Hooks reference

What each warden hook does, what it allows and blocks, and the exact messages it shows.

A hook is a small program Claude Code runs at fixed moments, for example before a tool call. warden's hooks keep the run on track: they stop the agent from skipping steps, writing warden's own files, or pushing before the gates pass. They catch the usual shortcuts; they are not a sandbox.

The hooks#

Each hook runs bin/warden hook <event>.

Rules for all hooks#

• They never break a session. A hook always exits 0. An internal error goes to hook-errors.log in the data folder, and the tool call or prompt goes on.
• Only in set-up projects. Outside a git repo, a hook does nothing. In a repo without .warden/warden.json, session start prints warden: not set up here. Run /warden:init. and the other hooks do nothing.
• Bun missing. When Bun is missing or older than 1.4, session start prints warden: Bun is not installed, so warden is off. ... (or Bun <v> is too old (need 1.4 or newer)), and every hook exits 0 without doing anything.
• The reviewer is left alone. Inside the review gate's reviewer (WARDEN_ROLE is set), every hook does nothing.
• Session records. The hooks keep one record per session (and per subagent) in .warden/state/_sessions/. A record notes the task the session works on and whether Claude Code was started with PROJECT_AGENT=1. It is how warden knows which run a later call is about. A Bash command cannot change it.

SessionStart#

Runs when a session starts, resumes, is cleared or compacted. It adds lines to the agent's context. Each line starts with warden:.

What it does:

1. Writes two pointer files so Bash calls can find the plugin and its data folder (see environment).
2. For each live run, adds a line and restarts its engine worker if it died.
3. Adds the upgrade and new-version notices, the checks lines, the orchestration lines and the report lines below.
4. Starts due auto command checks in the background (not while a live run uses the main checkout as its worktree).
5. Starts a background report sync when the last one is more than an hour old, or a report is still unsent and the last try is more than a minute old.

The lines it can add:

Session start never writes a tracked file.

UserPromptSubmit#

Runs on every prompt you type. It never blocks a prompt. It links the session to its run, and it acts on a few words.

Approve, reject, retry#

The prompt must be one of these forms (case does not matter):

Without a task id, warden picks the session's run, or the only live run, or the only run that needs this action. If several runs need it, it says: warden: several runs wait for this (<tasks>); type "<word> <task>".

The agent then gets one of these lines in its context:

Answers to warden ask#

When a run waits for the answer to warden ask, any prompt that is not a slash command is the answer. The run is active again, and the agent gets: warden: <task> continues at <step>. The user's answer is in this message.

With several live runs, start the answer with the task id: PG-012: yes, keep the old route or answer PG-012 yes.

PreToolUse#

Runs before Edit, Write, MultiEdit, NotebookEdit and Bash. A denied call shows the agent a reason that starts with warden:, and is logged as a hook.denied event on the run.

Edit, Write, MultiEdit, NotebookEdit#

The rules are checked in this order. The first match decides.

A file in <dir>/.worktrees/<task>/ belongs to that nested worktree, never to a run whose worktree is <dir> (such as a run in the main checkout started without --worktree).

So at a check, review or approve step, no file in the task worktree can be edited. An approve step that waits, or a blocked run, still has a current step, and the same rule applies.

Bash#

Rules, in order. The first match decides. warden reads the command text; a heredoc that feeds warden done or warden report is skipped, because it is data.

B5 and B6 apply only when the call is about a run (the session's run, or the run of a folder the command cds into or names with git -C). Outside any run, push and merge are not checked.

What counts as push, PR or merge:

• git push (any branch)
• gh pr create, gh pr merge
• az repos pr create, az repos pr update
• glab mr create, glab mr merge
• <path>/pr.ts create|merge
• warden tools <name> create|merge, where <name> is pr, the tool the pr role names, or another role that names that tool
• git merge into the main branch: the command switches to the main branch, or runs in a checkout that is on it

Session links#

The pre-tool-use hook also notes which task a session works on. A warden start|next|done|wait|ask command links the session to the task it names (or the run of the folder it cds into). A warden orchestrate plan|status <epic> command marks the session as the orchestrator of that epic.

Stop#

Runs when the agent wants to end its turn. While the session's run is active, it keeps the turn going:

warden: <task> is at <step> and needs you. Run: warden next (or warden wait while a gate runs). At an agent step, if you need the user, run warden ask "<question>" and end your turn.

It lets the turn end when:

• the run is not active (it waits, is blocked, shipped or done),
• the session is orchestrating an epic,
• at an agent step with no engine work pending, the agent's last message ends with a question mark,
• at a fix step, the warden:fixer agent has not returned yet,
• it already blocked 3 times in a row. It then lets the turn end with: warden: stopping although <task> is active; type "continue" to resume.

Before it blocks, it restarts a dead engine worker, so warden wait has something to wait for.

SubagentStop#

Runs when a subagent ends. It links the subagent's own transcript to the task, so its tokens count for that task in summary.json and on the site. It never blocks.

See also#

• How warden works
• For agents
• Environment
• Blocked and waiting runs
• Team setup
• Troubleshooting