Hooks Author

Hooks Author

The hooks extension lets a user drop a shell script at a tool-call (or session) boundary without writing TypeScript. This skill teaches WHEN a hook is the right tool, which event to pick, and how to shape the script so the runner reads the response correctly.

Reference: config/pi/extensions/hooks.md is the full spec (schema, payload, decision matrix, env vars). Read it once before authoring a new hook; come back here for the judgment calls.

Decision: hook vs ad-hoc command vs extension

Three options for "do X when pi does Y". Pick by how durable and how integrated the behavior needs to be.

Reach for a hook when all of these hold:

• The trigger is one of the five Claude-Code-compatible events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart.
• The behavior is user-trusted - the user (not the model) chose to install it.
• The work is short enough to fit in a script call and finish under the timeout (default 60s).
• The right answer is the same every time the trigger fires; you don't need new pi state or a new tool.

If any of those break, write an extension instead. Extensions are the right home for new tools, new slash commands, typed event payloads, or anything that has to compose with another extension's state.

Pick the event

Important constraints:

• PostToolUse, Stop, SessionStart are fire-and-forget for decisions - a block here is illegal and gets logged + treated as continue. Don't author a "block on post" hook; that's a PreToolUse job.
• Hooks fire after bash-permissions, filesystem, and sandbox have approved the call. A bash command the permissions gate already denied never reaches a PreToolUse hook - don't try to use a hook to weaken or override a built-in gate.

Match the right tool

matcher semantics (full reference in hooks.md):

For events without a tool dimension (UserPromptSubmit, Stop, SessionStart) omit matcher entirely.

Author the script, not the config

Keep the JSONC entry thin. Logic lives in the script the entry calls - that's what gets edited, tested, and version controlled separately from the config.

A typical hook script:

#!/usr/bin/env bash
set -euo pipefail

# 1. Read the payload (single JSON object on stdin).
payload=$(cat)

# 2. Do the work. `jq` is the easiest way to pull fields.
tool=$(jq -r '.tool // empty' <<< "$payload")
cmd=$(jq -r '.input.command // empty' <<< "$payload")

# 3. Append to a log, format a file, etc.
printf '%s\t%s\t%s\n' "$(date -Iseconds)" "$tool" "$cmd" >> ~/.pi/bash.log

# 4. Empty stdout = `continue`. Exit 0.

Decision protocol cheat sheet (full matrix in hooks.md):

• Empty stdout, exit 0 → continue. Default. The tool / prompt proceeds.
• Plain-text stdout, exit 0 → continue with the text appended as additionalContext.
• JSON stdout with {"decision": "continue"} → same as above; use this shape when you also need additionalContext or reason set explicitly.
• JSON stdout with {"decision": "allow"} → skip remaining hooks for this event (the next hook in the array does not run). The tool still runs.
• JSON stdout with {"decision": "block", "reason": "<text>"} → on PreToolUse / UserPromptSubmit only; short-circuits and surfaces reason to the model.
• Non-zero exit code → block with stderr as reason. Mirrors Claude Code.

Anti-patterns inside the script:

• Don't read stdin twice. cat once into a variable; the payload is gone after the first read.
• Don't print debug logging to stdout. It will be appended to the tool result as additionalContext. Use stderr (or PI_HOOKS_TRACE=<path> from the runner side) for diagnostics.
• Don't shell out to pi from inside a hook. Hooks fire inside the running session; re-entering it from a subprocess will not do what you want.

Author the config

~/.pi/agent/hooks.json is JSONC - // and /* */ comments are allowed, trailing commas are not. Start from config/pi/hooks-example.json and uncomment the event you need. Project-scoped hooks live at <repo>/.pi/hooks.json and merge with the user file on every event (deny-wins-block - the first block from any layer short-circuits).

Recommended timeouts:

• Audit / log hooks: 2000-5000 ms.
• Formatters / linters that shell out to another binary: 10000-30000 ms.
• Anything talking to the network: bump up explicitly; don't rely on the 60s default.

The sandboxed field is plumbed end-to-end but the wrap lands in a follow-up commit. Setting "sandboxed": true today is reserved - leave it at the default false unless you're tracking the follow-up.

Verify the hook fires

After installing a hook, smoke-test it:

1. pi /hooks - the entry should appear under the correct scope (user / project / session) and event.
2. Run the matching trigger (bash, edit, etc.) and confirm the side effect (log line written, file formatted, prompt context injected).
3. If silent, set PI_HOOKS_DEBUG=1 (notify on every fire) or PI_HOOKS_TRACE=~/.pi/agent/hooks.trace (one line per fire, works in -p / RPC mode where notifications go nowhere) and rerun.

Anti-patterns

• Suggesting a hook for a one-shot task. "Run prettier on this file once" is a bash command, not a PostToolUse entry. Reserve hooks for things that should fire on every matching event.
• Using a hook as a permissions gate. Permissions live in bash-permissions.json. A PreToolUse hook that re-implements deny rules will drift from the real gate and confuse later readers.
• Putting logic in the JSONC entry. The command field is a shell invocation - keep it pointing at a script. Pipelines, conditionals, or environment branching belong in the script, not in hooks.json.
• Authoring a hook that needs a new pi event. The five supported events are the whole surface. If the trigger isn't on that list, you want an extension, not a hook.
• Forgetting set -euo pipefail. Hook scripts run unattended; a silent failure mid-script is worse than a loud exit-1 block.

Quick reference