Session Events

Coding sessions forward the five Agent events and add queue_changed, context_budget, compaction_start, compaction_end, prompt_timing, agent_settled, session_title, permission_changed, approval_requested and approval_resolved. Consumers send commands through instance methods and receive results through subscriptions.

Subscribe

Given an existing session:

const unsubscribe = session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }

  if (event.type === "agent_settled") {
    console.log("\nOutcome:", session.state.outcome);
  }
});

try {
  await session.prompt("Hello!");
} finally {
  unsubscribe();
}

See the full SDK sample for construction and cleanup. It only prints text deltas, so waiting and tool-only turns can be silent; the CLI separately renders activity status.

Event reference

Event	Use
message_start	Begin a message or assistant draft.
message_update	Consume the original model stream update carried in assistantMessageEvent.
message_end	Display a completed message; this is not a disk-save acknowledgement.
tool_execution_start	Show the tool name/call ID and pending execution.
tool_execution_end	Show the matching result and isError.
prompt_timing	Carries timing: PromptTiming at prompt start and generation end; upsert by id when present, otherwise by userMessageIndex for legacy records. Resume starts a new attempt with its own ID and message range. Completion precedes saving and does not imply success or a durable save.
context_budget	Carries the complete estimated input and response reserve before every main request, including rejected requests and tool continuations. See context budget.
compaction_start	Automatic summarization started within a prompt; carries startedAt and live historyMessageCount.
compaction_end	Automatic preparation finished; carries optional saved checkpoint ID/boundary/count/time and optional error. Summary text and usage are not broadcast. A generation error can still allow the main request when its input fits.
agent_settled	An accepted prompt's execution and save attempt have finished. Inspect outcome and pending-save state.
session_title	Title display changed or generation failed; carries title and optional error. May arrive after a run settles.
permission_changed	Managed permission selection saved; carries permissionPreset. No prompt run ID is needed.
approval_requested	Carries the approval request snapshot. Can occur outside a prompt and may resolve immediately.
approval_resolved	Carries the request and final outcome in result; removes the matching pending request.

Approval events are paired by request ID, including unavailable, rejected and cancelled outcomes. A normal event subscription does not make approval available: a trusted host must explicitly register an interaction handler. See approvals for registration, decision submission, timeout and lifecycle behavior.

The initial fallback title is published immediately and again after saving; a title event alone is not a history-save acknowledgement. Title errors are exposed separately in state.titleError and never change the main run outcome. See session titles.

agent_settled fires for accepted prompts even when model preflight fails. Validation failures before acceptance, such as a concurrent prompt, do not start a run or emit it. Model switching and flushing do not emit prompt lifecycle events.

state.activeCompaction exposes transient automatic activity and clears on completion, cancellation or failure. The prompt remains running, preserving its run identity, Stop behavior and reconnect timing. Manual compaction continues using the host command lifecycle. A compaction end event does not mean the prompt has settled or that its final response has been saved.

Completed messages and drafts

state.messages is completed history; state.draft is the current assistant partial. Draft state clears at assistant completion and run finalization. On explicit Stop, coding-agent emits message_end for retained partial text marked aborted before the completed prompt_timing event and save; unfinished tool calls and thinking are excluded from that snapshot. Do not append every delta into a persistent message list.

agent_settled means stopped, not necessarily successful or saved. state.outcome is success, error, or cancelled after finalization; hasPendingSave reports retained unsaved history. prompt() still rejects on failure, so handle its promise as well as events.

Listener isolation

Each session listener receives its own cloned event. Session callbacks are invoked synchronously, but returned promises are not awaited. Thrown/rejected listener errors are recorded in state.listenerErrors without failing the run. That list is cumulative for the session; asynchronous listener work can finish after prompt() settles.

Subscriptions belong to one session instance. Rebind them when AgentSessionRuntime replaces that instance. Unsubscribe when the host no longer needs updates.

Source

For independently persisted execution records, see telemetry. Session subscriptions alone are not durable logging.

session types, agent-session.ts, agent-session.test.ts, and interactive output.

Queue Changes

queue_changed signals an input or scheduling change. Read state.queue, state.canResume and state.isRunning. The snapshot owns message bodies; events do not duplicate them. See message queue.