Skip to content

Events ​

A turn is an async iterable of AgentEvents. thread.subscribe() sees every event on the thread, including turns the agent starts by itself, as Claude does when a background subagent reports back.

All event types ​

AreaEvents
Turnturn.started, turn.completed, turn.failed
Texttext.delta, text.done, reasoning.delta, reasoning.done
Toolstool.input.progress, tool.started, tool.output.delta, tool.progress, tool.completed
Filesfile.changed, diff.updated
Plansplan.updated, plan.proposal.delta, plan.proposal.done
Background workstatus, task.started, task.progress, task.ended, subagent.started, subagent.ended
Requestsrequest, request.resolved
Usage and modelsusage, rate-limit, compacted, model.rerouted, model.confirmed, service-tier.updated
Runtimenotice, hook.started, hook.completed, goal.updated, mcp.status, thread.renamed, settings.updated, prompt.suggestion, realtime.*

engine.subscribe() gets the events that belong to no thread: account.changed and notice (a config warning, a deprecation). Only Codex sends these today. Claude and ACP engines accept a listener, but it never fires.

The union grows in minor releases. A switch on event.type should have a default branch rather than an exhaustive check that fails to compile when a new member arrives.

Events from a subagent carry its agentId.

Requests ​

A request is an approval, a question (Claude's AskUserQuestion, Codex's user-input request, an ACP agent's multiple-choice question) or an MCP elicitation. Call its respond once. An unanswered request is cancelled when the turn ends.

A Codex file-change approval carries the proposed changes, with diffs, so the user can review them before allowing.

Codex approvals can carry more:

  • decisions lists the plain answers Codex offers for this request. When it's missing, all four are fine.
  • network names the host when the command needs network access.
  • rules are lasting rules Codex offers to save: allow later commands that start with a prefix, or allow or block a host. Answer with one of them as rule: { decision: "allow", rule }, or { decision: "deny", rule } for a rule that blocks a host. A rule Codex didn't offer, or with the other decision, is refused.
  • A permissions request can be granted in part: { decision: "allow", grant: { network: true } } grants the network and refuses the file-system access. strictReview: true has Codex review every later command in the turn.

File changes ​

file.changed lists the files one tool call changed, from the main agent or a subagent (tagged with its agentId): Codex's apply_patch edits, and Claude's Edit, MultiEdit, Write and NotebookEdit.

Each diff is unified hunks with no ---/+++ header, the same from both runtimes. A new file is all + lines, a deleted one all -, and a Codex move names the new path in movedTo. Neither runtime reports files a shell command writes.

Text phases ​

Codex marks each agent message's phase on text.delta and text.done: commentary for a progress note between tool calls, answer for the reply. Claude's text events have no phase. A turn's result text is never a progress note.

Live progress ​

These events are for showing work as it happens. None of them changes a turn's result: tool.completed still carries the whole output and turn.completed the reply.

EventCodexClaude
tool.input.progressNot sentA tool call's name as the model starts writing it, then the running characters of its input about every 2,000 characters. tool.started follows with the same itemId once the input is complete, which for a large Write can be minutes later
tool.output.deltaCommand output as it streamsNot sent; the SDK doesn't stream command output
tool.progressMCP tool progress messageelapsedSeconds of a running tool
diff.updatedThe turn's whole unified diff so far, replacing the last oneNot sent; use file.changed
plan.updatedThe checklist, whole each time, with an optional explanationEach TodoWrite list, with itemId of the call
plan.proposal.delta / .doneA plan streamed in plan mode; .done has the final text.done with the plan when Claude asks to leave plan mode
statusFrom the thread status: working, waiting (with waitingOn), idle; also compacting and retryingworking, compacting, retrying with attempt and delay
task.started / task.endedNot sentBackground shells, monitors, workflows and MCP tasks
task.progressNot sentThe same tasks, and subagents (taskId is the subagentId)
ts
thread.subscribe((event) => {
  switch (event.type) {
    case "tool.output.delta": appendToTerminal(event.itemId, event.delta); break;
    case "plan.updated": showChecklist(event.steps); break; // { step, status: "pending" | "in-progress" | "completed" }
    case "status": showStatus(event.status.state); break;
    case "task.progress": showTask(event.taskId, event.summary ?? event.description); break;
    default: break;
  }
});

Limits worth knowing ​

  • status is a hint for a status line, not a turn lifecycle. Use turn.completed and turn.failed for that. A Codex idle usually arrives after turn.completed, so it reaches thread.subscribe but not the turn's iterator.
  • Claude reports idle and waiting only through session-state events, which the SDK sends when a session opts in. The engine doesn't opt in, so from Claude expect working, compacting and retrying. A pending request is the sign it's waiting.
  • retrying means the runtime will try the model request again. The turn has not failed.
  • When a finished subagent begins another turn, it reports subagent.started again with the same subagentId, then its own subagent.ended. Queuing a Codex message without waking the subagent doesn't start it. From Claude, prompt on that second start is the new message, and older run IDs can't change the current run.
  • A task a subagent launched carries that subagent's agentId. task.ended needs the task.started from the same thread handle, so a task begun before a resume doesn't end on the new handle.

Released under the MIT Licence. Not affiliated with OpenAI, Anthropic or the ACP project.