Hooks

Runs when a run starts (source startup or resume) and again after a compaction (source compact); return strings to add them to the model's context as untrusted reference. A throw or timeout refuses the run with input_denied. Omit it and nothing runs at session start.

Why the session started: "startup" for a thread's first run, "resume" for a later run on a thread that already has input, "compact" after the context was compacted. "fork" is in the contract but is not passed today.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Observes the end of a run that finished without halting. It can't change anything; a failure is recorded and ignored. Omit it and nothing runs at session end.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Gates each turn's user input before the first model request. Return allow (optionally with injections) or deny with a reason; a deny, throw or timeout ends the turn input_denied. Omit it and every input is let through.

The user input the turn starts with, as recorded in the log.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

allow: the input goes on to the model, with this hook's injections (if any) added before the request.

Recorded as injected{source: hook} events; not a decision.

deny: the input stays in the log for audit but is never sent to the model, and the turn ends input_denied.

Why, as any text. It is recorded on the hook_decision; the model never sees it.

Runs before every model request. Return proceed (optionally with injections) or deny with a reason; a deny, throw or timeout means the request isn't sent. Omit it and every request is sent.

The thread's reduced state at this point, the same value reduce(log) returns.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

proceed: the request is sent, with this hook's injections (if any) added first.

Recorded as injected{source: hook} events; not a decision.

deny: this attempt is never sent to the model, and the turn ends error.

Why, as any text. It is recorded on the hook_decision; the model never sees it.

Reviews each model response before its tool calls run and its output is released. Return proceed, deny (the output is withheld and its calls are closed unrun), guide (the model is asked again with your text) or retry (asked again with the reason, at most twice per turn). Omit it and every response proceeds.

The thread's reduced state at this point, the same value reduce(log) returns.

The model's response: its content parts (text and tool_use), usage and the request it answers.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

proceed: the response stands; its tool calls go on to be authorized and run, or the turn ends as the response says.

deny: the response's output is withheld and each of its tool calls is closed as denied without running. The turn ends error; in TypeScript, a response that had tool calls instead goes back to the model with each call shown as denied.

Why, as any text. It is recorded on the hook_decision. TypeScript shows it to the model on each closed call (denied: reason); Python shows a fixed text.

guide: the response is withheld, its tool calls are closed without running, and the model is asked again with text as a trusted instruction.

The instruction the model is re-asked with, as any text. It is recorded on the hook_decision and added to the next request as a trusted hook instruction.

retry: like guide, with reason as the instruction. After 2 retries in one turn, a further retry counts as a deny.

What to do differently, as any text. It is recorded on the hook_decision and sent to the model as a trusted hook instruction.

Runs before the permission decision on every tool call, even one the policy denies (the deny stands). Return allow, deny with a reason, or ask to require approval; when several extensions answer, the strictest wins, and a throw or timeout denies. TypeScript stops at the first extension that denies, so later ones aren't called; Python calls every extension. Omit it and the agent's permission rules decide alone.

The tool call: its call_id, tool name, parsed input and the request it came from.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

allow: this hook doesn't object. The policy's decision stands; a hook can never loosen a policy ask or deny.

deny: the call is refused and never runs. It closes as a denied tool_result the model sees, and permission_denied observers are told.

Why, as any text. It is recorded on the hook_decision and kept on the call's permission_decision. TypeScript shows it to the model in the denied tool_result (denied: reason); Python shows the fixed text denied by policy.

ask: the call needs approval. permission_request hooks may answer it; otherwise it opens an approval challenge and parks until an approver decides. In dont_ask mode an ask is a deny.

A permission rule to show with the ask, such as bash(git push *). It is recorded as the reason on the hook_decision and on the permission_decision. Omitted: the ask carries no reason.

Answers a tool call the permission rules would send for approval. Return allow or deny to decide it, or ask to leave it to a human; a throw or timeout denies. Omit it and the call waits for a human approval.

The tool call: its call_id, tool name, parsed input and the request it came from.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

allow: the programmatic approver grants the call, so it runs without asking a person.

deny: the programmatic approver refuses the call; it closes as a denied tool_result the model sees.

Why, as any text. It is recorded on the hook_decision and kept on the call's permission_decision. TypeScript shows it to the model in the denied tool_result (denied: reason); Python shows the fixed text denied by policy.

ask: the hook doesn't answer, so the call opens an approval challenge and parks until a person decides.

Recorded as the hook_decision's reason only: an ask answers nothing, so the earlier decision and its reason stand. Omitted: no reason is recorded.

Observes a tool call after it was denied. It can't change anything; a failure is recorded and ignored. Omit it and denials are only recorded in the log.

The tool call that was denied: its call_id, tool name, parsed input and the request it came from.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Observes each tool result after it is recorded. Return strings to record them as an annotation on the call; it can't change the result, and a failure is recorded and ignored. Omit it and results are recorded with no annotation.

The tool call: its call_id, tool name, parsed input and the request it came from.

The tool's recorded result for that call.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Guards each executed tool result before later requests render it. Return proceed, redact with byte spans of the result's text to hide, or deny to clear it; the raw result stays in the log either way, and a throw, a timeout, an empty span list or a span outside the text clears it. Omit it and results are rendered as recorded.

The tool call: its call_id, tool name, parsed input and the request it came from.

The tool's recorded result for that call, as later requests render it unless a hook changes it.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

proceed: later requests render the result as it is.

redact: the listed spans are hidden from every later request, recorded as context_edited guardrail. The raw result stays in the log.

The byte ranges to hide, as UTF-8 offsets into the result's first text part (the preview when it has no content), start inclusive and end exclusive; give at least one, each non-empty. An empty list, an empty span, a span outside that text or a span that splits a character counts as a failed hook, so the whole result is cleared instead.

deny: the whole result is cleared from every later request (context_edited guardrail). The call already ran; the raw result stays in the log.

Why, as any text. It is recorded on the hook_decision; the model sees the cleared result, not the reason.

Runs once every tool result of a model response is recorded, before the next request. Return strings to add them to the model's context as untrusted reference; a throw or timeout ends the turn with an error. Omit it and the next request is sent with nothing added.

The thread's reduced state at this point, the same value reduce(log) returns.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Runs before the context is compacted. Return proceed, guide with text the summary request should follow, or deny with a reason, which fails this compaction; a throw or timeout also fails it. Omit it and compaction proceeds with the default instructions.

The thread's reduced state at this point, the same value reduce(log) returns.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

proceed: compaction goes ahead: older turns are summarized by a side request.

deny: no summary is made this time, recorded as compaction_failed at stage hook.

Why, as any text. It is recorded on the hook_decision; the model never sees it.

guide: compaction goes ahead, and text is added to the summary request's instructions.

Extra instructions for the summary, such as what to keep, as any text. They follow the fixed summary instruction under Additional instructions.

Runs after a compaction, before the next request. Return strings to add them to the model's context as untrusted reference; a failure is recorded and adds nothing. Omit it and only the framework's own restored context is added.

The thread's reduced state right after compaction.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Runs when a turn is about to end normally. Return stop to let it end, or continue with a reason that is sent to the model as an instruction for one more request; after 3 continues in a turn it ends stop_hook_limit, and a throw or timeout stops. Omit it and turns end when the model stops.

The thread's reduced state at this point, the same value reduce(log) returns.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

stop: the turn ends end_turn as the model intended.

continue: the turn doesn't end. The model is asked again with reason as a trusted instruction. After 3 continues in one turn it ends stop_hook_limit.

What the model should still do, as any text. It is recorded on the hook_decision and sent to the model as a trusted hook instruction.

Observes a turn that ended in a failure, such as max_turns, max_output or a model error; on_stop doesn't run then. It can't change anything, and a failure is recorded and ignored. Omit it and failures are only recorded in the log.

The run error code the turn ended with: context_exhausted, model_unavailable, max_output, max_turns, output_invalid, input_denied or model_error.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Gates each spawn of a child agent before it starts. Return allow, or deny with a reason and the child isn't started; a throw or timeout denies. Omit it and every spawn the permission rules allow starts.

The spawn tool call: its call_id, tool name, parsed input (which agent and what task) and the request it came from.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

allow: the subagent starts (agent_spawned).

deny: the subagent never starts. The spawn call closes as a denied tool_result the parent's model sees.

Why, as any text. It is recorded on the hook_decision. TypeScript shows it to the parent's model as the denied result; Python shows a fixed text.

Runs when a child agent finishes. Return stop to let its result stand, or continue with a reason that is sent to the child as new input; after 3 continues, or if the child was cancelled, the result stands, and a throw or timeout stops. Omit it and each child's result stands as it finished.

How the child finished: its status and its final output or error.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

stop: the subagent's result stands and goes back to the parent.

continue: the subagent runs again with reason as its next input. After 3 continues, or when the subagent was cancelled, its result stands.

The subagent's next input, as any text. It is recorded on the hook_decision. When the continue can't take effect, TypeScript records a stop instead (reason cancelled, or continuation limit after 3 continues); Python records this continue and its reason even when the subagent was cancelled, and after 3 continues doesn't call the hook at all.

Gates an automatic model switch: the switch to a fallback model after repeated overloaded rejections (retry.fallback_after) and, with fallback_scope turn, the revert at the next input. Return allow, or deny with a reason to stay on the current model; a throw or timeout denies. Thread.setModel doesn't run it. Omit it and every automatic switch is allowed.

The model settings the thread would switch to.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

allow: the switch to the fallback model goes ahead (settings_changed with reason fallback).

deny: no switch to the fallback model. TypeScript keeps retrying the current model; Python ends the turn model_unavailable.

Why, as any text. It is recorded on the hook_decision; the model never sees it.

Observes a model switch after it is recorded. It can't change anything; a failure is recorded and ignored. Omit it and switches are only recorded in the log.

The model settings the thread switched to.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).

Observes notable events as they are recorded: the branch parked or a retry wait began, and in TypeScript also a budget was exceeded or a child agent finished. It can't change anything; a failure is recorded and ignored. Omit it and those events are only in the log.

The event that was just recorded, exactly as it is in the log.

The run's context: thread id, branch and the agent's deps (in Python, hooks always get deps as None).