Primary navigation

Hooks

Trigger scripts or MCP tools at set points in the ZeroTwo lifecycle

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.

PhaseEvents
In a turnPreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStop, Stop
StartSessionStart, 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:

  • type is command or prompt. A command handler runs a shell command; a prompt handler asks a small model to judge the event and return the same JSON a command would print.
  • timeout is in seconds. The default is 30 and the desktop caps it at 300.
  • commandWindows, shell, name, description and statusMessage are optional, and async: true runs a command in the background.
  • A prompt handler 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.