hook-driven-workflow-enforcementlisted

# Hook-Driven Workflow Enforcement ## Core Insight There are two fundamentally different ways to influence agent behavior: | Mechanism | Determinism | How it works | Failure mode | |-----------|-------------|--------------|--------------| | CLAUDE.md / memory / skills | **Non-deterministic** | Agent reads instructions, may or may not follow | Agent skips, forgets, or deprioritizes | | Hooks (PreToolUse / PostToolUse) | **Deterministic** | System intercepts tool calls, blocks or injects feedback | Cannot be bypassed — the hook runs regardless of agent intent | **Rule of thumb:** If an agent must *always* do X before Y, use a hook. If it *should* do X, use CLAUDE.md. Hooks are for invariants, instructions are for guidelines. ## How It Works ```mermaid sequenceDiagram participant Agent participant Claude Code participant PreToolUse Hook participant State File participant PostToolUse Hook Note over Agent: Agent wants to run<br/>gated command (e.g. gh pr create) Agent->>Claude Code: Bash("gh pr create ...") Claude Code->>PreToolUse Hook: stdin: {tool_name, tool_input} PreToolUse Hook->>State File: Check: /tmp/.gate-<branch>-done exists? State File-->>PreToolUse Hook: No PreToolUse Hook-->>Claude Code: {"decision":"block","reason":"Run /pre-pr-review first"} Claude Code-->>Agent: ❌ Blocked + reason shown as system-reminder Note over Agent: Agent follows instructions,<br/>runs prerequisite skill Agent->>Claude Code: S