Hooks

Hooks are commands pw code runs automatically on lifecycle events: before a tool call, when you submit a prompt, when a session ends, and around thirty other moments. A hook can observe what the agent is doing, block an action, or rewrite it. Use them to audit shell commands, enforce a policy the agent cannot talk its way past, format files after every edit, or send a notification when a long run finishes.

A hook handler can be a shell command, an HTTP endpoint, an MCP tool, or an LLM prompt.

Configuring Hooks

Hooks live under a top-level hooks key in a settings file, keyed by event name. Each event holds a list of matcher groups, and each group holds a list of hook definitions:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.config/agents/hooks/bash-audit.sh", "timeout": 5 }
        ]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "prompt", "prompt": "Are the tests green? $ARGUMENTS" }] }
    ]
  }
}

Edits take effect on the next run, or immediately with /hooks reload.

Matchers

matcher selects which occurrences a group runs for, by testing the payload field named in the Matcher column of the event table. Matching is case-sensitive.

Names may contain letters, digits, _, -, and spaces. Add ^ and $ to a regular expression to anchor it.

Where Hooks Are Configured

Hooks are read from these files, from lowest to highest priority:

The local file sits at the repository root (in a git worktree, the main checkout's root), not in each subdirectory you start in. .mcp.json supplies MCP servers only and is never read for hooks.

~/.config/pw/code.json is seeded on first access from ~/.config/agents/settings.json. Most settings are read only from code.json after that seed, but hooks, disableAllHooks, and allowedEnvVars are always read live from ~/.config/agents/settings.json too, so a hooks block kept there keeps working.

Two keys are honored from the user layer only. A project or local file that sets them is warned about and ignored, so a cloned repository cannot weaken your guards or exfiltrate secrets:

• disableAllHooks: true turns every hook off.
• allowedEnvVars: ["MY_TOKEN", …] names the environment variables an HTTP hook may interpolate into its headers. Referencing any other variable is a loud error, never a silent empty value.

Project Hooks Must Be Trusted

Project and local settings ship with a repository, so their hooks are arbitrary code written by whoever authored the clone. They stay inert until you trust the exact configuration:

1. Run /hooks and review the pending hooks, marked untrusted.
2. Run /hooks trust to enable them for this workspace.

Trust covers the project and local hook definitions only. Any change to them, including one you did not make, such as a teammate's commit, re-gates them until you review and trust again. Edits to other settings in those files do not. This is separate from the workspace trust prompt at launch, which does not enable hooks. User-level hooks are always active and never need trusting.

Handler Types

"async" is only valid on command hooks, and is ignored with a warning on PreToolUse and PermissionRequest: those hooks always run synchronously, since an async guard could never block.

All hooks matched by one event run in parallel.

Timeouts

The default timeout is 600 seconds. Shorter defaults apply to SessionEnd (30s), UserPromptSubmit (30s), and MessageDisplay (10s), and LLM-backed handlers are capped further: prompt hooks at 30s and agent hooks at 60s, or the event default if that is shorter. Set "timeout" in seconds on any hook to override. On timeout, a command hook's entire process group is killed.

Hook Input

Every payload is a JSON object with a common envelope plus event-specific fields. All field names are snake_case.

tool_use_id is omitted when the provider gave no ID.

Hook Output

Exit Codes

Output beyond 100 KB is cut off. Reply JSON that cannot be parsed, including JSON cut off at that limit, is reported as an error rather than treated as a clean pass.

Reply JSON

permissionDecision takes precedence over the nested decision object and over the top-level decision field. permissionDecision: "defer" is treated as "ask" with a notice. suppressOutput is accepted but has no effect.

When several hooks answer the same event, deny beats ask, which beats allow; any block blocks; every additionalContext is kept; and if more than one rewrites the input, the hook that finished last wins. A rewritten tool call is re-checked by the permission engine rather than trusted as-is.

What Each Decision Does

Supported Events

Every event below is valid in configuration and appears in the /hooks browser. Dormant events parse and list but never fire yet, because the feature they depend on does not exist in pw code. Configuring one warns at startup, so a guard that can never fire is never mistaken for an armed one.

Ten events are dormant, and /hooks explains why for each:

Reviewing Hooks

• /hooks opens an interactive browser: an arrow-navigable event list, then matcher groups, then hooks, then hook detail. It shows each hook's type, timeout, and source file, tags dormant events, marks untrusted project hooks, and lists recent hook activity. Non-interactive -p runs print a text listing instead.
• /hooks trust enables the project hooks you just reviewed for this workspace.
• /hooks reload re-reads every settings file mid-session. Project hooks still need trust.

Behavior Notes and Limits

• FileChanged fires only for pw code's own WriteFile and EditFile edits. There is no filesystem watcher, so edits made by a shell command the agent ran do not trigger it.
• ConfigChange reports in-app changes with the sources model, permission_mode, and allowlist. Settings files are not watched; run /hooks reload after editing one.
• The per-hook fields if, statusMessage, once, shell, and asyncRewake are accepted but not implemented. Each is warned about and ignored, so an if-narrowed hook runs on every matched occurrence and an asyncRewake hook never wakes the agent.
• An http hook refuses cross-origin redirects, since following one would forward your custom secret headers to a host you did not configure.

Related Documentation

• Skills: Packaged instruction sets invoked by you or the agent
• Settings: Settings files and workspace trust
• Permissions: Permission modes and allow rules
• MCP Servers: Connect MCP servers, including servers a mcp_tool hook can call
• Non-Interactive Mode: One-shot runs, where guards fail closed