# 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.