create-agent-rig 0.7.1 → 0.9.0

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

@@ -9,7 +9,9 @@
     "0.6.0",
     "0.6.1",
     "0.6.2",
-    "0.7.0"
+    "0.7.0",
+    "0.7.1",
+    "0.8.0"
   ],
   "files": {
     ".agents/skills/check-premises/SKILL.md": {
@@ -26,7 +28,8 @@
         "47922b182915cb92696f851174f2e88c4ae8c67dc119ef39a3a597ef1300fab5",
         "57f6add0504db45e7577474f97705fe474310e4cd3310cdb348a2c64eabe88cd",
         "18f4300de4c4c7ea380d726fb109fa224da950ef0a4cea5015ab1d408b823be5",
-        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d"
+        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d",
+        "a0d11ca1745095cc5b68777915161f16a6d1602c21f6d273f475d1d07c4b8546"
       ]
     },
     ".agents/skills/new-invariant/SKILL.md": {
@@ -59,7 +62,8 @@
       "hashes": [
         "a2fb0d03c65701af9d2d69cbcb2582ae573f097b1e1071eb2916e5e4f7832b37",
         "9616e4767942b2021e34ab7bb76eec9a5c280cc608a0756abb02743741d5fc8a",
-        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8"
+        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8",
+        "dc1d9c02879e383448f2336ae6433f960f86e8f8efb4ab8ccf9a17a5f7f524c3"
       ]
     },
     ".agents/skills/ro-debug/SKILL.md": {
@@ -227,7 +231,8 @@
         "ce2104ce697d3e5ed9210e85fe0daeb66b432a36868493f06fec54073a5fff31",
         "530f63a4b29a5cc67867fa7b23575db81d42609ae401bfc4089b05194c586c21",
         "a7359408d56e6bdbf268019ad9193d5fbf4a872385a65ba08564204e6a8f5b5f",
-        "619999500386b3d2867bbd4799f86a800fe7e168083c6e35fb2e629a2c926c5f"
+        "619999500386b3d2867bbd4799f86a800fe7e168083c6e35fb2e629a2c926c5f",
+        "532dc5cdffb1464fb68889628664b1e7e345272c806cf2ccb7a063c6a3a7f1bf"
       ]
     },
     ".claude/rules/aws-cdk.md": {
@@ -438,7 +443,8 @@
       "hashes": [
         "32f847a2a3a5136cabcb42f6447da9f8cf98e2d20512212ee5201461128d7798",
         "b62348a27bcaa1d62a0e4ddd53873fab6cb75f9af8e8c69d24f6ce81c592c4e3",
-        "b151045e8083c398e94571b35dc9568dfa0102abcb847cdf764f6f694914d53e"
+        "b151045e8083c398e94571b35dc9568dfa0102abcb847cdf764f6f694914d53e",
+        "f756b7ccc2a4459e58b2125408de1f91372cd6093bf6f4ed14e26dc2eb4190fc"
       ]
     },
     ".claude/scripts/revalidation-report.mjs": {
@@ -514,7 +520,8 @@
         "47922b182915cb92696f851174f2e88c4ae8c67dc119ef39a3a597ef1300fab5",
         "57f6add0504db45e7577474f97705fe474310e4cd3310cdb348a2c64eabe88cd",
         "18f4300de4c4c7ea380d726fb109fa224da950ef0a4cea5015ab1d408b823be5",
-        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d"
+        "0a1b6575f6df8139766c8e71ba7320e14d2a5a5ed8ab26b6b43f7a006153d37d",
+        "a0d11ca1745095cc5b68777915161f16a6d1602c21f6d273f475d1d07c4b8546"
       ]
     },
     ".claude/skills/new-invariant/SKILL.md": {
@@ -550,7 +557,8 @@
         "75adb84414a330db621ff4f1363b3926f537133199236a9e25bb9880b935e02e",
         "a2fb0d03c65701af9d2d69cbcb2582ae573f097b1e1071eb2916e5e4f7832b37",
         "9616e4767942b2021e34ab7bb76eec9a5c280cc608a0756abb02743741d5fc8a",
-        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8"
+        "a6340b95a03000b89fb27f5357cdd9c7ec12b714054b5334b61a30da600405e8",
+        "dc1d9c02879e383448f2336ae6433f960f86e8f8efb4ab8ccf9a17a5f7f524c3"
       ]
     },
     ".claude/skills/ro-debug/SKILL.md": {

package/templates/release-ledger.json

@@ -9,5 +9,7 @@
   "0.6.0": "29ca0543368e922349945e52541a92b46ddcc5bd",
   "0.6.1": "f1d1e3dbd2161545d77ee5e7f90fa8e74b8a9f3e",
   "0.6.2": "2a1fc8e10cd2b65deb5c95d937fd7de39f2c92a2",
-  "0.7.0": "6589db36e1daa63a99ec595191db1cccf7373196"
+  "0.7.0": "6589db36e1daa63a99ec595191db1cccf7373196",
+  "0.7.1": "52e879b6c103f6ba70493007b6a6466c57ea9824",
+  "0.8.0": "870f9a3ecae2881908ece8ec3e2ac13f84f505f5"
 }

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);