Kjell Tore Guttormsen 912689f3c5 feat(templates): add governance and approval gate templates (Paperclip pattern)

Session 4 step 17 — 5 autonomy levels (0-4), PreToolUse approval-gate
hook polls approval-responses.jsonl with 60s timeout, blocks on no-response.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-12 06:55:33 +02:00

2.3 KiB

Raw Permalink Blame History

Governance and Approval Gates

PreToolUse hook implementing human oversight with configurable autonomy levels. Inspired by Paperclip's "autonomy is a privilege you grant" philosophy.

Autonomy model

Five levels (0–4) control how much the agent auto-approves:

Level	Description	Auto-approves
0	Full manual	Nothing — every tool requires human OK
1	Safe ops	Read, Glob, Grep
2	File ops	+ Write, Edit within project
3	Non-destructive	+ Bash (non-destructive commands)
4	Full autonomy	Everything — hooks act only as guardrails

Set Current level: N in GOVERNANCE.md to change autonomy.

Approval gates

Gates are conditional checkpoints where the agent pauses and waits for human approval regardless of autonomy level. Configure them in GOVERNANCE.md:

- deploy-gate: after all tests pass AND reviewer approved
  Action: pause

How approval flow works

approval-gate.sh runs as a PreToolUse hook
If auto-approved (based on level): exits 0, tool proceeds
If gated: writes request to governance/pending-approvals.jsonl
Polls governance/approval-responses.jsonl for matching response (by ID)
Response approve → allow (exit 0), log to approvals.log
Response deny → block (exit 2), log denial
No response within timeout (default 60s) → block with timeout message

Responding to approval requests

When an agent is waiting for approval, add to governance/approval-responses.jsonl:

{"id": "<request-id>", "decision": "approve"}

{"id": "<request-id>", "decision": "deny"}

Audit trail

All tool calls are logged to governance/audit.log. All approval decisions are logged to governance/approvals.log.

Integration

Add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "bash governance/approval-gate.sh"}]
    }]
  }
}

Paperclip comparison

Paperclip stores approvals in a database table with async notification. This implementation uses file-based polling — simpler, no service dependency, suitable for single-machine deployments. For multi-agent systems that need concurrent approval routing, consider upgrading to a queue or webhook approach.

2.3 KiB Raw Permalink Blame History Unescape Escape