infraweaver 0.1.0

package/README.md

@@ -0,0 +1,244 @@
+# Infraweaver
+
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
+[![CI](https://github.com/infraweaver-io/infraweaver-action/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/infraweaver-io/infraweaver-action/actions/workflows/test.yml)
+[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](package.json)
+
+**Infraweaver brings your Terraform up to best practice — automatically, as reviewable pull requests.**
+
+> 🌐 **Languages:** [🇩🇪 Deutsch](docs/i18n/README.de.md) · [🇪🇸 Español](docs/i18n/README.es.md) · [🇵🇱 Polski](docs/i18n/README.pl.md) · [🇷🇴 Română](docs/i18n/README.ro.md) — condensed summaries; this English README is canonical.
+
+Infraweaver is an open-source ([AGPL-3.0](#licence)) GitHub Action and agent runtime. Point it at a
+repository and it scans the Terraform with standard deterministic tools, then opens **one scoped,
+reviewable pull request per concern** that fixes the issue and **proves it fixed** by re-scanning the
+branch (✗ → ✓). It never auto-merges — a human always reviews.
+
+- **It proves its own fixes.** The PR body records `✗ → ✓ <rule> resolved`, produced by re-running the
+  same deterministic scanners on the branch. Anyone can reproduce it — evidence, not a claim.
+- **Tools decide, the LLM assists.** Findings come from `terraform fmt`/`validate`, tflint, Trivy and
+  Checkov — not the model's opinion. The agent only applies the minimal, constrained fix.
+- **One scoped PR per concern.** Small, reviewable diffs on stable `remediate/<id>` branches. Re-runs
+  update the existing PR rather than opening duplicates.
+- **Guardrails enforced in code, not prompts.** Terraform-only edits, no inlined secrets, no destroying
+  stateful data, never auto-merges — all fail-closed at push time.
+- **Module-aware.** Fixes land at the module source, version upgrades arrive as scoped `chore(deps)`
+  PRs, and resource piles become module calls only when a pure-`moved` plan proves the refactor is a
+  no-op.
+- **Bring your own key, no hosted backend.** Supply your own LLM key, pointed at an approved endpoint
+  where data residency matters. Nothing leaves your runner that you didn't configure.
+
+## Quickstart
+
+```yaml
+name: Infraweaver — Terraform remediation
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # weekly drift sweep
+
+permissions:
+  contents: write # push the remediation branch
+  pull-requests: write # open the PR
+
+jobs:
+  remediate:
+    runs-on: ubuntu-latest
+    steps:
+      # Pin third-party actions to a commit SHA — a tag can be force-repointed.
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      # install the Terraform best-practice toolchain (absent tools are skipped, never fatal)
+      - uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3
+      - uses: terraform-linters/setup-tflint@90f302c255ef959cbfb4bd10581afecdb7ece3e6 # v4
+      - uses: aquasecurity/setup-trivy@81e514348e19b6112ce2a7e3ecbafe19c1e1f567 # v0.3.1
+        with:
+          # renovate: datasource=github-releases depName=aquasecurity/trivy
+          version: v0.72.0 # pin the TOOL too: a SHA-pinned action still installs floating-latest
+      - run: pipx install checkov
+
+      - name: Run Infraweaver
+        uses: infraweaver-io/infraweaver-action@main
+        with:
+          mode: remediate
+          severity_threshold: medium # only act on medium+ concerns
+          max_prs: 1 # one scoped PR per run
+        env:
+          # bring your own LLM key (BYOK)
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ github.token }}
+```
+
+> **Ready-to-use workflows:** [`examples/`](examples/) has copy-pasteable workflows — scheduled
+> [remediation](examples/remediate.yml), [behaviour-preserving refactors](examples/refactor.yml),
+> [comment-triggered fixes](examples/comment-fix.yml), and the full
+> [SARIF + plan-gate + policy setup](examples/remediate-advanced.yml).
+
+## How it works
+
+```mermaid
+flowchart LR
+  A[Scan<br/>fmt · validate · tflint<br/>Trivy · Checkov] --> B[Concerns<br/>severity-ranked,<br/>grouped]
+  B --> C[Fix<br/>minimal change,<br/>Terraform-only]
+  C --> D[Validate<br/>fmt · validate · tflint]
+  D --> E[Plan gate<br/>optional, with creds]
+  E --> F[Open one<br/>scoped PR]
+  F --> G[Re-scan branch<br/>✗ → ✓ proof]
+  G -.->|regression / needs-human| H[Label for a human]
+```
+
+**Scanners find the problem, the agent applies the minimal fix, and the scanners verify it** before a
+single PR is opened. Coverage is inherited, not reinvented: findings come from the scanners Infraweaver
+runs (Checkov's 1,000+ policies, Trivy's AVD checks, tflint's provider rulesets, `fmt`/`validate`), so
+new upstream checks show up the day you update the scanner. The PR's **Validation (✗ → ✓)** section is
+the part you can trust without trusting Infraweaver — re-run the same scanners on the branch and
+reproduce it. Higher-risk fixes (a regression, a stateful destroy/replace, a large blast radius, a
+non-deterministic plan) get a `> [!CAUTION]` banner and a `needs-human` label.
+
+## How Infraweaver compares
+
+|                                              | Reports findings |   Fixes the code   |   Proves the fix   |      Opens a PR      | Auto-merges |
+| -------------------------------------------- | :--------------: | :----------------: | :----------------: | :------------------: | :---------: |
+| **Scanners** (Checkov, Trivy, tfsec, tflint) |        ✅        |         ❌         |         ❌         |          ❌          |      —      |
+| **Plan orchestrators** (Atlantis, Digger)    |        ❌        |         ❌         |         ❌         |  comments on yours   |     ❌      |
+| **Dependency bots** (Dependabot, Renovate)   |    ✅ (deps)     | ✅ (version bumps) |         ❌         |          ✅          |  optional   |
+| **Auto-fix AI bots**                         |     partial      |         ✅         |       rarely       |          ✅          |    often    |
+| **Infraweaver**                                |        ✅        |         ✅         | ✅ (✗ → ✓ re-scan) | ✅ (one per concern) |  **never**  |
+
+## Modes
+
+A run is one **mode** — the verb it performs. Pin it with the `mode:` input for a deterministic CI
+run (the Terraform CI modes ship an engine-owned prompt that a workflow can't override), or omit it
+to let Infraweaver pick from the trigger. Full reference: **<https://infraweaver.dev/docs/modes>**.
+
+| Mode | Commits? | What it does |
+| --- | :---: | --- |
+| **Assess** | ❌ | Read-only security/best-practice posture scan — the PR gate. |
+| **TerraformCodeReview** | ❌ | Read-only `*.tf`-only review of a human PR (security, state-safety, version pins, module hygiene). |
+| **PolicyGate** | ❌ | Read-only OPA/conftest policy gate (PASS / FAIL / INCONCLUSIVE). |
+| **DriftDetect** | ❌ | Read-only scheduled drift check — `terraform plan` vs live state. |
+| **ComplianceAudit** | ❌ | Read-only controls audit mapped to `required_controls`, emits OSCAL. |
+| **Remediate** | ✅ | Fixes the top finding group, one scoped PR, proven by a ✗→✓ re-scan. |
+| **Refactor** | ✅ | Behaviour-preserving modularise/normalise, proven `equivalent: true`. |
+| **RemediateAndRefactor** | ✅ | Fix + modularise in one PR with two distinct proofs. |
+| **UpdateDependencies** | ✅ | Bumps stale provider/module pins, proven by equivalence or a reviewed plan. |
+| **ModernizeDeprecated** | ✅ | Migrates deprecated patterns, one class per PR, proven by a reviewed plan. |
+| **CostOptimization** | ✅ | infracost-quantified rightsizing PRs (needs `INFRACOST_API_KEY`). |
+
+Plus general verbs auto-selected from the trigger — **Build**, **Review**, **IncrementalReview**,
+**AddressReviews**, **Fix**, **Plan**, **SummarizePr**, **ResolveConflicts**, **Task**. Infraweaver
+**never auto-merges** — every PR is left for human review.
+
+### Signed evidence
+
+The compliance artefacts (`terraform_emit_evidence`, `terraform_emit_vex`) can be **signed** with a
+detached Ed25519 signature so an auditor can verify them offline. Generate a keypair once, store the
+private half as a repo/org secret, and pass it to the runs that emit evidence:
+
+```bash
+# one-time: generate the keypair (private key never leaves your secret store)
+openssl genpkey -algorithm ed25519 -out infraweaver-signing.pem
+openssl pkey -in infraweaver-signing.pem -pubout -out infraweaver-signing.pub.pem   # publish this half
+base64 -w0 infraweaver-signing.pem   # → the INFRAWEAVER_SIGNING_KEY secret value
+```
+
+```yaml
+env:
+  INFRAWEAVER_SIGNING_KEY: ${{ secrets.INFRAWEAVER_SIGNING_KEY }}
+```
+
+Each artefact then ships with a sibling `.sig` plus the public key + fingerprint embedded in its
+`signature` metadata; verify with `infraweaver verify-evidence <bundle> <bundle>.sig <pubkey.pem>`.
+Without the secret nothing breaks — artefacts honestly record `"signature": null`.
+
+#### Keyless (Sigstore) attestation — no key to manage
+
+For a second, key-free tier, set `INFRAWEAVER_KEYLESS_SIGNING: true` on a GitHub Actions run that emits
+evidence. Infraweaver then also writes a `<artefact>.sigstore.json` — an in-toto attestation of the
+artefact (by sha256 digest) signed with the **workflow's ephemeral OIDC identity**: [Fulcio][fulcio]
+issues a short-lived certificate bound to *this repo + workflow + run*, and the signing event is
+recorded in the public [Rekor][rekor] transparency log. There is nothing to distribute — a verifier
+checks the certificate identity (the workflow + the GitHub OIDC issuer), auditable in a public log. It
+reuses the `id-token: write` permission Infraweaver already requires, so **no extra workflow permission
+is needed**, and it's best-effort (a Fulcio/Rekor hiccup never blocks emitting evidence). Verify it
+with the Cloud MCP server's `infraweaver_verify_keyless` tool.
+
+[fulcio]: https://github.com/sigstore/fulcio
+[rekor]: https://github.com/sigstore/rekor
+
+#### Verifying Infraweaver itself
+
+Evidence over trust applies to us too: don't take the code on faith, check it. Infraweaver is consumed
+from `main`, so there are no published release artefacts — you verify the tree you're running and the
+inventory it builds.
+
+```bash
+# 1. Build the CycloneDX SBOM from the same lockfile CI installs from, then
+#    Ed25519-sign it with your own key.
+pnpm sbom && pnpm sign:sbom
+
+# 2. Verify the signature offline — no network, no trust in npm or GitHub,
+#    using the public key shipped beside it.
+node -e "const s=require('./infraweaver.cdx.json.sig.json');require('node:fs').writeFileSync('pub.pem',s.public_key)"
+infraweaver verify-evidence infraweaver.cdx.json infraweaver.cdx.json.sig pub.pem
+```
+
+`infraweaver.cdx.json` is a **CycloneDX 1.7 SBOM of the locked dependency tree** — generated from
+`pnpm-lock.yaml` (what CI actually installed from), so it describes exactly what a run installs
+rather than a re-resolution of it. If you need it for a CRA or procurement dossier, that file plus
+the verification step above is the artefact set.
+
+> **What this does and does not prove.** The signature binds the inventory to bytes. It does not
+> assert the dependencies are free of vulnerabilities — that's what the SBOM is *for*: feed it to
+> your own scanner.
+
+## Documentation
+
+The full guides live on the docs site, **<https://infraweaver.dev/docs>**. The repo keeps the
+machine-generated references next to the code.
+
+| Doc                                              | What's in it                                                                                                                | Full guide                                 |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| [Action inputs & outputs](docs/action-inputs.md) | The complete `action.yml` reference (generated — never drifts)                                                              | —                                          |
+| Modes                                            | Every run mode — what it does, whether it commits, and how it proves its change                                             | <https://infraweaver.dev/docs/modes>          |
+| [Configuration](docs/configuration.md)           | Modes, comment-scoped runs, scoping out findings, the plan gate & OIDC roles, BYOK, SARIF, repo config, scheduling, modules | <https://infraweaver.dev/docs/configuration>  |
+| [Security model](docs/security-model.md)         | The code-level guardrails and the trust/data-privacy story (generated from `src/mcp/guardrails.ts`)                         | <https://infraweaver.dev/docs/security-model> |
+| [Native rules](docs/native-rules.md)             | The `source: infraweaver` findings no upstream scanner can produce, and the bands that decide each verdict                    | —                                          |
+| [Policy authoring](docs/policy-authoring.md)     | Turning a written standard into reviewable Rego with `policy_author`, enforced by `policy_check`                            | —                                          |
+| [MCP server (local)](docs/mcp.md)                | `infraweaver mcp` in your IDE + pairing with HashiCorp's terraform-mcp-server                                                 | <https://infraweaver.dev/docs/mcp>            |
+| MCP server (Cloud)                               | `@infraweaver/mcp-server` — read a connected repo's Cloud findings, health score & signed evidence from your IDE agent        | <https://infraweaver.dev/docs/mcp-cloud>      |
+| [Tools](docs/tools.md)                           | Every MCP tool the agent uses, and the CLI binaries they shell out to                                                       | <https://infraweaver.dev/docs/tools>          |
+| [Supported models](docs/models.md)               | The model catalog and how selection works (generated)                                                                       | —                                          |
+
+## Support
+
+- **Getting started / usage** — this README, the [docs](https://infraweaver.dev/docs), and the [`examples/`](examples/) workflows.
+- **Bug reports & feature requests** — open a [GitHub issue](https://github.com/infraweaver-io/infraweaver-action/issues).
+- **Security vulnerabilities** — **don't** use a public issue; see [Security](#security) below.
+
+## Contributing
+
+Contributions are welcome. Infraweaver standardises on **Node 24** and **pnpm 11**:
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+```
+
+All contributions are accepted under the [Contributor License Agreement](CLA.md) (enforced by the CLA
+Assistant on your first PR). There are no tagged releases — consumers reference the action at
+`@main`, and [Conventional Commits](https://www.conventionalcommits.org) prefixes keep the history
+readable. See
+[`CONTRIBUTING.md`](CONTRIBUTING.md) for the full development, commit, and action-pinning conventions.
+
+## Security
+
+Infraweaver runs AI coding agents with write access to repositories and CI secrets, and is positioned for
+security- and compliance-sensitive use. **Please don't open public issues for vulnerabilities** — report
+them privately via [GitHub Security Advisories](https://github.com/infraweaver-io/infraweaver-action/security/advisories/new).
+See [`SECURITY.md`](SECURITY.md) for scope, supported versions, and response targets.
+
+## Licence
+
+Infraweaver is licensed under the **GNU Affero General Public License v3.0 or later** (AGPL-3.0-or-later).

package/dist/agents/claude.d.ts

@@ -0,0 +1,113 @@
+import type { DispatchRecorder } from "#app/agents/dispatchMetrics";
+import { type AgentResult, type AgentRunContext } from "#app/agents/shared";
+import { type RunTokenQuota } from "#app/agents/tokenQuota";
+import type { TodoTracker } from "#app/utils/todoTracking";
+export declare const CLAUDE_EXEC_TOOL_DENY_RULES: string[];
+export declare function writeMcpConfig(ctx: AgentRunContext): string;
+/**
+ * Build the `--agents` JSON definition for the `loupe` subagent.
+ *
+ * The Claude Code path always runs against an Anthropic model (see
+ * resolveAgent), so we hardcode the cheaper-sibling downshift: lenses run
+ * on Sonnet, the orchestrator stays on whatever model `--model` was passed.
+ *
+ * Per-call model override is also possible (Task tool's `model` arg accepts
+ * 'sonnet' | 'opus' | 'haiku') and takes precedence over what's set here —
+ * we don't pass it; the per-subagent `model` field is the right default.
+ *
+ * The `model` is route-aware: the bare Anthropic-API id `claude-sonnet-5`
+ * is only valid on the direct API. On Bedrock (`eu.anthropic.…`) and Vertex
+ * (`@`-versioned) routes that id is rejected, and claude-code does not
+ * translate per-agent model names — so on those routes we omit `model`
+ * entirely and the lens inherits the orchestrator's (already valid) model.
+ *
+ * Kept in lockstep with the `claude-sonnet` alias in models.ts (the opencode
+ * path derives the same target via deriveSubagentModels); bump both together.
+ *
+ * The non-mutative + non-recursive contract is enforced by the prose system
+ * prompt baked into the agent — see action/agents/reviewer.ts for why we
+ * no longer wire per-agent `disallowedTools` here.
+ */
+export declare function buildAgentsJson(routeAware?: {
+    isBedrock: boolean;
+    isVertex: boolean;
+}): string;
+export declare function stripProviderPrefix(specifier: string): string;
+type RunParams = {
+    label: string;
+    cmd: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+    todoTracker?: TodoTracker | undefined;
+    onActivityTimeout?: (() => void) | undefined;
+    onToolUse?: ((event: {
+        toolName: string;
+        input: unknown;
+    }) => void) | undefined;
+    /** per-run token ceiling (LLM10). `label` is the accumulator's source key, so
+     *  a `--resume` retry is charged on top of the attempt it resumes rather than
+     *  replacing it. Absent → nothing to enforce. */
+    tokenQuota?: RunTokenQuota | undefined;
+    /** specialist-routing watch (agents/dispatchMetrics.ts). Passed as the bare
+     *  recorder rather than the whole `toolState` — this runner drives a
+     *  subprocess and has no business reading run state it cannot act on.
+     *  Optional for the same reason `tokenQuota` is: subagent and test call sites
+     *  have nothing to record. */
+    dispatchMetrics?: DispatchRecorder | undefined;
+};
+type ClaudeRunResult = AgentResult & {
+    sessionId?: string | undefined;
+    /** set when the failure was a synthetic-stop with a retryable provider
+     * status — the session is intact and worth a `--resume` retry. */
+    retryableTransient?: boolean | undefined;
+};
+/**
+ * Provider statuses worth a resume-retry: rate limit (429) and upstream 5xx
+ * (500–599, which includes Anthropic's 529 "overloaded"). Deterministic
+ * failures (401 auth, 400 validation) are excluded — resuming would just
+ * replay the same error at full cost.
+ */
+export declare function isRetryableApiStatus(status: number | null | undefined): boolean;
+/**
+ * Continue prompt for a `--resume` retry after a transient provider failure.
+ * The interrupted turn's tail may or may not have been applied server-side,
+ * so the prompt asks the model to re-check before repeating its last action.
+ */
+export declare const TRANSIENT_RESUME_PROMPT: string;
+/**
+ * Return the tail of `text` capped at `maxCodeUnits` UTF-16 code units,
+ * dropping any partial first line. used in the exit-non-zero stdout fallback
+ * so we never surface a truncated NDJSON event to operators —
+ * `result.stdout.slice(-2048)` would otherwise cut mid-line and produce a
+ * syntactically broken JSON fragment. code units rather than bytes because
+ * `String.prototype.slice` operates on UTF-16 units; for multi-byte UTF-8
+ * content the effective byte budget can be up to 4× the nominal limit.
+ */
+export declare function tailLines(text: string, maxCodeUnits: number): string;
+export declare function runClaude(params: RunParams): Promise<ClaudeRunResult>;
+/**
+ * managed Stop hook. swaps the old `--resume <sessionId>` follow-up
+ * subprocesses (reflection + every gate retry — cost audit on PR #792
+ * showed reflection alone burned ~$0.85 / 111K cache_write per Opus run,
+ * almost all of it wasted re-running `getAttachmentMessages` in the fresh
+ * process) for a `{decision: "block", reason: ...}` injection inside the
+ * live `queryLoop`. existing session context is already in the prompt
+ * cache so only the new reason text is fresh cache_write.
+ *
+ * the script is intentionally minimal — all decision logic lives in the
+ * sidecar gate server (`gateServer.ts`), which reads live `ctx.toolState`
+ * mutations from the same process the MCP server runs in. budget +
+ * one-shot tracking lives there too, so re-fires across multiple stops in
+ * one session are safe. claude-code's 8-consecutive-block override is the
+ * last-line backstop.
+ */
+export declare function buildStopHookScript(): string;
+export interface ManagedSettingsParams {
+    ctx: AgentRunContext;
+    stopHookPath: string | null;
+    pretoolGateScriptPath: string;
+}
+export declare function buildManagedSettings(params: ManagedSettingsParams): Record<string, unknown>;
+export declare const claude: import("#app/agents/shared").Agent;
+export {};

package/dist/agents/claudePretoolGate.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Claude Code `PreToolUse` hook source — written into `ctx.tmpdir` at runtime
+ * and registered via a tmpdir-scoped `settings.json` referenced by
+ * `--settings <path>` (see action/agents/claude.ts).
+ *
+ * Closes the subagent → state-mutating MCP tool path that motivated the
+ * 2026-05-18 zed-industries/cloud incident (`terralens` lens called
+ * `checkout_pr` mid-review and the orchestrator's next push clobbered an
+ * unrelated branch). Pairs with the `tool.execute.before` hook in
+ * action/agents/opencodePlugin.ts; both runtimes embed the same per-run deny
+ * set, derived from each MCP tool's `mutates` flag (`subagentDeniedToolNames`
+ * in action/mcp/server.ts).
+ *
+ * PreToolUse hook contract (verified against yasasbanukaofficial/claude-code
+ * `src/utils/hooks/hooksConfigManager.ts` and `src/utils/hooks.ts`):
+ *   - stdin: JSON with `hook_event_name: "PreToolUse"`, `tool_name`,
+ *     `tool_input`, `tool_use_id`, `session_id`, `cwd`, `transcript_path`,
+ *     and crucially `agent_id` / `agent_type` populated when the call
+ *     originates from a subagent (set by the SDK when a Task/Agent
+ *     dispatches a tool — see `createBaseHookInput` in claude-code source).
+ *   - exit 0 → allow, no output shown
+ *   - exit 2 → block tool call AND show stderr to model (this is the path
+ *     we want for the deny case — the subagent gets a clear refusal it can
+ *     reason about and pick a different action)
+ *   - other → show stderr to user only, continue with tool call
+ *
+ * The hook itself is intentionally tiny: stdin → JSON → check `agent_id`
+ * presence + `tool_name` against the deny list → exit 0 or 2. No deps.
+ *
+ * Why the script source is a string template, not a separate `.ts` file
+ * shipped with the action: the action runs as a published npm package; at
+ * install time we don't have the source on disk in a stable place. Embedding
+ * the source into `dist/main.mjs` and writing it out per-run keeps the path
+ * inside `ctx.tmpdir` (where `--settings` can find it) and survives bundle
+ * minification.
+ */
+/**
+ * The pinned `@anthropic-ai/claude-code` version against which the subagent
+ * gate's `agent_id` discriminator was last verified (see the contract notes in
+ * the gate source below). The gate fails OPEN for subagents if claude-code ever
+ * stops populating `agent_id` in the PreToolUse hook payload, so a version bump
+ * must be paired with a re-verification of `createBaseHookInput`.
+ *
+ * `claudePretoolGate.test.ts` asserts this equals the version pinned in
+ * `package.json` — that test fails on any bump, forcing the re-verification
+ * before the pin and this constant are updated together.
+ *
+ * 2.1.220 verified 2026-07-28 against the schema embedded in the shipped
+ * binary: the base hook input still declares `agent_id` as
+ * `string().optional().describe("Subagent identifier. Present only when the
+ * hook fires from within a subagent (e.g., a tool called by an AgentTool
+ * worker). Absent for the main thread, even in --agent sessions. Use this
+ * field (not agent_type) to distinguish subagent calls from main-thread
+ * calls.")` — exactly the discriminator the gate relies on, byte-for-byte
+ * unchanged from the 2.1.198 verification (2026-07-10), itself unchanged from
+ * 2.1.195 (2026-07-01) and 2.1.190 (2026-06-25), which was more explicit than
+ * the 2.1.177 schema it replaced. The 2.1.220 pass additionally confirmed the
+ * field is still POPULATED and not merely declared — the minified bundle
+ * assigns `agent_id` from real identifier sources (`e.agentId`,
+ * `e.parentAgentId`, `e.data.agentId`), not a hardcoded empty value.
+ *
+ * Scope of this verification, stated honestly: it is static inspection of the
+ * shipped binary. No CI job exercises the Claude subagent gate against a live
+ * agent — `security-tests.yml` is deliberately opencode-only (free keyless
+ * model; Claude Code cannot use an `opencode/*` gateway model). So this pin,
+ * plus the tripwire test, IS the contract check. Keep both.
+ */
+export declare const CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION: "2.1.220";
+/**
+ * Source written to `<ctx.tmpdir>/infraweaver-pretool-gate.mjs`. Plain ESM,
+ * no TypeScript, no dependencies — node executes it directly via the
+ * `#!/usr/bin/env node` shebang and the executable bit set by the harness.
+ *
+ * `deniedTools` is the per-run deny set derived from each MCP tool's `mutates`
+ * flag (see `subagentDeniedToolNames`), embedded into the hook's `Set` literal so
+ * the gate fences exactly the mutating tools registered for this run — no
+ * hand-maintained list to drift.
+ */
+export declare const CLAUDE_PRETOOL_GATE_FILENAME: "infraweaver-pretool-gate.mjs";
+/**
+ * Claude Code's native file-writing tools. The gate intercepts these to enforce
+ * `allowed_paths` / `protected_paths` at WRITE time; without them the only
+ * enforcement is the push-time diff scan, which lets a disallowed file exist in
+ * the tree for the rest of the run (see action/agents/writePolicy.ts).
+ *
+ * `MultiEdit` is included even though recent claude-code folds it into `Edit` —
+ * an extra name in the matcher is inert, a missing one is a hole.
+ */
+export declare const CLAUDE_WRITE_TOOL_NAMES: readonly ["Write", "Edit", "MultiEdit", "NotebookEdit"];
+export declare function buildClaudePretoolGateSource(deniedTools: readonly string[], writePolicyAbsolutePath: string): string;
+/**
+ * Settings JSON shape registered via `claude --settings <path>`. The
+ * matcher `^mcp__infraweaver__` is treated as a regex by claude-code's
+ * `matchesPattern` helper (anything outside `[a-zA-Z0-9_|]` triggers the
+ * regex branch — verified in src/utils/hooks.ts), so this anchors at the
+ * start of the tool name and fires for every Infraweaver MCP tool. We narrow
+ * inside the script itself rather than declaring per-tool matchers because
+ * the deny list is the source of truth.
+ *
+ * The hook process inherits the parent's PATH, so `node` resolves to the
+ * runner's node binary; the `--settings` flag accepts either a path or a
+ * literal JSON string per claude-code source `src/main.tsx` (`Path to a
+ * settings JSON file or a JSON string`), but we use a path so the script
+ * and its config sit side-by-side under `ctx.tmpdir`.
+ *
+ * `execToolDenyRules` are the native exec tools (Bash/Monitor/REPL/Workflow +
+ * their `Agent(...)` forms) to deny at a settings-source rule — the
+ * authoritative, bypass-immune layer. `--disallowedTools` alone (a `cliArg`
+ * deny) was observed to leak under `--dangerously-skip-permissions`, so the
+ * deny is carried here too. Both consumers use both returned fields: the flag
+ * `--settings` JSON (covers non-CI runs) writes the whole object, and
+ * `buildManagedSettings` (CI, /etc managed settings) spreads `hooks` and folds
+ * `permissions.deny` into its richer deny list.
+ */
+export declare function buildClaudePretoolGateSettings(scriptAbsolutePath: string, execToolDenyRules: string[]): {
+    hooks: {
+        PreToolUse: Array<{
+            matcher: string;
+            hooks: Array<{
+                type: "command";
+                command: string;
+                timeout?: number;
+            }>;
+        }>;
+        /** layered in by writePretoolGateAssets so non-CI runs (no managed
+         * settings) still fire the gate-server Stop hook. */
+        Stop?: Array<{
+            hooks: Array<{
+                type: "command";
+                command: string;
+            }>;
+        }>;
+    };
+    permissions: {
+        deny: string[];
+    };
+};

package/dist/agents/dispatchMetrics.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Specialist-dispatch instrumentation.
+ *
+ * WHY THIS EXISTS. Review routing moved from a **count-parity** gate ("0 or 2+
+ * lenses, never exactly 1", gated on diff size) to **hypothesis coverage**
+ * (one specialist per falsifiable, load-bearing question, no size threshold).
+ * The evaluation that adopted it named its own risk plainly: the bar to
+ * dispatch *something* drops, each specialist re-reads the diff, so cost is
+ * "plausibly neutral-to-slightly-up" — and the recommendation was to ship it
+ * "behind a close watch on dispatch-rate/cost". See `docs/AGENT-HARDENING.md`.
+ *
+ * That watch never existed. Tokens were summed for the whole run with no split
+ * between the orchestrator and the subagents it dispatched, so the one number
+ * that would settle the question — what share of a run the specialists cost —
+ * was not observable at any point. "Plausibly neutral" was an assumption with
+ * no instrument behind it.
+ *
+ * WHAT IS MEASURED, AND HOW MUCH IT CAN BE TRUSTED. Two different qualities of
+ * signal, deliberately kept apart rather than blended into one number:
+ *
+ *   - **Dispatch counts are exact.** They are recorded from the actual Task
+ *     tool call, one per dispatch, not inferred from the event stream.
+ *   - **The token split is robust but coarse.** Tokens are attributed to
+ *     "orchestrator" vs "subagents", never per-lens. Per-session labels come
+ *     from `SessionLabeler`, whose own contract says its FIFO dispatch↔session
+ *     pairing is for log readability and is not depended on for correctness.
+ *     A mis-paired label would corrupt a *per-lens* number — but both sides of
+ *     a mis-pairing are still subagents, so the orchestrator/subagent split is
+ *     unaffected by exactly the weakness the labeler warns about. That is why
+ *     this file reports the split and not the breakdown.
+ *
+ * Deliberately NOT a database column. A new `WorkflowRun` field needs manual
+ * production DDL, and a metric nobody looks at is not a watch. This surfaces
+ * where the comparison actually gets made — the run's own log line and job
+ * summary — so "before/after the routing change" is two runs side by side.
+ */
+export interface DispatchTally {
+    /** subagent dispatches this run — exact, counted at the Task call. */
+    dispatches: number;
+    /** dispatch count per resolved label, e.g. `lens:iam-blast-radius`. */
+    byLabel: ReadonlyMap<string, number>;
+    /** billable tokens (input incl. cache + output) attributed to the orchestrator. */
+    orchestratorTokens: number;
+    /** …and to every subagent session combined. */
+    subagentTokens: number;
+}
+/**
+ * Per-run accumulator. Lives on `ToolState` and is written by whichever harness
+ * is driving, so the counts survive across agent invocations (post-run resume,
+ * transient-provider retry) the same way `usageEntries` does.
+ */
+export declare class DispatchRecorder {
+    #private;
+    /** Record one subagent dispatch. Call at the Task tool_use, not at completion:
+     *  a dispatch that errors out still cost the decision and usually the tokens. */
+    recordDispatch(label: string): void;
+    /**
+     * Attribute billable tokens to a session label. Anything that is not the
+     * orchestrator counts as subagent — including a session the labeler could not
+     * name, because an unnamed session is by definition not the orchestrator's.
+     */
+    recordTokens(label: string, billableTokens: number): void;
+    tally(): DispatchTally;
+}
+/** subagent share of attributed tokens, 0–1. Null when nothing was attributed —
+ *  distinct from 0, which means specialists genuinely cost nothing. */
+export declare function subagentTokenShare(tally: DispatchTally): number | null;
+/** One stdout line. Empty when the run dispatched nothing AND attributed nothing —
+ *  a solo run has no routing to report and the line would be noise. */
+export declare function describeDispatchTally(tally: DispatchTally): string;
+/**
+ * Markdown block for the GitHub job summary, rendered beside the usage table.
+ * Collapsed like the usage table so it costs nothing to ignore, and carries its
+ * own accuracy caveat: a reader comparing two runs needs to know the split is
+ * coarse before they draw a conclusion from it.
+ */
+export declare function formatDispatchSummary(tally: DispatchTally): string;

package/dist/agents/gateServer.d.ts

@@ -0,0 +1,7 @@
+import { type AgentRunContext } from "#app/agents/shared";
+export interface GateServerHandle {
+    url: string;
+    token: string;
+    [Symbol.asyncDispose]: () => Promise<void>;
+}
+export declare function startGateServer(ctx: AgentRunContext): Promise<GateServerHandle>;

package/dist/agents/index.d.ts

@@ -0,0 +1,6 @@
+import type { Agent } from "#app/agents/shared";
+export type { Agent, AgentUsage } from "#app/agents/shared";
+export declare const agents: {
+    claude: Agent;
+    opencode: Agent;
+};

package/dist/agents/nativeFsDenies.d.ts

@@ -0,0 +1,46 @@
+/** worktree-relative blanket WRITE deny for the entire `.git` tree, in
+ * OpenCode Wildcard dialect (`*` compiles to regex `.*`, matching `/`
+ * recursively — see packages/core/src/util/wildcard.ts). spread into the
+ * `edit` ruleset after a `"*": "allow"` baseline — `evaluate` is
+ * last-match-wins by key order, so the deny keys must follow the wildcard
+ * allow.
+ *
+ * four patterns, because the root-anchored descendants glob only matches
+ * paths under a root `.git` *directory* — it misses `.git` when it's a gitfile
+ * (worktree / submodule layouts: a regular file whose `gitdir:` line redirects
+ * git metadata) and misses nested gitfiles (a `.git` inside a subdirectory).
+ * rewriting either pointer is the same code-exec surface (`core.hooksPath`,
+ * clean/smudge filters, credential.helper) the blanket deny exists to seal, so
+ * we cover the gitfile itself and any nested `.git` too. */
+export declare const GIT_NATIVE_WRITE_DENY_OPENCODE: Record<string, "deny">;
+/** worktree-relative narrow READ deny (`.git/config` only), in OpenCode
+ * Wildcard dialect. spread into the `read` ruleset after the `"*": "allow"`
+ * baseline. */
+export declare const GIT_NATIVE_READ_DENY_OPENCODE: Record<string, "deny">;
+/** Claude `permissions.deny` entries for the blanket `.git` WRITE deny across
+ * BOTH write-capable native tools — mirrors {@link GIT_NATIVE_WRITE_DENY_OPENCODE}.
+ * Write is included so the agent can't PLANT a new hook/config file (e.g.
+ * `.git/hooks/pre-push`) that an Edit-only deny would miss. */
+export declare const GIT_NATIVE_WRITE_DENY_CLAUDE: string[];
+/** Claude `permissions.deny` entries for the narrow `.git/config` READ deny,
+ * one per read/enumerate tool — mirrors {@link GIT_NATIVE_READ_DENY_OPENCODE}. */
+export declare const GIT_NATIVE_READ_DENY_CLAUDE: string[];
+/** Claude `permissions.deny` entries protecting the harness-owned files in the
+ * per-run tmpdir (`infraweaver-*`: the PreToolUse gate script, the Stop hook
+ * script, the write-policy JSON, the flag settings). The tmpdir doubles as the
+ * agent's $HOME, so these paths are discoverable; the hook scripts are
+ * re-executed by claude-code with the full process env, which makes
+ * overwriting one arbitrary command execution outside every other deny. Both
+ * single- and double-slash forms are emitted, mirroring the secretDenyPaths
+ * pattern in buildManagedSettings. */
+export declare function harnessTmpdirWriteDenyClaude(tmpdir: string | undefined): string[];
+/** Claude `permissions.deny` (Edit+Write) keeping native file writes out of the
+ * out-of-workspace persistence/credential targets above. The agent runs with
+ * HOME pointed at a throwaway tmpdir, so the only way a poisoned native write
+ * reaches a file a later step trusts is an absolute path under the real runner
+ * $HOME — which these enumerate. Enumerated rather than deny-all on purpose:
+ * Claude's permission model has no allow carve-out under a broad deny (a
+ * `Edit(/**)` deny would also block the in-repo fix), and `sandbox.filesystem`
+ * governs only Bash — so "deny everything outside the repo" is not expressible
+ * for native tools. Returns [] when the runner $HOME is unknown. */
+export declare function runnerHomeWriteDenyClaude(runnerHome: string | undefined): string[];