signed-audit-trails-recipe

Signed Audit Trails for Claude Code Tool Calls

Cookbook-style walkthrough for cryptographically signed receipts on every Claude Code tool call. This is the teaching skill. For the runtime implementation, install the protect-mcp plugin.

What this gives you

Every tool call (Bash, Edit, Write, WebFetch) is:

1. Evaluated against a Cedar policy before execution. If the policy denies the call, the tool does not run.
2. Signed as an Ed25519 receipt after execution. Receipts are JCS-canonical, hash-chained, and verifiable offline by anyone with the public key.

An auditor, regulator, or counterparty can verify the full chain later with a single CLI command (npx @veritasacta/verify receipts/*.json). No network call, no vendor lookup, no trust in the operator.

When to use the pattern

• Regulated environments (finance, healthcare, critical infrastructure) where you need tamper-evident evidence of agent behavior
• CI/CD pipelines where you want to prove that a policy gate held for every automated build step
• Multi-party collaboration where a counterparty wants to verify your agent's behavior without trusting your operator
• Compliance contexts (EU AI Act Article 12, SLSA provenance for agent-built software) where standard logging is not sufficient

Step 1: Install the hook configuration

Create .claude/settings.json in your project root:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hook": {
          "type": "command",
          "command": "npx protect-mcp@latest evaluate --policy ./protect.cedar --tool \"$TOOL_NAME\" --input \"$TOOL_INPUT\" --fail-on-missing-policy false"
        }
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hook": {
          "type": "command",
          "command": "npx protect-mcp@latest sign --tool \"$TOOL_NAME\" --input \"$TOOL_INPUT\" --output \"$TOOL_OUTPUT\" --receipts ./receipts/ --key ./protect-mcp.key"
        }
      }
    ]
  }
}