feat(setup): commit only the shared agent-settings floor

[potiuk]

#1671 stopped committing .claude/settings.json and #1675 made CI refuse it, so nothing every contributor must share — the sandbox, the deny/ask rules, the plugin wiring — reached a fresh checkout without a manual copy. This brings the committed file back, but only as a floor, and moves everything personal into a local layer that setup keeps up to date.

Committed .claude/settings.json (the floor): sandbox.enabled, the ~/ read wall with the minimum reads git/uv/prek need, the core network hosts (GitHub, PyPI, astral), the credential env-var denies, every deny and ask rule, the plugin wiring, the vetted-ops read path (the ~ read pair and exclusions #1640 requires), and the MCP tools of the adopted families. Its only allow entries are those MCP tools and the vetted-op-read pair.

Local template → .claude/settings.local.json: tools/agent-isolation/claude-settings.local.template.json carries the rest — the gh read allows, the gh * / adversarial-review / evals exclusions, family-specific hosts, personal tool paths (GnuPG, Docker). setup upgrade, isolated-setup-install (Step T) and worktree-init (per worktree) reconcile it and hand the user the copy, since an agent cannot write its own settings; reconciliation adds missing entries, records what it applied per worktree, and asks before removing anything upstream dropped. The template is applied only in the framework checkout itself, never staged into an adopter's project.

MCP allows by family: skills/setup/family-mcp-allows.json records which families' skills call which read-only MCP tools (ponymail, apache-projects, claude.ai Gmail reads, gmail-plaintext drafts). adopt and upgrade derive the committed allows from the lock's families, as they already derive enabledPlugins; families installed on one machine only get theirs in the local file. Upgrade proposes removing derived allows the lock and registry no longer produce, and unadopt/uninstall remove them.

sandbox-lint:

• lints the floor merged with the template against the unchanged baseline, and the floor alone against every invariant (a contributor with no local file is still protected);
• enforces the split: every deny/ask in the floor, no non-derived allow in the floor, no MCP allow and no overridden scalar in the template (a local sandbox.enabled: false would switch the sandbox off);
• checks the floor's MCP allows against the registry, failing closed if the registry is missing;
• checks the contributor's live .claude/settings.local.json layered over the floor (invariants plus overrides) — it may add, not weaken.

This replaces #1675's refusal step. The template and registry are Edit-denied (and so sandbox write-denied) like the floor.

Migration: contributors who set up while the file was untracked should back it up first (cp .claude/settings.json .claude/settings.json.bak), since git pull silently overwrites an ignored file, then move their personal entries into .claude/settings.local.json (CONTRIBUTING → Agent settings).

#1681's removal of the Gmail token path and Google hosts carries over: those entries are gone from the template, and its new invariant guards the merged view and the live local layer.

Test plan: sandbox-lint passes on the layered files; 294 sandbox-lint tests pass (merge semantics, every split rule, registry drift, CLI failure paths, live-local cases); prek run clean apart from the workspace tests that need local sockets/network; roborev (claude-code) iterated to Pass with no issues.

---

Generated-by: Claude Opus 5

🤖 Generated with Claude Code