Agents execute tool calls. Most of them are fine. Some of them delete staging databases, send emails to the wrong distribution list, or git push --force onto a branch someone was reviewing. The gap between "the model decided" and "the tool ran" is where governance has to live.
This is a hands-on walkthrough of adding that gap, a pre-execution approval layer, to Claude Code in about 60 seconds.
The one-liner
curl -fsSL https://sidclaw.com/install-hooks.mjs | node
That's the full install. No npm package, no .claude/settings.json edits, no wrapper binary. The script writes a PreToolUse hook into Claude Code's hook directory, registers it against all 11 governed tool categories, and verifies the install with a self-test call.
Homebrew, rustup, and nvm all use this pattern. It's a reasonable trust model: you can read the script before piping it (curl -fsSL https://sidclaw.com/install-hooks.mjs | less), SHA-256 sum is published at /install-hooks.mjs.sha256, and the install is idempotent — running it twice won't double-register.
Environment variables
Two vars, both required:
export SIDCLAW_BASE_URL=https://api.sidclaw.com
export SIDCLAW_API_KEY=ai_your_key_here
Free tier keys come from app.sidclaw.com/signup. The hook fails closed by default if the API is unreachable. Set SIDCLAW_FAIL_MODE=open if you'd rather prioritize availability over safety (not recommended for production).
Optional:
export SIDCLAW_TIMEOUT_MS=30000 # default 30s
export SIDCLAW_AGENT_ID=my-agent-name # defaults to hostname
What gets intercepted
Every call in these 11 categories goes through policy evaluation before the tool runs:
| Tool category | Example action | Typical policy |
|---|---|---|
| Bash | rm -rf ./staging |
approval_required for destructive paths |
| Edit | editing .env files |
approval_required for secrets |
| Write | writing to /etc/
|
deny |
| MultiEdit | bulk refactor across 50 files | approval_required over threshold |
| Agent | spawning a subagent | allow with trace |
| Skill | invoking a skill | allow, log inputs |
MCP tools (mcp__*) |
any MCP server call | varies by server |
| NotebookEdit | mutating notebook cells | allow |
| WebFetch | fetching an arbitrary URL | approval_required for non-allowlisted hosts |
| WebSearch | external search | allow |
| BashOutput / KillShell | background process control | allow |
Policies are YAML in the dashboard. You can start with the defaults (SOC2-aligned, block the obvious danger) and tighten from there.
Demo: the rm -rf scenario
Without the hook:
$ claude
> clean up the test data in ./staging
# Claude runs: rm -rf ./staging
# Files gone. No confirmation. No log.
With the hook:
$ claude
> clean up the test data in ./staging
[SidClaw] Tool call held for approval: Bash
command: rm -rf ./staging
risk: high (recursive delete)
classification: restricted
agent: claude-code-local
reasoning: "user requested test data cleanup; ./staging contains test fixtures"
Approval pending... (policy: destructive-fs-operations)
The reviewer sees the full card in Slack, Teams, Telegram, or the dashboard. They approve, deny, or edit the command before execution. Every decision writes a signed entry to the audit chain.
Approve → the command runs, trace recorded.
Deny → Claude gets a structured refusal it can reason about. No data accessed.
Before / after
Before (vanilla Claude Code):
agent decides → tool runs → logged in Claude's local history (per-session)
After (with hook):
agent decides → SidClaw policy → [allow | approval_required | deny] → tool runs or blocks → hash-chained audit event
The audit chain is two tables, both tamper-sealed with SHA-256 chains:
-
action_records— every state transition (running→pending_approval→approved→completed, or any failure edge) -
audit_events— every decision, with the previous event's hash included in the next event's signature
You can verify the chain offline, export to SIEM as JSON/CSV, or stream continuously via webhook.
Troubleshooting
"No API key" error on every tool call. You didn't export SIDCLAW_API_KEY, or you exported it in a different shell from where Claude Code is running. Check with echo $SIDCLAW_API_KEY in the same terminal. If you use a .env file, Claude Code doesn't load it automatically — source it first.
Timeout after 30 seconds. The reviewer hasn't responded yet. Increase SIDCLAW_TIMEOUT_MS or switch the policy to async (webhook-based) so the agent can continue on allowed actions while the held call waits.
The hook didn't fire. Claude Code loads hooks at session start. Restart claude after install. Verify the hook is registered: claude hooks list should show sidclaw-pretooluse.
Rate-limited by the API. Free tier is 1,000 governed calls/day. The response includes a retry-after header. For higher volumes, app.sidclaw.com has paid tiers.
Compliance mapping
This isn't a disclaimer. The hook's audit trail is structured against specific regulatory requirements:
- FINRA 2026 Rule 3110 — documented human checkpoints for AI actions in financial services. The approval card IS the checkpoint artifact.
- EU AI Act Article 14 (effective August 2026) — human oversight for high-risk systems. The audit chain is the oversight record.
- SOC 2 CC7.2 — monitoring of system activities. The action_records table satisfies this.
- GDPR Article 22 — safeguards for automated decision-making. The approval step is the safeguard.
- NIST AI RMF and OWASP Agentic Top 10 — mapped in the compliance docs.
Honest limitations
- The hook is a pre-tool-use interceptor, not a full agent runtime. It governs what Claude Code is about to do, not what it thought about doing.
- If you're running Claude Code offline and the SidClaw API is unreachable, the default is fail-closed. That's safer but it stops your agent. Know which mode your policy is in.
- Policy authoring is YAML today. A visual policy builder ships in May.
- The hook currently intercepts tool calls, not model responses. If you need prompt filtering too, that's a different layer (we don't do that).
Related tools (honest alternatives)
- Claude's permission rules — built into Claude Code, simpler but no audit trail or reviewer UI
- cco-mcp — real-time firewall for Claude Code tool calls; stalled since August 2025 but open source
- DIY governance builder — several walkthroughs on this site covering custom hook scripts; more control, more maintenance
Links
- Repo: github.com/sidclawhq/platform
- Integration docs: docs.sidclaw.com/docs/integrations/claude-code
- Compliance docs: docs.sidclaw.com/docs/compliance
- Install script source (read before piping): sidclaw.com/install-hooks.mjs
Top comments (0)