AGENTS.md — the agent-config repository

Repo-local knowledge for the agent configuration repository (the live ~/.claude): cross-file invariants, operator rulings, and traps that already bit once. The constitution is the shared contract at the root of this snapshot, not this file.

Instruction files

• Claude Code reads AGENTS.md natively since 2.1.277. The user setting pluginConfigs.agents-md@builtin.options.instructionFiles = claude-md-and-agents-md (settings.json, 2026-09-21) loads both files in repos that carry a CLAUDE.md and an AGENTS.md; the default skips AGENTS.md there. Project and local settings ignore this key.
• Because the config directory sits inside $HOME, ~/AGENTS.md and this file load into every session under $HOME as project instructions of ~. Measured 2026-09-21 with claude -p in three working directories. Keep this file short; it is read far outside the config repo.

Hooks and gates

Read hooks/MAINTENANCE.md before changing gates, scanners, hook dispatch, or their tests; it preserves the failure cases, bounds, and test pitfalls.

• A PreToolUse hook that exits with anything but 0 or 2 is treated as permission: a gate refuses only with exit 2 plus a reason on STDERR, and hooks/run-gates.sh has to survive set -u. Any _GATE_FAIL_CLOSED=0 opt-out goes before the source line.
• The two privacy gates read the command text; their CMDPOS regex is duplicated and the copies must stay identical. A secret is refused whatever the target; a private identifier passes only when every target is proven private. A read, lookup, scan or timeout that fails is a refusal, never a clean verdict.
• Tests must exercise the intended failure with positive and negative controls; KNOWN_RED is a ticketed deferral, not evidence of coverage.
• Changes to the decisions clause of the shared contract require semantic alignment and a manual gates/verify-vendor-contract.sh --emit-baseline reseal.
• Deletion guards were retired by ruling on 2026-09-01 (easy to bypass); the ~/to-delete/ convention remains guidance in the contract. Do not restore the retired guards from historical notes.

Skills

• Ruling of 2026-09-04: queue loading only when picking up work, Linear for work needing follow-through, independent review according to risk, and continuity saves only when useful. Claude's local settings no longer register a session queue summary; Codex's empty SessionStart slot preserves trusted hook indices. Compaction still restores existing saves without a missing-save instruction.
• The same day, generic process skills moved to a shelf. The current managed Codex set is in codex/install.sh; do not restore retired links just because a historical skill references them.
• settings.json is intentionally untracked because it can contain credentials. The 2026-09-04 cut disabled sibling narration, context nudges, resource-sizing warnings, lint-on-write, browser-window movement, and workspace-wide unpushed warnings. Privacy, ownership, continuity, notifications, and workspace sync remain configured; scripts for disabled hooks remain on disk.
• Claude defaults to bypassPermissions (ruling of 2026-09-22). The desktop's agent launcher is locally patched to launch plain claude, respecting permissions.defaultMode rather than forcing auto mode; package updates may overwrite this patch.
• The broad built-in docs skill of Codex is disabled in the local Codex config; its MCP tools remain available. Restart Codex after local config changes.
• A skill description over ~600 characters is dropped wholesale from the ambient listing: the skill stops auto-triggering while looking healthy on disk. Budget 200-400 characters.
• Two skills (a desktop-config skill and a crash-diagnosis skill) are symlinks into the desktop package's skill directory, owned by the package and mirrored by its migrations into every runtime's skill directory. Never edit, shelve, or add them to codex/install.sh; --check ignores them.
• skills/outreach-atlas/: ruling of 2026-08-27: the atlas store is curated markdown, hand-edited by the primary only. No JSON stores, no patch pipelines.
• skills/cold-email/: the sender's own jurisdiction governs the compliance frame (ruling of 2026-08-26). Earlier briefs argued a different frame and carried vendor statistics that failed primary-source verification; do not re-import either.

Delegation and tooling

• Laptop provider bridges are on demand (2026-10-16): delegate/ensure-provider-bridge starts only the selected DeepSeek/OpenRouter user service and waits for local health; ds-codex/codex-union call it before dispatch. They are disabled at login and stay shared until explicitly stopped. Do not enable them merely to repair a wrapper.
• The Codex layer is symlinks only (ruling of 2026-09-01: thousands of lines managed by one link, a few links and one hook). codex/install.sh writes them, --check audits them; a regular file at a managed path is reported and left as found. Editing a hook here changes live Codex behaviour at once.
• Codex hook trust is keyed by hooks.json path, event, and index in ~/.codex/config.toml [hooks.state]; changing a hook command can silently stop it until the operator re-approves it in the startup TUI. Preserve trusted indices. codex/hooks/pre_tool_use.py must dispatch both privacy gates and refuse on failures; dispatch bounds and verification mechanics are in hooks/MAINTENANCE.md.
• deepseek/CORE-compact.md serves the DeepSeek dispatch agent, the ~/.agents/CORE.md symlink, and the cached harness prefix. Keep its leading bytes stable: DeepSeek's prefix cache matches exact leading bytes, so an edit near the top invalidates it for every dispatch.
• Agent-tier tools in delegate/ and scripts/ each keep a symlink at their original ~/.local/bin path, pinned absolutely by systemd units and reference docs; never delete one without editing its caller. scripts/optmem-proposals is 700 on disk, 755 after a fresh clone.
• Free web research runs on OpenRouter's thinkingmachines/inkling-small:free through omp, two doors: the omp-search wrapper and the omp web-researcher agent. Invariants: the endpoint logs prompts for training, so public topics only, never a person's name, an address, a CRM row or vault text; every :free run on the key shares 20 requests a minute and 1000 a day; omp's web_search is hosted search on the Codex login, so searches still draw Codex quota. A smaller free model failed a multi-hop task twice on 2026-09-16; do not swap it back in without a new measurement. Free general work (non-search, public inputs) runs on thinkingmachines/inkling:free through the omp-inkling wrapper (--small for inkling-small) and the omp inkling-worker agent. Both Inkling models return 403 on raw API calls ("only available on agentic harnesses"), so they only run through omp. Evidence and flags: the model-delegation reference.
• Free routes run only inside delegate/free-silo (ruling of 2026-09-27): the harnesses attach private files, and a model with file tools can read any of $HOME. One wrapper had sent the memory wake, the contract and the skill list; omp every cwd-ancestor AGENTS.md. The silo is bubblewrap: a fake $HOME with its own omp profile and CODEX_HOME (configs delegate/free-silo-{omp.yml,codex.toml}, installed per run), an empty jail as cwd, and only the OpenRouter/Tavily keys in env. --cwd DIR only receives outputs; inputs go in with --in FILE. The free omp agents live in the silo profile, so a Codex-model omp session cannot hand them work. Runs refuse after an omp or codex update until free-silo --verify passes again (isolation, and a canary AGENTS.md captured offline with positive controls). Search in the silo is Codex-hosted all the same: delegate/codex-search-bridge (user unit on loopback, bearer token) serves the SearXNG API from the host omp with only web_search, so the login stays outside and the silo holds just a localhost token. Do not copy the Codex login into the silo: two copies of one session invalidate each other's refresh token. The stealth model behind codex-union/omp-union was retired upstream on 2026-09-27, so those wrappers have no model until one is chosen.
• eval/skill-activation/run.py: --tools removes tools from the model's view entirely, so denying Skill that way zeroes fired-detection; it does not cover MCP tools; and the prompt must sit immediately after -p, before the variadic --tools.

The work system

• Queue keepers (2026-09-30 to 2026-10-10) were retired by the dispatcher; their timers are stopped and disabled, units and state kept for rollback (stop the dispatcher first: two claimers race). What survives: the VPS worker account (own device-auth login), the Linear apps for each worker hand (one installed as an agent since 2026-10-11: assignable and mentionable through Linear's delegate field, which rests on a browser-consent installation with actor=app plus a .scopes file next to the client secret so every caller mints the same scopes; token JSON 0600 in the tool's state directory), the bounded operator wrapper (one sudoers line, an allowlist, three restarts per hour, syslog; never widen it to deploys or edits), the approval page (VPS unit, tailnet port, approvers is the phone's tailnet address only, never a machine; a tap writes a record read once by the dispatcher when ticket, comment and text equal the stored ask; any agent signature is accepted since 2026-10-10), the non-routing pins laptop/vps, the ntfy approve channel, and the Claude app identity for Claude Code sessions (three settings in settings.json env; each brain-linear call mints and revokes its own token). Tests live beside the code in work/.
• Codex's sandbox sets no_new_privs and blocks sudo, so VPS workers run danger-full-access. Since 2026-10-10 the worker account has passwordless root (the operator's "full root" ruling, installed through the phone gate), so the OS user is no longer the boundary; the approval record is. Since 2026-10-13 the operator's or the assistant's request on a ticket is the authority for root work, deploys included; the APPROVAL RECORD gates only money, messages as the operator, secrets and tier-3 destruction. Ticket text can come from the assistant, which reads mail and the web: never let quoted text stand in for a request or a comment for the record on those four gates.
• One work system (ruling of 2026-10-10): the assistant files tickets; a Linear webhook delivers every Issue/Comment/IssueLabel change in seconds to the VPS receiver, which forwards it to the steering agent; the steering agent files, labels, pins and comments (as its own Linear app, signed (steering, date)) and never claims; the dispatcher (VPS unit, own account, own Linear app, signs (dispatcher, date)) is the one claimer: it tails the event log, polls every five minutes, claims for:codex (Sol via codex exec) and for:claude (Claude Code -p --chrome, laptop only) tickets, honours the pins, and spawns one fresh worker per ticket over SSH with a forced command (the dispatcher's key can do nothing else), two per machine, one Claude at a time. Workers sign (worker-vps run-xxxxxx, date) style, post milestones, end with one signed outcome; no outcome = handed back, twice = for:operator; an unsigned reply within 14 days spawns a follow-up; a phone-page record spawns the approved action. Mechanics and rollback: work/.
• ntfy has three channels, split by what the operator must do (2026-10-01). approve (high): pushes that wait on a tap, from the approval page and dispatch approval requests. alarm: something broke, from the alarm unit and the watchdog (alarms high, recoveries low). One owner per failure: the watchdog owns the tracker pull (no OnFailure there; one fetch failure is not an alarm, a lasting one escalates), the alarm unit the other units, once per 6 h. fyi: "run finished" pushes. A new sender picks a channel by that question and reads the topic from its file, never inline. Senders post to ntfy directly; the laptop falls back to an ssh relay through the VPS, since ntfy meters by address and a VPN exit can run dry.
• Local collaboration uses opt-in agent-bridge, hcom, and connectome-lab launchers; see the agent-communication reference. agent-bridge avoids the existing /usr/bin/bridge networking command. Codex 0.154.0 hooks/list verified that its session-flag hooks append alongside managed hooks.json; keep that check when upgrading. Do not nest bridge and hcom on one session or replace trusted hook indices. The local hcom build preserves managed symlinks and empty hook groups; retain both regressions when upgrading.
• The assistant bridge (2026-09-22, streamlined 2026-09-23): a private repository holds the published vault subset and the tools; deploy is a root-owned copy that refuses unless main's tools, rules and policy equal the reviewed commit and every such change since the deployed revision is by the owner, because the assistant's own GitHub account has write access and main cannot be protected on the free plan. Server jobs: publish (5 min), apply (1 min; a PR wholly under the inbox is applied after content checks, the rest waits for a person; no verdicts, no owner approvals), respond (1 min; a one-shot codex exec under its own OS user and login: never copy another user's login), check (15 min; restarts a failed job, pages after three failed checks in a row or a stopped timer; a pause marker holds a job). No GitHub login, label, merge or comment carries owner authority. The vault is the source of truth: publish overwrites GitHub-side vault edits. Traps: systemd 255 prints a timer's LastTriggerUSec in human form despite --timestamp=unix; the pre-push privacy gate times out on rewritten vault history, so the operator pushes such a rewrite with ! after a manual scan; a policy change on main stops publish until it is deployed. Labels for:assistant and from:assistant route tickets; for:assistant tickets are mirrored into GitHub issues; the assistant files machine work as for:codex plus from:assistant so the queue workers answer it. Mechanics: assistant-bridge/.

Reference docs

• The model-delegation reference carries only what <wrapper> --help and the contract cannot; the derivable parts were cut, because a duplicate rots while the source does not.
• The compute-provider reference's figures decay fast and expensively: read the vendor CLI.
• The VPS reference: verify any deploy path against pm2 show <name>. One recipe copied builds into a dead directory for months and reported success every time.