Visible Reasoning and Activity Summaries
Chainabit does not expose raw private Chain-of-Thought as a public UI feature. Eligible Chao sessions can still show visible reasoning: concise, policy-approved steps that help a person follow the conversation while it runs. Visible reasoning is separate from operational activity and artifact events.
Visible reasoning preserves the familiar think → tool → think experience where the session supports it. A client may render a visible-reasoning step only when the event carries the approved disclosure marker, visible_reasoning_v1. Clients must discard unmarked or malformed reasoning payloads rather than recovering display text from tool input, tool output, or provider-specific fields.
Visible reasoning events
Use cot.* events for eligible-session visible reasoning. Keep their sequence relative to tool.* events so a person can understand which step preceded and followed a tool call.
| Event | Use |
|---|---|
cot.step | Add or update a short visible-reasoning step. |
cot.phase | Show a compact reasoning phase transition when supplied. |
cot.tool.reasoning | Associate a safe explanation with a tool card without rendering arguments or results. |
cot.completed | Mark the visible-reasoning trace complete. |
The payload is an intentionally small display model. It may contain a step ID, safe summary, display phase, timestamp, and the correlation ID of an already authorised tool card. It never grants access to a tool call or artifact.
Do not display, persist, export, or infer visible reasoning from raw model output, hidden prompts, provider payloads, credentials, signed links, or internal paths. If a summary cannot pass that policy, omit that individual step instead of replacing the whole eligible-session experience with generic status.
Operational activity and tool cards
Use these events for user-facing reasoning and tool cards:
| Event | Use |
|---|---|
capability.resolved | Show which capability was selected for a request |
plan.step_added | Add a planned write action to review UI |
tool.started | Open or update a tool card |
tool.progress | Update card detail/status text |
tool.approval_required | Show approve/reject controls |
tool.approval_response | Mark approval accepted or rejected |
tool.approval_timeout | Mark approval expired |
tool.completed | Mark the tool card completed |
tool.failed | Mark the tool card failed, but keep the run open |
tool.degraded | Show a graceful fallback state |
Normal chat text still comes from message.delta and message.completed. Artifact progress uses its own artifact.* and preview.* events; render it as artifact state, not as a reasoning step.
Tool Card Payload
Normalize tool-like payloads before rendering:
| Normalized field | Preferred lookup |
|---|---|
toolKey | payload.toolKey ?? payload.key |
callId | payload.callId ?? payload.toolCallId ?? envelope.stepId |
input | payload.input ?? payload.args |
output | payload.data ?? payload.output |
When payload.activity exists, render from it:
| Field | Meaning |
|---|---|
activityType | Activity category, such as tool_read, tool_write, approval, research, or image_generation |
origin | Producer, usually chao |
label | Short card title |
detail | Human-readable progress or result detail |
renderHint | Suggested card style, such as tool_card or status_card |
status | pending, active, completed, or failed |
subjectType | Domain such as bits, calendar, research, or media |
subjectId | Tool call ID or related subject ID |
Reload Behavior
Use persisted, policy-approved trace data to reconstruct visible reasoning after reload where the session supports it. Preserve the recorded order of visible reasoning, tool cards, and message content. Do not reconstruct reasoning from thinking.emit tool input or output.
Use persisted message.toolCalls to reconstruct tool cards after reload. Supported statuses include:
pending, executing, completed, failed, degraded, rejected, and skipped.
tool.failed is not terminal. Keep listening until you receive message.completed, message.partially_completed, run.failed, run.error, or run.settlement.completed.
Compatibility and fallback
Clients that do not implement visible reasoning may ignore the cot.* family without affecting messages, activity cards, or artifact cards. Clients that do implement it must preserve its ordering on live delivery and replay. A missing or rejected visible-reasoning step must not block a tool card, artifact card, or final message.