run.start | agentName: string, agentId?: string | First event of every run. |
step.start | step: number | A model step begins: one model call plus the tool calls it asks for. step counts from 1 (a run resumed from a checkpoint continues the count). |
text.delta | text: string | A chunk of model text, as it arrives. |
object.delta | object: unknown | Only for an agent with an output schema: the reply parsed so far, a best-effort partial object (an unfinished string value is cut where the text is; an unfinished key or number is left out). Follows a text.delta that changes it. Not validated; the validated object is run.done’s object. |
text.done | text: string | The step’s complete text: the concatenation of its text.delta events. Only for steps with text. |
reasoning.start | (none) | The model starts reasoning in this step. Only with the reasoning option (or a model that always reasons). Its reasoning.deltas and reasoning.done follow, before the step’s first text.delta or tool.start. |
reasoning.delta | text: string | A chunk of reasoning text (or of its summary). Never part of text.delta / run.done’s text. |
reasoning.done | text: string, tokens?: number | The reasoning ended: text is all of it; tokens when the provider reported reasoning tokens by then. When the model call fails after reasoning only and is retried, the failed attempt’s reasoning ends here, before the provider.retry event; the retry’s reasoning starts again with reasoning.start. |
tool.start | toolCallId: string, toolName: string, args: Record<string, unknown>, executedBy?: 'provider', parentToolCallId?: string | A tool call starts. args are the model’s arguments parsed from JSON ({} when they are not valid JSON). A call a code mode script made carries parentToolCallId, the run_code call’s id (also on its tool.partial, tool.done and tool.error). A hosted tool the provider ran inside the model call carries executedBy: 'provider'; it passed no permission rule, guardrail, approval or hook. Exactly one per tool call across a pause: a call that paused for approval (or sign-in) and then ran reports tool.resume on the continued run, not a second tool.start. |
tool.resume | toolCallId, toolName, args: Record<string, unknown> | The decided call of an approval continuation runs. Its tool.start was emitted by the run that paused; handle it like tool.start when you track calls. |
tool.partial | toolCallId, toolName, output: unknown, index: number | A snapshot of a running tool’s output: a tool whose execute is an async function* reports one per yield (see Streaming partial results). Each snapshot is complete and replaces the previous one; index counts the call’s snapshots from 0. The last one is also the call’s tool.done result. output is JSON-encoded like result. Snapshots never reach the model, the transcript, checkpoints or traces. A sub-agent’s carries subagent. |
tool.done | toolCallId, toolName, result: unknown, durationMs: number, replacedByHook?: string, executedBy?: 'provider' | A tool call returned. result is the value as it would be JSON-encoded (undefined becomes null, a Date becomes a string). durationMs counts from its tool.start / tool.resume. replacedByHook names the hook whose { result } outcome replaced (or stood in for) the tool’s result. A hosted tool call carries executedBy: 'provider' and its result is capped at 20,000 characters of JSON. |
todo.updated | todos: Todo[], counts: { pending, in_progress, completed, total }, toolCallId: string | A successful todo_write call of the todo tools replaced the list, right after that call’s tool.done. todos is the complete new list ({ id, content, status }), toolCallId the todo_write call. A sub-agent’s carries subagent. The UI bindings keep the list and show it live. |
tool.error | toolCallId, toolName, error: { name: string, message: string }, durationMs: number, executedBy?: 'provider' | A tool call failed: it threw, its arguments did not match its schema (name: 'ToolArgumentsValidationError'), or the tool does not exist. A hosted tool call the provider reported as failed carries executedBy: 'provider' and error.name is 'HostedToolError'. The model gets the error as the call’s result and the run continues. |
approval.requested | approvalId: string, toolCallId, toolName, args: Record<string, unknown>, kind?: 'question' | 'sign-in', question?: { text, options?, allowFreeText? }, signIn?: { provider, displayName?, url } | A tool call needs a human decision. The run then stops; resume it with agent.approvals.resolve() or resumeAfterApproval() (see Approvals), or stream the continuation (see Streaming after an approval). An ask_question call carries kind: 'question' and its question; answer it with agent.approvals.answer() (see Asking the user a question). A tool waiting for an OAuth sign-in carries kind: 'sign-in' and the link in signIn (see What the user sees). |
permission.decision | toolCallId, toolName, decision: 'allow' | 'deny' | 'ask' | 'default', rule?: { index: number, reason?: string }, reason?: string, hook?: string, mode?: 'plan' | 'acceptEdits' | 'dontAsk', args?: Record<string, unknown>, at: string | How a tool call’s permission rules decided it: after its tool.start, before the call’s own tool.done / tool.error / approval.requested. hook names the preToolCall hook that denied the call, reason why it (or the tool’s needsApproval) denied. Only when the run sets permissions or onPermissionDecision, or a permission mode other than 'default' (mode is set when the mode changed the outcome); args is left out under redactContent. |
step.done | step: number, finishReason: string, usage?: { promptTokens, completionTokens, totalTokens, inputTokens, outputTokens, estimated: boolean, costUsd?: number } | A step ends. finishReason is the model’s ('stop', 'tool_calls', 'length', …), or 'awaiting-approval', 'aborted', 'steered' (its model call was aborted by run.steer(), see Steering) or 'error' when the step ended that way (a run that runs out of maxSteps still wanting to continue ends with run.done 'max-steps'). usage is this step’s model call, absent when the call produced no response; promptTokens/completionTokens alias inputTokens/outputTokens, estimated is true when the provider reported nothing and the counts are an estimate, and costUsd is absent when no model used has a known price, and costPartial: true marks a costUsd that leaves out a call with unknown pricing. |
error | error: { name: string, message: string } | An error. If it ends the run, run.done with finishReason: 'error' follows. A provider error retried under surfaceRetryableProviderErrors is followed by further steps instead. |
provider.retry | attempt: number, maxRetries: number, delayMs: number, error: { message: string, category?: string }, provider: string | A model call failed and is retried after delayMs (createAgent({ retry }) or any withRetry() provider). attempt is the attempt that failed (1 = first); category is 'rate-limit', 'timeout', … and absent when unknown (a 5xx, for example). |
provider.fallback | from: string, to: string, fromModel?: string, toModel?: string, error: { message: string } | A model call still failed after its retries and the next provider takes over (createAgent({ fallbackModels }) or any withFallback() provider). from and to are provider names; fromModel and toModel are the model ids, which tell two providers of the same name apart (e.g. two OpenRouter models). |
compaction.start | strategy: string, tokensBefore: number, contextWindow: number, thresholdTokens: number, trigger?: 'manual' | The compaction hook (createAgent({ compaction })) found the next model request above its threshold and starts compacting it. Exactly one compaction.done follows. trigger: 'manual' marks a session.compact() call (see context.cleared). See Context compaction. |
compaction.done | strategy: string, appliedStrategy?: string, tokensBefore: number, tokensAfter: number, prunedToolCallIds: string[], summary?: boolean, error?: { message: string }, unchanged?: true, trigger?: 'manual' | A compaction ended. tokensAfter equals tokensBefore and unchanged is true when nothing could be compacted (later no-op attempts on the same transcript emit no events); summary is set when old turns were replaced by a summary; error is set when the strategy failed or fell back (the run continues); appliedStrategy names the strategy whose result was applied when it differs from strategy ('prune-tool-results' after a rejected summary). trigger: 'manual' marks a session.compact() call. |
heal.action | action: 'hint' | 'deny' | 'stop', toolName: string, reason: string, failure?: 'bad-input' | 'timeout' | 'missing-capability' | 'permission' | 'unknown' | A hook stepped in to get a run unstuck (see createProgressGuard()). |
context.cleared | sessionId: string, messagesCleared: number | session.clear() emptied a session’s transcript. Delivered to session.on() listeners, not to a run’s stream. compaction.start / compaction.done from session.compact() also reach session.on() and carry trigger: 'manual'. |
budget.exceeded | limit: string, value: number, max: number, scope: 'run' | 'session' | A limits budget tripped: limit is 'maxTokens', 'maxInputTokens', 'maxOutputTokens', 'maxCostUsd', 'maxDurationMs' or 'maxSteps', value what was spent, max the limit. run.done ('budget-exceeded') follows; with onExceeded: 'throw', error and run.done ('error'). |
input.queued | id: string, text: string | run.enqueue() took an input (id is EnqueueResult.id, text its user text). Can come at any point of the run, also inside a step. See Queued input. |
input.steered | id: string, text: string, mode: 'immediate' | 'queued' | run.steer() took an input (id is SteerResult.id). mode: 'immediate': the in-flight model call was aborted for it, and its step ends with step.done 'steered'; 'queued': it waits for the next safe point like enqueue(). See Steering. |
input.applied | id: string, step: number | The queued (or steered) input joined the transcript, right before the model call of step: the step.start of that step follows. |
guardrail.tripped | name: string, kind: 'input' | 'output' | 'tool', reason: string, toolName?: string, info?: GuardrailTripInfo (what tripped: types and offsets, never the matched text; see the starter set) | An input, output or tool guardrail blocked: before the first model call (input), before the step’s text.done (output) or after the call’s tool.start (tool). run.done ('guardrail') follows; with onTripped: 'throw', error and run.done ('error'). |
guardrail.rewrote | name, kind, reason, toolName?, info? | A guardrail rewrote the input, the step’s text (before its text.done, which carries the new text) or a tool call’s arguments. The run continues. |
agent.drift | model?: { from?: string, to?: string }, toolsAdded: string[], toolsRemoved: string[], toolsChanged: string[], instructions: boolean | A checkpointed or approval-paused run is being continued by an agent that differs from the one that saved it, and onAgentDrift is 'warn' (the default): what changed. Emitted right after the continuation’s run.start, before any step or tool event; the run continues. With 'error' the resume is refused with LOUSHO_AGENT_DRIFT instead and this event is not emitted. See Resuming with a changed agent. |
handoff | from: string, to: string, toolCallId: string | The run handed the conversation to another agent (Handoffs): after the handoff call’s tool.start / tool.done, before the target’s first step.start. The run’s steps from here on are the target’s; run.result.agentName names the agent of the final reply. |
run.done | finishReason: string, text: string, usage?: { promptTokens, completionTokens, totalTokens, inputTokens, outputTokens, estimated: boolean, costUsd?: number, modelCalls?: number, hostedToolCalls?: { [tool: string]: number } }, object?: unknown | Last event of every run, exactly once, including aborted, failed and awaiting-approval runs. finishReason and text match run.result ('max-steps' when the maxSteps budget ran out while the model still wanted to continue); a failed run has finishReason: 'error', text: '' and no usage. usage is the whole run’s: modelCalls counts its model calls and hostedToolCalls the hosted tool calls the provider ran per tool name (their fees are not in costUsd). object is run.result’s validated object for an agent with an output schema (see Structured output), absent otherwise. |