create-agent-rig 0.8.0 → 0.9.1

package/templates/agent-os/universal/docs/decisions/subagent-routing.md

@@ -0,0 +1,142 @@
+# Subagent routing: every gate pins its model and effort
+
+Status: accepted for RP-173 (Claude Code). The Codex half, RP-166, is recorded in
+`codex-adapter.md`. Both harnesses' routing comes from one role table: the Codex
+profiles are generated from it, and the Claude agent definitions are checked against it.
+
+## Decision
+
+Each named subagent this rig ships pins the model and the effort it reads with:
+
+| Role | Claude Code | Codex |
+| --- | --- | --- |
+| `code-reviewer`, `security-scanner`, a stack's infrastructure reviewer | `claude-opus-5`, `high` | `gpt-5.6-sol`, `high` |
+| `test-writer`, `prose-reviewer` | `claude-sonnet-5`, `high` | `gpt-5.6-terra`, `high` |
+| a subagent with no definition | `claude-sonnet-5`; effort follows the session | `gpt-5.6-terra`, `medium` |
+
+In this project the pins are the files themselves: `model:` and `effort:` in
+`.claude/agents/<role>.md`, `model` and `model_reasoning_effort` in
+`.codex/agents/<role>.toml`, `env.CLAUDE_CODE_SUBAGENT_MODEL` in
+`.claude/settings.json`, and the `[agents]` defaults in `.codex/config.toml`.
+
+The driver session's own model and effort are not pinned. They belong to whoever
+starts the session.
+
+## Why
+
+A gate that inherits the driver's model returns a verdict whose meaning changes
+whenever the driver does. Pinning makes the reader behind a SHIP a property of the
+rulebook rather than of how a session happened to be launched.
+
+- **Full model IDs, not aliases.** An alias moves when a new model ships, and every
+  verdict would change meaning without a diff. Moving a role to another model is a
+  policy change.
+- **The larger model reads correctness, security and infrastructure; the smaller one
+  does bounded, frequent work** — the same split as the Codex tiers.
+- **`high` for every gate, and escalation is a policy change.** A dispatch has no way
+  to set a subagent's effort — the `per-dispatch-effort` row below — so raising a
+  gate's effort is an edit to its definition, and nothing here invents a per-call knob.
+
+## How Claude Code resolves a pin, and what voids one
+
+Claude Code's changelog states two of the rules:
+
+- A subagent's model comes from the per-dispatch `model` first, then the
+  definition's `model:`, then `CLAUDE_CODE_SUBAGENT_MODEL`, then the parent session —
+  and that order holds from **2.1.251**. Before it the environment variable overrode
+  definitions, so the unnamed default this rig sets would replace every gate's pin.
+  That is why 2.1.251 is the version the session-start check warns below; it is
+  the release that makes the MODEL pins outrank the shipped default, and nothing more
+  is claimed for it — the `effort:` field and the `Agent` tool name the guard matches
+  were observed working on 2.1.269 and 2.1.270 only.
+- `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, added in 2.1.257, applies one model to every
+  subagent and ignores each definition's `model:`.
+
+The rest is measured. Each row records a live Claude Code run, read by a script from
+what Claude Code itself wrote — a subagent transcript, a hook's payload or a hook's
+environment — never from a subagent's own report. The rows are the generator's
+`docs/capability-evidence.json` (absent in a generated rig), keyed by `mechanism`
+and `surface`:
+
+- `subagent-model-pin` and `subagent-effort-pin` hold under a driver on another model
+  and effort (surface `.claude/agents/test-writer.md`);
+- `subagent-model-pin` does not hold with `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`, and
+  `subagent-effort-pin` does not hold with `CLAUDE_CODE_EFFORT_LEVEL=low` — each
+  variable replaced only the pin it names;
+- `subagent-model-pin` does not hold against a call-site `model` when no guard
+  refuses the dispatch;
+- `unnamed-subagent-model` holds and `unnamed-subagent-effort` is unsupported: a
+  subagent with no definition ran on the shipped default at the session's effort.
+
+Two mechanisms follow, both in `.claude/hooks/`. `guard-subagent-model` refuses a
+per-dispatch `model` for an agent whose definition pins one (`call-site-model-guard`).
+`warn-subagent-routing` warns at session start when either variable is set, when
+Claude Code is older than 2.1.251, or when its version cannot be read from `AI_AGENT`
+(`claude-code-version-signal`); it never blocks, because the variables are the
+operator's to set and the warning makes their cost visible instead of taking the
+decision. Pinned in `subagent-routing-hooks.test.ts` (absent in a generated rig)
+› "blocks a call-site model on a project agent that pins one, and says to re-dispatch without it"
+and › "warns when %s is set, and never blocks the session".
+
+Neither hook is wired for Codex, which has no dispatch hook and no Claude
+environment: `subagent-routing.test.ts` (absent in a generated rig) ›
+"keeps both routing hooks out of the Codex projection, which has no Agent tool and no Claude environment".
+
+## What this does not do
+
+- **The effort of a subagent with no definition is not pinned.** It runs at the
+  session's effort (`unnamed-subagent-effort`). That is recorded as unsupported, not
+  worked around.
+- **A definition says what was asked for; only the transcript says what ran.** A
+  verdict does not yet carry the model and effort it was produced on.
+- **The guard's notion of a role is "a project agent whose definition pins a model".**
+  In a generated project the definitions are the policy (next section), so an agent
+  a project adds with a pin is a role, and a role whose definition is changed to
+  `model: inherit` has stopped being one — by that project's reviewed decision.
+- **The built-in agents get no definitions here.** A general-purpose subagent follows
+  the unnamed default like any subagent without a definition.
+- **The warning is a warning.** A session started with `CLAUDE_CODE_EFFORT_LEVEL` set
+  still runs every gate — at that level.
+
+## Changing a role in this project
+
+The item this record implements asked that a project lower a default by editing
+"its policy", with "the test following". Here that is realised as follows, and the
+difference from a literal reading is deliberate:
+
+- **The agent definitions are this project's policy.** It receives no copy of the
+  generator's role table and no routing check: a second copy beside the definitions,
+  with no projector here to keep the two aligned, is the drift `rules/invariants.md`
+  forbids ("one mechanism, one implementation"), and the Codex half already shipped
+  that way.
+- **To move a role**, edit `model:` / `effort:` in `.claude/agents/<role>.md` and the
+  matching `.codex/agents/<role>.toml` in one reviewed change; both trees are
+  elevated paths.
+- **The test that follows the table lives in the generator**, where the expected
+  values are read from the table rather than restated.
+- **`upgrade` reports the edited agent file as yours and leaves it alone**, while an
+  agent file nobody edited is replaced by the release's pinned one —
+  `subagent-routing-install.test.ts` (absent in a generated rig) ›
+  "replaces an untouched pre-pin agent with the pinned one" and ›
+  "reports a pre-pin agent the user edited as a conflict and leaves its bytes alone".
+
+## In the generator
+
+`templates/agent-os/subagent-routing.json` is the one table.
+`scripts/sync-codex-adapter.mjs --check` loads it through `scripts/subagent-routing.mjs`,
+derives the Codex profiles from it, and refuses a Claude agent without `model` or
+`effort`, a value that differs from its role, a role without an agent or an agent
+without a role, an effort the pinned model does not support, an unknown field in
+either harness's mapping, and shipped settings that miss the unnamed default or set
+either voiding variable —
+`subagent-routing.test.ts` (absent in a generated rig) › "refuses a routing policy with %s"
+and › "refuses a Claude agent template whose model disagrees with the routing policy".
+
+## Risk and rollback
+
+A pinned model can be unavailable to an account. In the generator the recovery is
+changing the table and, in the same change, the Claude agent definitions checked
+against it; in a project it is changing the definitions as above — never a
+per-call override. Rollback in a project is deleting the `model:` / `effort:` lines,
+the `env` entry, and the two hooks with their wiring; every gate then inherits the
+session again.

package/templates/agent-os/universal/layers.json

@@ -16,6 +16,8 @@
     ".claude/hooks/inject-rules.mjs",
     ".claude/hooks/guard-secret-file.mjs",
     ".claude/hooks/guard-rulebook.mjs",
+    ".claude/hooks/guard-subagent-model.mjs",
+    ".claude/hooks/warn-subagent-routing.mjs",
     ".claude/hooks/lib/edit-input.mjs",
     ".claude/hooks/lib/hook-input.mjs",
     ".claude/skills/pr-ship/SKILL.md",
@@ -69,6 +71,7 @@
     "docs/decisions/gate-coverage.md",
     "docs/decisions/fail-open-guards.md",
     "docs/decisions/codex-adapter.md",
+    "docs/decisions/subagent-routing.md",
     "docs/decisions/closing-a-task.md",
     "docs/decisions/content-blind-revalidation.md",
     "docs/decisions/review-lanes.md",
@@ -84,6 +87,7 @@
   ],
   "meta": [
     ".claude/settings.json",
+    ".codex/config.toml",
     ".codex/hooks.json",
     "CLAUDE.md",
     "AGENTS.md"

package/templates/hash-history.json

@@ -10,7 +10,9 @@
     "0.6.1",
     "0.6.2",
     "0.7.0",
-    "0.7.1"
+    "0.7.1",
+    "0.8.0",
+    "0.9.0"
   ],
   "files": {
     ".agents/skills/check-premises/SKILL.md": {
@@ -27,7 +29,9 @@
         "47922b182915cb92696f851174f2e88c4ae8c67dc119ef39a3a597ef1300fab5",
         "57f6add0504db45e7577474f97705fe474310e4cd3310cdb348a2c64eabe88cd",
         "18f4300de4c4c7ea380d726fb109fa224da950ef0a4cea5015ab1d408b823be5",
-        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d"
+        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d",
+        "a0d11ca1745095cc5b68777915161f16a6d1602c21f6d273f475d1d07c4b8546",
+        "b47bdf0d7a2f6c5b2034b8f6d683ad2b3c83bd65d15baf7de9b58cc4689d0ab1"
       ]
     },
     ".agents/skills/new-invariant/SKILL.md": {
@@ -81,7 +85,8 @@
       "hashes": [
         "2286fbc01c0342b9bac9909890876c079615db5b398e3499a0f2fddb1a334098",
         "4c6241da56060b44e77f9b5f7a8cde7d2923bd605b8b9bae70d00329784c35be",
-        "03f87fbc976d8d65287b032ae3612511fc8f7e57772470b2282b660343fc32db"
+        "03f87fbc976d8d65287b032ae3612511fc8f7e57772470b2282b660343fc32db",
+        "5ec51bc08c9a934bfcbb2077fc7edce48c0e0cc3ed117d7dfc8a2895f2d9c01b"
       ]
     },
     ".claude/agents/code-reviewer.md": {
@@ -91,7 +96,8 @@
         "be3d2992d1f278dde46b555df1840b02f91403db1ec2fd4d489fb5efa940f019",
         "ec403373ef6bc0575d61c6ca11f82792817b272221fad8317ef6c45388b52628",
         "f125cfbce848cdaa91fd81e961808b4dbde452287959ec2cf10b905ee3ede789",
-        "8ede9297480c889ec6d6caf8d076e7d69111fb472933dcf5a48b9a8425fe50c2"
+        "8ede9297480c889ec6d6caf8d076e7d69111fb472933dcf5a48b9a8425fe50c2",
+        "f12cb04871578eca3c9c36a1c2d60f5ae15a0e9094ecfc7c704c341756de4e3e"
       ]
     },
     ".claude/agents/prose-reviewer.md": {
@@ -100,7 +106,8 @@
         "8d5762849afd328fdc1aabf053ad207f2e306e013665e3ff934b06cbb1bbda38",
         "0e4307cd9cf8ef723d79e98b1af46a34c6912a6aa925e2179d939cb83c8f2a44",
         "7e8eaa2b4af9d65e1d10bf50c32c1d138fb2f8b9ba6e6d0880cade0524324d9d",
-        "ed1c05d3938c0b4f277f1bf4af8641460def830569049ff0697c9bda14518b78"
+        "ed1c05d3938c0b4f277f1bf4af8641460def830569049ff0697c9bda14518b78",
+        "7aed3bfc955efc94bbeda3f866d25e2b253c88facaa2beed73939182a9f845b2"
       ]
     },
     ".claude/agents/security-scanner.md": {
@@ -108,13 +115,15 @@
       "hashes": [
         "43e5d59315483e369ad19f3070175f146e88deabd3a12dc09339ac4fac0f2aee",
         "e01467a38a0183be46ba45b05d44f663fbf4b139ceaecb91b5d096f3286a3fcd",
-        "844e215af7d80bd85f62ca937c79bea59c8d8cd7c97353937ce62f7747eb9df7"
+        "844e215af7d80bd85f62ca937c79bea59c8d8cd7c97353937ce62f7747eb9df7",
+        "7c0bc189521955f2d126bac0ff97ab4fa252b05067692a5a3bb6cda232ddfaa3"
       ]
     },
     ".claude/agents/test-writer.md": {
       "since": "0.2.0",
       "hashes": [
-        "333feef12383dea51791ae4923c44ba542438de793f0792fb51d96aa15b8b1b8"
+        "333feef12383dea51791ae4923c44ba542438de793f0792fb51d96aa15b8b1b8",
+        "fce976938fdd1154641e405a557b67161daa34cf84de9ad35fa14287d13b7f9c"
       ]
     },
     ".claude/hooks/block-no-verify.mjs": {
@@ -178,6 +187,12 @@
         "5bf2896ec5e5f94fab20b52cd22418a4392778b40744602a087e320eeca3f688"
       ]
     },
+    ".claude/hooks/guard-subagent-model.mjs": {
+      "since": "0.9.0",
+      "hashes": [
+        "345cbd5f43171adb01cd46ad485fb61299f7135c00ff4217765993551aca3b38"
+      ]
+    },
     ".claude/hooks/guard-web-boundary.mjs": {
       "since": "0.2.0",
       "hashes": [
@@ -200,7 +215,8 @@
       "hashes": [
         "4f836bc3ff75a868ffe035b179ac9e7dc1ad7715d520677ff9f6aa5bfdb200eb",
         "0c191d326a7bb0bbfc110e2210f44b4aa39276e8db3779aaa4545cffd4e11863",
-        "572c671f8f2cad190fe2f144071954ac4d3b1357cab80a19bad584dd3b3768c8"
+        "572c671f8f2cad190fe2f144071954ac4d3b1357cab80a19bad584dd3b3768c8",
+        "6695698d2b38c79a12292601048dd0082a0cd18bf9e69c047d47679c2e6ecf67"
       ]
     },
     ".claude/hooks/lib/hook-input.mjs": {
@@ -210,6 +226,12 @@
         "3be3d4af4a25536d2a2bac0441a1370be7efafb5f8aa737b195bdce77db0091b"
       ]
     },
+    ".claude/hooks/warn-subagent-routing.mjs": {
+      "since": "0.9.0",
+      "hashes": [
+        "b95165243ebb60264c78b82ce01407669457fe33c0bf86ff2a5c117963c6bc6d"
+      ]
+    },
     ".claude/queue.json": {
       "since": "0.3.0",
       "hashes": [
@@ -229,7 +251,8 @@
         "ce2104ce697d3e5ed9210e85fe0daeb66b432a36868493f06fec54073a5fff31",
         "530f63a4b29a5cc67867fa7b23575db81d42609ae401bfc4089b05194c586c21",
         "a7359408d56e6bdbf268019ad9193d5fbf4a872385a65ba08564204e6a8f5b5f",
-        "619999500386b3d2867bbd4799f86a800fe7e168083c6e35fb2e629a2c926c5f"
+        "619999500386b3d2867bbd4799f86a800fe7e168083c6e35fb2e629a2c926c5f",
+        "532dc5cdffb1464fb68889628664b1e7e345272c806cf2ccb7a063c6a3a7f1bf"
       ]
     },
     ".claude/rules/aws-cdk.md": {
@@ -264,7 +287,8 @@
       "hashes": [
         "dbe8025e10583e03fee5056e88aa6b73e4399453711d9156d82528a02d6e0402",
         "9e60d0300e856a9b3f81ab748bf2c0a9de27233ad0aa58a8c7141413fa0f3cae",
-        "c8e9849a8fccd4e1e60b1ddc82937eb15aceb7f7c2afbd151b05e1bc966bfd2a"
+        "c8e9849a8fccd4e1e60b1ddc82937eb15aceb7f7c2afbd151b05e1bc966bfd2a",
+        "aa34a1eab572964b328ffa0044e96acb3e1c31491df0183460f06e5e6bba3b76"
       ]
     },
     ".claude/scripts/decision-router.mjs": {
@@ -349,7 +373,8 @@
         "ceb6d35fa028f9c5e5e2d5965c627095d5ba80c37191a584627b4bc645b6be15",
         "efa193dc543237d82dcb371fa1df6483ccd43c1db88d0e218f5d89769564974c",
         "bed44df40412a7edac96914de21edc796df604ddc275ff1a02764dfcc4d4ede7",
-        "b3893c365de37ef6d9d04ab933296b9fcf09a0886197d7e12313fa63eacdbd89"
+        "b3893c365de37ef6d9d04ab933296b9fcf09a0886197d7e12313fa63eacdbd89",
+        "37eeb4bdb50d7f6b1427bd02ec9815f39ad9142f35691ffadd8c0b626c6cdb00"
       ]
     },
     ".claude/scripts/queue/as-of.mjs": {
@@ -378,7 +403,8 @@
     ".claude/scripts/queue/gate-rounds.mjs": {
       "since": "0.5.0",
       "hashes": [
-        "7577674d5477cfc388594e4c301601e329d60741dfa0b2844be2cc94a3ab6283"
+        "7577674d5477cfc388594e4c301601e329d60741dfa0b2844be2cc94a3ab6283",
+        "deeb7a10772f906c7630bb3c295be1b61d7ebf0541b2a34debcb40c80e6d8f0e"
       ]
     },
     ".claude/scripts/queue/github-issues.mjs": {
@@ -398,7 +424,8 @@
         "7db3c17b781e6876b4822afd09e6affa97e46607b63d443975d987daf1f14464",
         "9edd70b5960f367958e8e7500150b4edd285c99869cca803e40e0537d2d347b0",
         "4cf917ac06708e1068dfe9f8bbebc9376c4748526bd669b9bea32929ba996d0a",
-        "b4a0789be7ad4b401de872edb06665bca349048178b4dd6c5db848ca44f7c977"
+        "b4a0789be7ad4b401de872edb06665bca349048178b4dd6c5db848ca44f7c977",
+        "19a04cdbdfd936213cea3a9a00a583a060a4a8d0356d6a6922ae1c2f593f16f1"
       ]
     },
     ".claude/scripts/queue/jira.mjs": {
@@ -478,7 +505,8 @@
       "hashes": [
         "060b001927d8b471f1c1a8c8851fbb4266d3b2edd674cccbd6c16c44b57b91dd",
         "7721ee19fd1bcf6902be3d359def40742d79b88f5d83e7e3ca22ba45ca3211aa",
-        "250292c9959916240bfc0fdf5987a864f6d54799de3d932dc6b85b776e62eaa9"
+        "250292c9959916240bfc0fdf5987a864f6d54799de3d932dc6b85b776e62eaa9",
+        "ad58b25f9ce30a1549b5047daa1e5b43c30352306aeceebacd638db86087e01f"
       ]
     },
     ".claude/scripts/verdict.mjs": {
@@ -495,7 +523,8 @@
         "55a6938b4d9967291a26e93301e34e5ffdef74a88f8c773a4d11b5d87d864fff",
         "713718fbb2cda132f05665b29b8f1108a6305729b5e7c789d2053d117c13e08e",
         "e588ab05bee707a099c80c9ea399008be31488e616f3db3c0598f66f3d1b3a52",
-        "a180578d6e6de6a21900ff2f8a8ade2242170d16d2dd95574e5004435d870b9b"
+        "a180578d6e6de6a21900ff2f8a8ade2242170d16d2dd95574e5004435d870b9b",
+        "44695f83e445c7da3257556a3decc70e79ef46d19da394d4d5dd4c9268c0b429"
       ]
     },
     ".claude/skills/check-premises/SKILL.md": {
@@ -517,7 +546,9 @@
         "47922b182915cb92696f851174f2e88c4ae8c67dc119ef39a3a597ef1300fab5",
         "57f6add0504db45e7577474f97705fe474310e4cd3310cdb348a2c64eabe88cd",
         "18f4300de4c4c7ea380d726fb109fa224da950ef0a4cea5015ab1d408b823be5",
-        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d"
+        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d",
+        "a0d11ca1745095cc5b68777915161f16a6d1602c21f6d273f475d1d07c4b8546",
+        "b47bdf0d7a2f6c5b2034b8f6d683ad2b3c83bd65d15baf7de9b58cc4689d0ab1"
       ]
     },
     ".claude/skills/new-invariant/SKILL.md": {
@@ -573,14 +604,16 @@
       "since": "0.5.0",
       "hashes": [
         "902dbace9532ec8e7a3c0cfd6ea0934227f087e345c0619923ec03512b26ba3e",
-        "55778d7fb9f778a33213590cc0a2dcf8e01026a1a93eed1c0f811ba4f1070721"
+        "55778d7fb9f778a33213590cc0a2dcf8e01026a1a93eed1c0f811ba4f1070721",
+        "5fbbb1431833692d56cd0d15249f1d024e53bb0ab63349842910a9fc90547f6a"
       ]
     },
     ".codex/agents/code-reviewer.toml": {
       "since": "0.5.0",
       "hashes": [
         "e0e3475404c95402f33d77ebb14001e289d26bb429205a0a73bdcef99b4a62c7",
-        "9ec92775791907f068d85ba58489236bd2bee69a8d769554ac530e8eadd5e374"
+        "9ec92775791907f068d85ba58489236bd2bee69a8d769554ac530e8eadd5e374",
+        "180c182cc909cc0b6c06cfa286f528f22b77189eee49cac067fdaaf2920f8bae"
       ]
     },
     ".codex/agents/prose-reviewer.toml": {
@@ -588,20 +621,29 @@
       "hashes": [
         "80b4631502d95c619ad060ce02cc8702b12574758ba7df8337ed63efa15d764d",
         "cfd516f72acdfd197c59ac3cbdd39d7b175976dbd3d9eef52825dfdc4f1e5b60",
-        "8687eacf0ad707a4f887e0714e82fca23fd005fa9ec8824faedfe99ca46333e1"
+        "8687eacf0ad707a4f887e0714e82fca23fd005fa9ec8824faedfe99ca46333e1",
+        "7c37e4dbd94980bee16396d0d46d97c5079e295d3eed4b3ed8f98d701e57b10d"
       ]
     },
     ".codex/agents/security-scanner.toml": {
       "since": "0.5.0",
       "hashes": [
         "9ee408789f237a0b55aac6a2472682a08f8696e1d1ff4918ea72766ac8535499",
-        "bc9aacca1ca3ed4ceac485f7cd1c6ff5a5405ac7be83419d6145499cc560ee91"
+        "bc9aacca1ca3ed4ceac485f7cd1c6ff5a5405ac7be83419d6145499cc560ee91",
+        "b529f02056948ff0ca179c96d9d47962c9c8064feccb68d3c970e7b1a2513fc9"
       ]
     },
     ".codex/agents/test-writer.toml": {
       "since": "0.5.0",
       "hashes": [
-        "bb89d93f57d70885d98cfbe428caa524e9c00e1ce30da235ed3318c1ba3c9606"
+        "bb89d93f57d70885d98cfbe428caa524e9c00e1ce30da235ed3318c1ba3c9606",
+        "ec9e61b2c16c97ed26d5bdda2b0f715a41b80c0af549d0f2bbb96d6ca4c4d8d7"
+      ]
+    },
+    ".codex/config.toml": {
+      "since": "0.9.0",
+      "hashes": [
+        "c41e34ef5c3bb606852269adeaf5678ce172dc7a7937514ac879152bbddea7f2"
       ]
     },
     ".codex/hooks.json": {
@@ -655,7 +697,8 @@
       "since": "0.5.0",
       "hashes": [
         "30e55d866d9a2c7359e594181070c63b1974d9df36e000caf419229284303a2e",
-        "ebf0ef61407944373c862d37e6a80d4965ece72304b931428c6b3fcc5d9527c4"
+        "ebf0ef61407944373c862d37e6a80d4965ece72304b931428c6b3fcc5d9527c4",
+        "46b68f9130d16a96278e03d0ddb14d99b678c5a239e4667aa79733e632e67505"
       ]
     },
     "docs/decisions/content-blind-revalidation.md": {
@@ -701,6 +744,12 @@
         "dc0c9f5988fc983eb5100a085e274691b1e88a3b54ab2797e00972c4d69d61c4"
       ]
     },
+    "docs/decisions/subagent-routing.md": {
+      "since": "0.9.0",
+      "hashes": [
+        "97bb882dd066a65a740780a836199ecef8887392c1ece02a92670ecf153988d3"
+      ]
+    },
     "docs/decisions/two-empty-endings.md": {
       "since": "0.5.0",
       "hashes": [

package/templates/release-ledger.json

@@ -10,5 +10,7 @@
   "0.6.1": "f1d1e3dbd2161545d77ee5e7f90fa8e74b8a9f3e",
   "0.6.2": "2a1fc8e10cd2b65deb5c95d937fd7de39f2c92a2",
   "0.7.0": "6589db36e1daa63a99ec595191db1cccf7373196",
-  "0.7.1": "52e879b6c103f6ba70493007b6a6466c57ea9824"
+  "0.7.1": "52e879b6c103f6ba70493007b6a6466c57ea9824",
+  "0.8.0": "870f9a3ecae2881908ece8ec3e2ac13f84f505f5",
+  "0.9.0": "c27f391e7395accaf09354f255a07e1b9e4710c1"
 }

package/templates/skeleton/node-service/services/api/test/artifact.test.ts

@@ -1,17 +1,16 @@
 // CD brief §2: node-service's deployable artifact must actually build and run.
 // This bundles the server, boots the bundle over a real socket, and closes the
 // path — proving the artifact is genuine, not a stub.
-import { execFile, spawn } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import type { AddressInfo } from 'node:net';
 import { createServer } from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { promisify } from 'node:util';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { runPackageManager } from './package-manager.js';
 
-const exec = promisify(execFile);
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 const dist = path.join(projectRoot, 'dist');
 
@@ -38,7 +37,7 @@ describe('deployable artifact (dist/)', () => {
       () => true,
       () => false,
     );
-    if (!built) await exec('pnpm', ['build:artifact'], { cwd: projectRoot });
+    if (!built) await runPackageManager(['build:artifact'], { cwd: projectRoot });
   }, 180_000);
 
   afterAll(async () => {

package/templates/skeleton/node-service/services/api/test/package-manager.test.ts

@@ -0,0 +1,40 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { runPackageManager } from './package-manager.js';
+
+const literalArgs = ['space value', '&|<>^%!()', 'single "double"', ''];
+
+describe('package-manager transport for the artifact fallback', () => {
+  let work: string | undefined;
+
+  afterEach(async () => {
+    if (work !== undefined) await rm(work, { recursive: true, force: true });
+  });
+
+  it('honors the trusted current pnpm CLI on every platform with literal argv and preserves a failing child output', async () => {
+    work = await mkdtemp(path.join(tmpdir(), 'artifact-package-manager-'));
+    const cli = path.join(work, 'pnpm-cli.cjs');
+    await writeFile(
+      cli,
+      [
+        'process.stdout.write(JSON.stringify(process.argv.slice(2)));',
+        "process.stderr.write('artifact transport stderr');",
+        'process.exit(7);',
+      ].join(''),
+    );
+
+    const failure = await runPackageManager(literalArgs, {
+      cwd: work,
+      env: { ...process.env, npm_execpath: cli },
+    }).catch((error: unknown) => error);
+
+    expect(failure).toMatchObject({
+      code: 7,
+      stdout: JSON.stringify(literalArgs),
+      stderr: 'artifact transport stderr',
+    });
+  });
+});

package/templates/skeleton/node-service/services/api/test/package-manager.ts

@@ -0,0 +1,51 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+const currentPnpmCli = (environment: NodeJS.ProcessEnv): string | undefined => {
+  const currentCli = environment.npm_execpath;
+  if (currentCli && /^pnpm(?:-cli)?\.(?:cjs|js)$/i.test(path.basename(currentCli)) && existsSync(currentCli)) {
+    return currentCli;
+  }
+  return undefined;
+};
+
+const pnpmCli = (environment: NodeJS.ProcessEnv): string => {
+  const currentCli = currentPnpmCli(environment);
+  if (currentCli) return currentCli;
+
+  const installedCli = path.join(
+    path.dirname(process.execPath),
+    'node_modules',
+    'pnpm',
+    'bin',
+    'pnpm.cjs',
+  );
+  if (existsSync(installedCli)) return installedCli;
+
+  const corepackCli = path.join(
+    path.dirname(process.execPath),
+    'node_modules',
+    'corepack',
+    'dist',
+    'pnpm.js',
+  );
+  if (existsSync(corepackCli)) return corepackCli;
+
+  throw new Error('Cannot locate pnpm JavaScript CLI; npm_execpath must name the installed pnpm CLI');
+};
+
+/** Runs the workspace package manager without passing its arguments through a Windows shell. */
+export const runPackageManager = (
+  args: string[],
+  options: Parameters<typeof exec>[2],
+): ReturnType<typeof exec> => {
+  const environment = options?.env ?? process.env;
+  const currentCli = currentPnpmCli(environment);
+  if (currentCli) return exec(process.execPath, [currentCli, ...args], options);
+  if (process.platform !== 'win32') return exec('pnpm', args, options);
+  return exec(process.execPath, [pnpmCli(environment), ...args], options);
+};

package/templates/skeleton/node-service/services/api/test/static-dir.test.ts

@@ -1,26 +1,27 @@
 // The composition root resolves the built web bundle relative to itself; the
 // resolution is a pure function so it can be tested without importing main.ts.
 //
-// What is NOT pinned here: the Windows half of the same defect — the old
-// `new URL(url).pathname` yielded `/C:/…`. Both expressions are identical on a
-// POSIX runner, so observing the difference would mean passing a path flavour
-// into `defaultStaticDirFor`, i.e. a parameter that exists only for the test.
-// The decision was to leave that hook out; percent-decoding below is the same
-// bug's POSIX-visible half, and it fails against the old expression.
+// This native absolute fixture exercises the platform root spelling and
+// percent-decoding without injecting a path flavor into the production helper.
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { describe, expect, it } from 'vitest';
 import { defaultStaticDirFor } from '../src/static-dir.js';
 
+const moduleUrl = pathToFileURL(
+  path.join(path.parse(process.cwd()).root, 'a b', 'proj', 'services', 'api', 'src', 'main.ts'),
+).href;
+
 describe('resolving the default static dir from the module url', () => {
   it('decodes percent-escapes in the path (a directory may contain a space)', () => {
-    const resolved = defaultStaticDirFor('file:///Users/a%20b/proj/services/api/src/main.ts');
+    const resolved = defaultStaticDirFor(moduleUrl);
 
     expect(resolved).toContain('a b');
     expect(resolved).not.toContain('%20');
   });
 
   it('points three levels up from services/api/src at apps/web/out', () => {
-    const resolved = defaultStaticDirFor('file:///Users/a%20b/proj/services/api/src/main.ts');
+    const resolved = defaultStaticDirFor(moduleUrl);
 
     expect(resolved.endsWith(path.join('a b', 'proj', 'apps', 'web', 'out'))).toBe(true);
     expect(path.isAbsolute(resolved)).toBe(true);