agent-gate: Instructions file for Claude Code

CLAUDE.md — agent-gate

Project memory for AI assistants working on this repo. Read this before making non-trivial changes.

What this is

agent-gate is a personal, single-user audit gate for Claude Code's outbound HTTPS. It TLS-intercepts every request the agent (and its subprocesses) makes, parses + flags + persists the flow, and serves a local web dashboard for review. It does not ship as a service, ship to a backend, or run as multi-tenant. Everything is loopback, single-user, local disk.

Three subsystems share one binary:

┌──────────────────────── agent-gate ────────────────────────┐
│                                                            │
│   launcher  ──spawn──▶  agent (claude, curl, gh, ...)      │
│   (sandbox/jail)              │                            │
│                               │ all egress forced here     │
│                               ▼                            │
│   proxy :8888  ──parse──▶ policy ──▶ store (jsonl+sqlite)  │
│                                            │               │
│   dashboard :7878 ◀────────────────────────┘               │
└────────────────────────────────────────────────────────────┘

The launcher physically forces egress through the proxy via a per-platform network jail (macOS sandbox-exec, Linux user namespace, Windows scaffolded for Plan 4). The proxy is a TLS-MITM forward proxy. The dashboard is read-only against the store.

Critical rules — never break these

• Audit-log completeness. Every captured flow MUST land in the JSONL + SQLite store. The proxy emits on a buffered channel; if the consumer falls behind, the proxy slows down (and upstream may time out). Drop-on-full is a correctness bug, not a knob. See internal/proxy/proxy.go.
• Fail-closed posture. If the proxy crashes during agent-gate run, the agent's network goes dark. The supervisor's teardown path may not silently swallow this; the child must die when the proxy dies. See internal/launcher/supervisor.go.
• Loopback only. The proxy refuses to bind a non-loopback address; same for the dashboard. See isLoopbackAddr in cmd/agent-gate/proxy_cmd.go and isLoopback in internal/dashboard/server.go. Never relax this.
• File modes. CA private key + JSONL + dismissals.json must be 0600; config + data dirs must be 0700. The CA package refuses to start if key.pem is wider than 0600 — gated on runtime.GOOS != "windows" since Windows ignores unix mode bits. macOS + Linux enforce; Windows skips both in the production check (internal/ca/ca.go) and the unit test (internal/ca/ca_test.go).
• No secrets in commits. git add files by name, never git add -A or git add .. The user's data dir contains real captured prompts and responses; an accidental add -A would commit them.
• Don't push without permission. Local merge + tag is fine; pushing to origin always needs explicit user authorization (per the user's global CLAUDE.md).
• Always execute in a git worktree. Every code change, test run with side effects, and binary build happens inside .worktrees/<branch>/, never in the main checkout. The main checkout is reserved for reading, git operations, and merging PRs. The worktree is created BEFORE work starts — never skip it "just for a small change" and never infer it later. When invoking subagents to execute a plan, instruct them to cd into the worktree as their first step.