settings.example.json

{
  "_comment": "Reference hook wiring for Claude Code, per docs/runtime-hook-contract.md. Event names (PreToolUse, PostToolUse, Stop) are the real Claude Code hook event names; the Claude Code bridge maps the abstract contract triggers (pre-commit / post-tool-use / on-stop) onto these native events. Paths assume the hooks bundle is at ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/ (copied by the user from the plugin cache). Adjust to project-local hooks by changing the prefix to ${CLAUDE_PROJECT_DIR}/.claude/hooks/. The agentProtocol.{category,level,ruleIds} fields are documentation aids for humans reading this file — Claude Code ignores unknown keys.",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/manifest-required.sh",
            "description": "Category A (phase-gate): block non-trivial git commit if no Change Manifest is staged",
            "agentProtocol": {
              "category": "phase-gate",
              "level": "block",
              "ruleIds": ["phase-gate.manifest-required"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/manifest-size-lint.sh",
            "description": "Category A (phase-gate): block git commit when the Change Manifest exceeds the single-file read ceiling (~25,000 tokens / ~2,000 lines) per docs/change-manifest-spec.md §Manifest size ceiling",
            "agentProtocol": {
              "category": "phase-gate",
              "level": "block",
              "ruleIds": ["phase-gate.manifest-size-ceiling"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/context-pack-required.sh",
            "description": "Category A (phase-gate): block git commit when a parallel_groups entry has 2+ sub-agents but no context_pack_summary per skills/engineering-workflow/references/context-pack.md §When to produce one",
            "agentProtocol": {
              "category": "phase-gate",
              "level": "block",
              "ruleIds": ["phase-gate.context-pack-required"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/anti-full-justification.sh",
            "description": "Category A (phase-gate): block git commit when execution_mode=full but forced_full_trigger is missing per skills/engineering-workflow/references/mode-decision-tree.md §Mode upgrade / downgrade",
            "agentProtocol": {
              "category": "phase-gate",
              "level": "block",
              "ruleIds": ["phase-gate.anti-full-justification"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/manifest-fragment-consistency.sh",
            "description": "Category A (phase-gate): block git commit when a hierarchical Change Manifest's root↔fragment cross-references are inconsistent per docs/change-manifest-spec.md §Hierarchical Manifest",
            "agentProtocol": {
              "category": "phase-gate",
              "level": "block",
              "ruleIds": ["phase-gate.manifest-fragment-consistency"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/evidence-artifact-exists.sh",
            "description": "Category B (evidence): block git commit when evidence_plan paths do not resolve",
            "agentProtocol": {
              "category": "evidence",
              "level": "block",
              "ruleIds": ["evidence.artifact-exists"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/manifest-size-warn.sh",
            "description": "Category C (drift): warn (never block) when the manifest crosses 80% of the line/token ceiling — gives the agent room to compact before manifest-size-lint.sh blocks at 100%",
            "agentProtocol": {
              "category": "drift",
              "level": "warn",
              "ruleIds": ["drift.manifest-size-pressure"]
            }
          }
        ]
      },
      {
        "matcher": "Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/context-budget-warn.sh",
            "description": "Category C (drift): warn when an upcoming Read targets a file that, if read in full, will meaningfully consume the session's context budget per skills/engineering-workflow/references/resumption-protocol.md §Step 2b",
            "agentProtocol": {
              "category": "drift",
              "level": "warn",
              "ruleIds": ["drift.context-budget-overspend"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/resume-mode-attestation.sh",
            "description": "Category C (drift): warn when reading begins on a stale-manifest cross-session resume without a declared resume mode (Lazy / Targeted / Role-scoped / Full / Minimal) per skills/engineering-workflow/references/resumption-protocol.md §Step 2",
            "agentProtocol": {
              "category": "drift",
              "level": "warn",
              "ruleIds": ["drift.resume-mode-undeclared"]
            }
          }
        ]
      },
      {
        "matcher": "Bash(git push*)",
        "hooks": [
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/consumer-registry-check.sh",
            "description": "Category C (drift, network): warn when declared consumer registries are unreachable; never blocks",
            "agentProtocol": {
              "category": "drift",
              "level": "warn",
              "ruleIds": ["drift.consumer-registry-stale"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/cckn-canonical-sync-check.sh",
            "description": "Category C (drift): warn when a CCKN that mirrors canonical methodology SoT has drifted (SoT touched after CCKN updated, or methodology_version mismatch); never blocks",
            "agentProtocol": {
              "category": "drift",
              "level": "warn",
              "ruleIds": ["drift.cckn-mirrors-canonical-stale"]
            }
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/sot-drift-check.sh",
            "description": "Category C (drift): warn when a declared SoT source is not being touched",
            "agentProtocol": {
              "category": "drift",
              "level": "warn",
              "ruleIds": ["drift.sot-file-must-move"]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/drift-doc-refresh.sh",
            "description": "Category C (drift): warn when a declared SoT source is edited without a paired doc/spec/manifest update in the same diff",
            "agentProtocol": {
              "category": "drift",
              "level": "warn",
              "ruleIds": ["drift.doc-refresh-missing"]
            }
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/completion-audit.sh",
            "description": "Category D (completion-audit): block end-of-turn when manifest says 'done' dishonestly",
            "agentProtocol": {
              "category": "completion-audit",
              "level": "block",
              "ruleIds": [
                "completion.evidence-complete",
                "completion.unaccepted-risk",
                "completion.unresolved-escalation",
                "completion.observe-needs-narrative"
              ]
            }
          },
          {
            "type": "command",
            "command": "sh ${CLAUDE_CONFIG_DIR}/agent-protocol-hooks/hooks/handoff-prompt-validator.sh",
            "description": "Category D (completion-audit): warn at soft cap, block at hard cap when handoff_narrative (or aggregated narrative-bearing fields) exceed the budget in skills/engineering-workflow/templates/handoff-prompt-template.md §Budget",
            "agentProtocol": {
              "category": "completion-audit",
              "level": "block",
              "ruleIds": ["completion.handoff-narrative-overflow"]
            }
          }
        ]
      }
    ]
  }
}