pal-e-docs

SOP: Hook Block Recovery

sop-hook-block-recovery Sop

sop active
Project

SOP: Hook Block Recovery

Purpose: Teach agents how to understand and respond when a PreToolUse hook blocks their action. Hooks are the enforcement layer — they exist to prevent mistakes. When blocked, the agent should understand WHY before deciding what to do.
Traceability: plan-pal-e-agency → Phase 5 (Error Recovery SOPs)

How Hooks Work

Hooks live in ~/.claude/hooks/ and are hardlinked from ~/claude-custom/hooks/ (same inodes — git pull on claude-custom auto-deploys). They fire on PreToolUse (before a tool runs) or PostToolUse (after). A PreToolUse hook that exits non-zero with a JSON {"decision": "block", "reason": "..."} prevents the tool from executing.

Failure Modes

Symptom Likely Cause Recovery Steps
Write/Edit blocked with "no valid issue reference" <code>check-issue.sh</code> — you are trying to write code without an issue number in your branch name or conversation context. 1. Verify you are on a feature branch (not main). 2. Branch name must contain the issue number (e.g., <code>issue-42-fix-thing</code>). 3. If working without a branch yet, create the issue first, then create the branch.
Git commit blocked with "direct commits to main not allowed" <code>block-main-commits.sh</code> — you are committing directly to main. 1. Create a feature branch: <code>git checkout -b issue-N-description</code>. 2. Commit on the feature branch. 3. Never commit directly to main — this is by design.
pal-e-docs MCP write tool blocked <code>block-docs-writes.sh</code> — blocks all 17+ pal-e-docs write operations for non-Dottie agents. Only Dottie (spawned as general-purpose with the right context) can write to pal-e-docs. 1. If you are a Dev or QA agent: you CANNOT write to pal-e-docs. Report your doc update needs to Betty Sue. 2. If you are Dottie and getting blocked: verify your spawn included the correct context injection. Check if <code>block-docs-writes.sh</code> is checking agent identity correctly.
Agent spawn blocked with "no plan/issue reference" <code>check-agent-spawn.sh</code> — spawning a sub-agent without the required plan slug (for Dottie/general-purpose) or issue reference (for Dev/QA). 1. For Dev/QA agents: include the Forgejo issue number in the spawn prompt. 2. For Dottie: include the plan slug in the spawn prompt. 3. The rule is "No issue, no agent" — scoping must be complete before dispatch.
PR merge blocked with "ask permission" <code>block-pr-merge.sh</code> or <code>block-mcp-merge.sh</code> — merge requires explicit user approval. 1. This is NOT an error. Present the PR to the user and STOP. 2. Wait for explicit approval before merging. 3. Never attempt to bypass this hook.
PR submission blocked with "missing Closes #N" <code>check-pr-template.sh</code> — PR body must contain <code>Closes #N</code> to enable Forgejo auto-close. 1. Add <code>Closes #N</code> (with the correct issue number) to the PR body. 2. Re-submit the PR. 3. This is enforced because Forgejo auto-close depends on it.
Hook fires but the block reason seems WRONG Hook logic may be stale (new tools added but hook not updated), or the hook is checking context incorrectly. 1. Read the block reason carefully. 2. Read the hook script: <code>~/.claude/hooks/HOOK_NAME.sh</code>. 3. If the hook is genuinely wrong (e.g., blocking a valid action), note the finding and escalate. Do NOT try to work around the hook.

Decision Tree

When a hook blocks your action:
  • Read the block reason. The JSON reason field tells you exactly why.
  • Ask yourself: is the hook right? In 95% of cases, the hook caught a genuine mistake. Fix your action.
  • If the hook is right: Fix the underlying issue (create branch, add issue ref, add Closes #N, etc.) and retry.
  • If the hook seems wrong: Read the hook script at ~/.claude/hooks/ to understand its logic. Note the discrepancy. Escalate to Betty Sue — do NOT attempt to bypass or work around the hook.
  • Never modify hooks yourself. Hook changes go through the claude-custom repo with a proper PR. See sop-claude-config-development.

Escalation Criteria

Escalate immediately (do NOT self-correct) when:
  • A hook is blocking a valid, correctly-scoped action (hook bug)
  • A hook that should fire is NOT firing (hook gap)
  • You do not understand the block reason after reading the hook script
  • You are tempted to work around a hook by using a different tool or approach to achieve the same blocked action
  • sop-claude-config-development — how to modify hooks properly
  • pr-lifecycle — which hooks fire at each PR stage
  • agent-workflow — agent identity and what each agent can/cannot do
  • convention-enforcement-architecture — the four pillars (hooks, MCP, skills, agents)