Hooks and Enforcement

Hooks are deterministic scripts that run outside the agent loop. That matters because the agent cannot “forget” or “choose not to” run them.

When Hooks Are Worth It

Use hooks when a rule must happen every time:

• formatting after file edits
• linting before commits
• blocking dangerous shell commands
• logging tool usage for auditability
• enforcing local policy before high-risk actions

Good Hook Targets

Trigger	Useful enforcement
After file writes	format changed files
Before shell commands	block unsafe command patterns
Before commits	run lint, types, and tests
Before deploy wrappers	require human approval or a checklist

Example Pattern

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm lint --fix"
          }
        ]
      }
    ]
  }
}

Practical Rules

• Put repo-wide policy in hooks, not in polite prompt wording.
• Keep hook commands fast enough that people will not disable them.
• Prefer allowlists and narrow matchers over broad “do everything” scripts.
• Fail clearly so the agent and the human can tell what needs fixing.

When Not To Use Hooks

Do not reach for hooks when:

• the workflow is optional
• the check is too slow for local iteration
• the logic belongs in CI where environment parity matters more

The best use of hooks is enforcing fast, local, high-signal rules.