A working, self-contained demo of layered guardrails for Claude Code agents. Built to be taught slide-by-slide: open a file, run one command, watch the guardrail react.
Every layer in the deck is real and runs locally — permission policy, a Python hook firewall, a capability-token gateway, an intent-alignment shield, a disposable Docker sandbox, a five-seat review council, and a signed, hash-chained audit log.
app/ a tiny Node app the agents edit and test (the thing being worked on)
.claude/ settings, subagents, slash commands, a skill, an output style, statusline
hooks/ the Python hook firewall (PreToolUse / PostToolUse / SubagentStart / Stop)
gateway/ capability-token gateway + secure executor (slide 9)
sandbox/ disposable Docker playground (slide 11)
audit/ signed, hash-chained audit log + verifier (slide 13)
fixtures/ attack inputs that make the guardrails fire (injection, exfil, off-task)
scripts/ one runnable demo per slide + a full self-test
docs/ architecture and rollout notes
TEACHING_GUIDE.md the slide -> file -> command -> expected-result script
cd app && npm install # local devDeps only (eslint), no -g
cd .. && python3 audit/keygen.py # create the local audit signing keybash scripts/selftest.shExpected: ALL GREEN — ready to teach. (Docker shows SKIP if the daemon is
off; everything else must PASS.)
| Layer | What it is | Where |
|---|---|---|
| 1 Permissions | allow / ask / deny rules | .claude/settings.json |
| 2 Hooks | runtime firewall before/after every tool call | hooks/ |
| 3 Smart guardrails | per-action subagent, intent shield, capability tokens | hooks/, .claude/agents/guardrail-*, gateway/ |
| 4 Sandbox | disposable container for agent-run code | sandbox/ |
| 5 Review council | five independent reviewers before completion | .claude/agents/council-*, hooks/subagent_stop_council.py |
| 6 Audit | signed, tamper-evident log of every action | audit/ |
See TEACHING_GUIDE.md for the live walkthrough and docs/ARCHITECTURE.md for
how the layers fit together.