AGENTS.md git:20261103.c184039A

Immutable. This exact content never changes and is served at /api/v1/blob/54e7b99626038a10.

# auditor-skill — Agent Orchestration

This skill audits with a small team of subagents (see `agents/`) and, when available,
orchestrates Trail of Bits execution tooling vendored at `vendor/trailofbits`.

**Bundled paths.** Every bundled path — scripts, tools, templates, `vendor/trailofbits`, corpus files — is relative to the auditor-skill installation root, never to the working directory, which is usually the audited repository. Command and agent text writes that root as `${CLAUDE_PLUGIN_ROOT}` for what it runs, the skill body as `${CLAUDE_SKILL_DIR}`; corpus files they name by a relative path are read from that root too, and in a file read later, use the absolute root you were given (`OUTPUT-RULES.md` Rule 11e).

**Permissions.** Each command pre-approves, in its `allowed-tools`, the bundled entry points its steps run, and that grant covers the agents it starts in the same turn. An agent's own `tools:` list makes tools available but approves nothing, so the agents write files with the Write and Edit tools under the command's `Edit(audit_*/**)` or `Edit(incident_*/**)` grant, and run each bundled tool as one plain command, its quoted path first (Rule 11e). The grant ends at the user's next message, so a flow spawns its agents in the foreground and waits for them; a flow that goes on after a reply, or after an agent's result that arrives in a later turn, first invokes its command again through the Skill tool, with `--resume`, and that invocation runs `scripts/preflight.sh` again. Every flow starts with `scripts/preflight.sh`. See `docs/permissions-and-isolation.md`.

## Flow (full audit)

0. **Pre-scan (optional, deterministic).** If `tools/auditor-tools/` is built, `audit-scan --contract=1 <program-path>` emits the instruction/constraint/PDA/arithmetic map at ~$0 and `audit-mem warm --contract=1 --program-id <id>` loads the prior protocol profile, invariants + open false-positive rulings (Rule 11d: from an in-tree `.audit-memory/` only if the auditor created it, which `audit-mem init --contract=1` does, `.gitignore` first; `audit-mem` itself refuses a store the repository tracks in any letter case or that holds a link, and a store for the run, `--db audit_<n>/audit-mem.db`, takes its place) — seeding `context-builder` with a map instead of a blank repo, and letting `vuln-hunter` auto-suppress findings that carry a prior `FALSE_POSITIVE` ruling made at the audited commit whose guard still holds (`audit-mem check --contract=1 --commit <full commit id>`). Falls back to the grep walk if the toolchain is absent. See [references/orchestration/pre-scan.md](references/orchestration/pre-scan.md).
1. **`context-builder`** (sonnet) — Phase 0 setup + Phase 0.5 context reconstruction. No verdicts; understanding only.
1b. **`threat-modeler`** (opus) — from the context worksheets + `audit_<n>/intake.md`, emits `audit_<n>/threat-model.md` (asset inventory · actor×capability · trust boundaries) that hands the reviewers attacker goals and seeds report §4.4/§4.6/§4.7. When a bootstrap trigger fires (prior audit or incident, fork provenance, prior audits/incidents next to the target), the bundled collector (`<auditor-skill root>/scripts/threat-model/collect.sh`, never a `scripts/` path relative to the audited repo) first gathers history and prior reports offline into `audit_<n>/bootstrap/`; the agent stays read-only and cites that evidence per goal. No verdicts.
2. **`vuln-hunter`** (opus) — item-by-item walk against in-scope checklists + phase-triggered vectors. Every finding with N ≥ 6 must pass the Rule 5b gate. Delegates SAST / harnesses to Trail of Bits when present (see `references/orchestration/boundary-map.md`).
3. **`economic-analyst`** (opus) — checklist 06 + economic vectors; drives `/economic-sim` (Surfpool mainnet-fork) to quantify profitability for High/Critical economic findings.
4. **`peer-reviewer`** (opus) — independent reconciliation on top-severity findings (N≥8, contested N≥7): re-derives from the code (reusing the context worksheets), delegates to Trail of Bits `fp-check` (local) and `second-opinion` when present — `second-opinion` sends the selected code to an external LLM CLI (OpenAI Codex or Google Antigravity / Gemini), disclosed in the report per `OUTPUT-RULES.md` Rule 11b; emits CONFIRM / DISPUTE / DOWNGRADE. *(Neodyme independent dual-review.)*
5. **`audit-reporter`** (sonnet) — deterministic assembly: Scope Coverage, findings, Phase 4.5 maturity scorecard, remediation roadmap → `audit_<n>/REPORT.md`.

Between review and reconciliation, **`/triage`** batch-dedups the candidate set (root-cause + `audit-mem` suppression/regression), re-applies Rule 5b, and splits real findings from Notes & Nitpicks. On demand for High/Critical findings, **`poc-engineer`** + **`patch-engineer`** (via `/poc` / `/patch`, or `/audit-cycle --with-poc`) emit executable PoCs + verified fix patches (see [references/orchestration/poc-harness.md](references/orchestration/poc-harness.md)).

Cheap lanes: `/quick-scan` and `/diff-audit` skip the full item-by-item walk.

Post-incident: **`/auditor:hunt`** (no alert) and **`/auditor:respond`** (lead in hand) hand all reading and analysis of the incident corpus to the **`incident-responder`** (opus; Read/Grep/Glob/Bash/Write/Edit, no sub-agents), one phase at a time, as the fork of the **`auditor:dnr-analyze`** skill, which pre-approves the offline analysis tools — hypothesis ledger, query-don't-read; the commands spawn `context-builder` for source confirmation and `poc-engineer` for the local PoC; it proposes and never acts on-chain. Its tool list has no MCP tools, so it cannot call a signing or transfer tool. The commands themselves run in your session, where every connected MCP server stays callable; they call no MCP tool. Before a live incident, disconnect or deny write-capable MCP servers (for example, tools that transfer or stake). Its `Bash` can still run the `solana` CLI, which signs with the local default keypair, so the agent never runs a subcommand that signs or sends, and only `OUTPUT-RULES.md` Rule 11a isolated mode with no keypair mounted confines it. Contract: [references/detection-response/README.md](references/detection-response/README.md).

Every agent that builds or runs target code — `poc-engineer`, `patch-engineer`, Trail of Bits harnesses — uses the execution mode recorded at intake (`OUTPUT-RULES.md` Rule 11a): the bundled runners, `templates/poc/run.sh --crate` and `scripts/runner/target.sh`, take the stricter of `<R>/exec-mode` and `AUDITOR_EXEC_MODE`, and in isolated mode stop when a credential is readable; a runner `poc-engineer` writes does the same through the mode lines `agents/poc-engineer.md` gives. Any outside service it contacts is listed in the report, from the run directory's `disclosures.tsv` and from what was run by hand (Rule 11b).

Full-lifecycle flows: **`/audit-cycle`** (fully automated → client report) and **`/audit-assist`** (human-in-the-loop, iterative); **`/re-audit`** for fix-review. See [references/audit-lifecycle/methodology.md](references/audit-lifecycle/methodology.md).

## Trail of Bits (vendored submodule)

Trail of Bits provides tool **execution** auditor-skill cannot do in prose (CodeQL/Semgrep taint, fuzzing, coverage, mutation, IR-level zeroize/constant-time analysis). It is a **reference, not a copy** — CC-BY-SA stays with Trail of Bits; auditor-skill's own corpus is MIT. Methodology patterns re-implemented natively are credited in `ATTRIBUTION.md`. If the submodule is not initialized, subagents fall back to native grep checks and say so in the report. The pinned commit is the one README.md names; it moves only through the review in CONTRIBUTING.md §5.