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>
This commit is contained in:
parent
ec6f7c150e
commit
912689f3c5
3 changed files with 277 additions and 0 deletions
75
scripts/templates/governance/README.md
Normal file
75
scripts/templates/governance/README.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# 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
|
||||
|
||||
1. `approval-gate.sh` runs as a PreToolUse hook
|
||||
2. If auto-approved (based on level): exits 0, tool proceeds
|
||||
3. If gated: writes request to `governance/pending-approvals.jsonl`
|
||||
4. Polls `governance/approval-responses.jsonl` for matching response (by ID)
|
||||
5. Response `approve` → allow (exit 0), log to `approvals.log`
|
||||
6. Response `deny` → block (exit 2), log denial
|
||||
7. 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`:
|
||||
```json
|
||||
{"id": "<request-id>", "decision": "approve"}
|
||||
```
|
||||
or
|
||||
```json
|
||||
{"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`:
|
||||
```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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue