Hooks attach your own command or prompt to moments in the agent loop, so you can log activity, veto a risky tool call, add context at the start of a session, or push the agent to keep going when it tries to stop. They run in Work and Code tasks on the desktop app. Command hooks never run in cloud runs and are not available on the web.
| Phase | Events |
|---|---|
| In a turn | PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStop, Stop |
| Start | SessionStart, SubagentStart |
ZeroTwo has no SessionEnd or Interrupt event. Every hook whose matcher fits an event runs, one after another in the order configured.
Where hooks come from
Your own hooks live in ~/.zerotwo/hooks.json. Hooks bundled with the plugins you have enabled are picked up too. Open Settings > Coding > Hooks to see both lists: From Config for your file and From Plugins for plugin hooks. Each source can be opened to switch individual hooks on or off, and the refresh button rereads the file.
Review and trust hooks
A command hook in your config does not run until you trust it. Settings marks hooks that need attention with a "need review" count, and trusting one records a hash of what will execute. Changing the command, the Windows command, the shell, the timeout or the async flag invalidates that trust and the hook is skipped until you approve it again. Hooks brought in through Settings > Import arrive disabled and untrusted. Prompt hooks run no shell command, so they are not gated this way.
Config shape
The file nests events, then matcher groups, then handlers:
{ "hooks": { "SessionStart": [ { "matcher": "startup|resume", "hooks": [{ "type": "command", "command": "python3 ~/.zerotwo/hooks/session_start.py", "timeout": 30 }] } ] } }
Handler fields worth knowing:
typeiscommandorprompt. Acommandhandler runs a shell command; aprompthandler asks a small model to judge the event and return the same JSON a command would print.timeoutis in seconds. The default is 30 and the desktop caps it at 300.commandWindows,shell,name,descriptionandstatusMessageare optional, andasync: trueruns a command in the background.- A
prompthandler can reference${TOOL_NAME},${TOOL_INPUT},${TOOL_RESPONSE},${PROMPT}and${INPUT}in its text. - Commands start in the task's own working folder and environment, under the same sandbox and approval rules as other local commands. On macOS that includes the OS sandbox; on Windows and Linux there is no OS sandbox.
Matcher patterns
matcher is a |-separated list of exact names or a regular expression; "*", an empty string or no matcher matches everything. For tool events it filters on the tool name, for SessionStart on the start source (startup, resume, clear or compact), for the compaction events on the trigger (manual or auto), and for the subagent events on the agent type. UserPromptSubmit and Stop have no matcher.
ZeroTwo names its shell tool exec_command and its file editor zerotwo_apply_patch. A matcher of Bash also catches shell calls, and Edit, Write or MultiEdit also catches file edits, so hooks written for other agents keep firing.
Common input fields
A command hook is handed a single JSON object on stdin containing hook_event_name, session_id, cwd, model and transcript_path, which is currently always null. Turn events add turn_id, and every event except the compaction pair adds permission_mode. Tool events carry tool_name and tool_input; PostToolUse adds tool_response. UserPromptSubmit carries prompt, the subagent events carry agent_id and agent_type, and Stop and SubagentStop carry last_assistant_message and stop_hook_active.
Common output fields
Exit 0 with no output means success. Exit 2 blocks the action and sends stderr back as the reason; any other non-zero exit is logged and ignored. If stdout starts with {, it is read as JSON. continue: false stops the run (with an optional stopReason) and systemMessage shows a warning. Plain text on stdout becomes extra context for UserPromptSubmit, PostToolUse, SessionStart and SubagentStart.
When several hooks answer the same event, a deny beats an ask and an ask beats an allow.
Large hook output
Background hook output above roughly 2,500 tokens is written to a file in the system temp folder and replaced by a head-and-tail preview that points to the file. Keep hook output short regardless, because it consumes context.
Treat hooks as guardrails, not a hard security boundary. A hook that fails to start, times out or errors does not stop the operation; only an explicit block does.
Run hooks in the background
Set "async": true on a command handler to avoid blocking the triggering operation. The output is delivered once the run reaches its next safe point, and a background hook cannot block, approve or rewrite anything. Up to eight background hooks run at once per task. A hook that must gate a tool, permission or prompt has to stay synchronous.
Hooks
Event specifics follow.
SessionStart
Matches the start source. Plain stdout or additionalContext is added to the model's context.
SubagentStart
Matches agent_type. Its additionalContext goes to the subagent.
PreToolUse
Can deny a call with permissionDecision: "deny" and a reason, with the older decision: "block", or by exiting 2 with a message on stderr. permissionDecision: "allow" can carry an updatedInput object that replaces the call's arguments, and "ask" hands the decision back to the normal approval prompt.
{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Blocked." } }
PermissionRequest
Runs just before an approval prompt. Return decision.behavior of allow or deny with an optional message inside hookSpecificOutput, or nothing to leave the prompt as it is. The fields interrupt, updatedInput and updatedPermissions are reserved, and using them is treated as a deny.
PostToolUse
Runs after a tool returns and receives tool_response. It cannot undo what the tool did. decision: "block" or exit 2 surfaces your feedback, and additionalContext adds notes for the model.
PreCompact
Matches the trigger (manual or auto) and fires before older context is summarized.
PostCompact
Matches the same triggers and fires after the summary is in place.
UserPromptSubmit
Receives the prompt. Stdout or additionalContext adds context, and decision: "block" or exit 2 rejects the prompt.
SubagentStop
Receives the final subagent message and stop_hook_active. decision: "block" with a reason makes the subagent do another pass.
Stop
decision: "block" does not discard the turn. It tells the agent to keep working, using your reason as the next instruction, so check stop_hook_active to avoid looping forever. continue: false from any hook outranks continuation.