fence: Instructions file for Claude Code

CLAUDE.md

Project Overview

Fence is a standalone Go CLI: guardrails for AI coding agents. It inspects an agent's tool calls (through that agent's hook system) and blocks or asks before catastrophic ones run — recursive deletes of home/root, secret exfiltration, curl | sh, force-pushes. Standalone Go module, Go 1.26, no runtime services.

Scope is deliberate. Fence is local self-protection: dev-owned, dev-editable, and it fails open. It is intentionally not a compliance or central-enforcement product — keep un-bypassable policy, fleet management, central audit, and approval workflows out of scope.

Commands

• make build → ./dist/fence · make test · make vet · make fmt · make tidy
• Raw: go build ./... · go test ./... · go vet ./... · gofmt -l .
• go test ./... is the gate — tests pin the false-positive discipline.
• Test a rule without an agent: fence check 'rm -rf ~' (prints a DENY/ASK/WARN/ALLOW card).
• Exercise the hook directly: echo '{"cwd":".","tool_name":"Bash","tool_input":{"command":"rm -rf ~"}}' | ./dist/fence hook claude-code

Architecture — agent-neutral core + per-agent adapters

• internal/policy/ — engine (Evaluate, deny-overrides resolution), the neutral Action/Effect/Decision types, Rule/Match/Rulepack, and the embedded builtin/recommended.yaml default pack.
• internal/analyzer/shell/ — shell-AST analysis via mvdan.cc/sh producing semantic facts (recursive-delete + target class, force-push, history-rewrite, net→shell pipe). This is the differentiator — see Conventions.
• internal/adapter/<agent>/ — translate one agent's tool call ⇄ neutral Action. claudecode (Claude Code PreToolUse + the statusLine session proof, with the SessionStart banner as fallback when another status line owns the slot) came first; codex speaks Codex's Claude-compatible hook envelope with its own tool vocabulary (Bash, apply_patch — expanded to one file_write per touched file, most severe verdict wins); opencode has no hook protocol at all — a generated JS shim plugin (fence init opencode writes it, template embedded in internal/cli/opencode_plugin.js) pipes tool calls to fence hook opencode, and its only block primitive is throwing, so ask degrades to a soft block that routes the agent to the user. Adapters stay self-contained even where the wire formats coincide — the protocols are owned by different vendors and may drift. Decisions and chat notices ride the same JSON envelope; an explicit "allow" decision is never emitted (it would bypass the user's own permission settings).
• internal/store/ — the user-level state dir (~/.fence): packs installed via fence add (the packs dir is the source of truth) + packs.lock.json metadata.
• internal/registry/ — fetch + sha256-verify packs from a static index (registry/ in this repo, read raw off main). Only the explicit commands import it — nothing on the eval path may ever touch the network.
• internal/cli/ — Cobra commands: check, hook, init, uninstall, add, search, update, remove, version. plugins.go detects a Claude Code plugin that already runs the Fence hook (see Conventions).
• cmd/fence/ — entrypoint; version is injected via -ldflags "-X main.version=...".