@ikon85/agent-workflow-kit 0.32.1 → 0.34.0

package/docs/adr/0002-capability-gated-orchestration.md

@@ -0,0 +1,70 @@
+# Capability-gated orchestration: scripted-workflow / native-subagents / direct, fail-closed, no emulation
+
+Status: accepted (2026-07-22, issue #167)
+
+`orchestrate-wave` fans out recon and building across agents. The mechanic that
+performs that fan-out is not the same on every host: one host exposes a scripted
+workflow runtime, another exposes native subagent spawn/wait primitives, a third
+exposes neither. The skill ships from one body for both surfaces, so the mechanic
+cannot be baked into the prose — and a wrong guess is expensive, because a wave
+that half-dispatches leaves worktrees and branches behind.
+
+We decided to select the mechanic from **proven, host-supplied capability
+evidence**, never from a surface name and never from the model's own belief
+about what it can call.
+
+1. **A capability matrix over normalized tool entries.** The host supplies an
+   inventory; `capabilityAdapter.claude` / `.codex` only normalize what was
+   handed to them and perform no ambient discovery. Each entry carries
+   `callable`, `permitted`, a schema, and `capabilities: string[] | "unknown"`.
+   `classifyCapabilities` returns exactly one of three paths, and
+   `selectOrchestrationReference` returns one discriminated target: a reference
+   path for A and B, the inline marker for C.
+2. **Fail closed, A → B → C.** Missing or `unknown` evidence never proves a
+   capability. Path A additionally requires the *literal* tool name plus every
+   named primitive individually proven; Path B requires proven spawn, wait, and
+   aggregate plus effective concurrency and thread capacity ≥2. Anything short
+   of that degrades to Path C — direct, serial, in the main thread — which is
+   always available.
+3. **Never emulate a missing primitive.** A host without a scripted workflow
+   runtime does not get a hand-rolled imitation of one. The degraded path is a
+   different, simpler recipe, not the same recipe with the primitive faked.
+4. **The report contract is path-independent.** Every path produces the same
+   schema-valid recon and builder reports (`src/lib/reportValidator.mjs`, mirrored
+   in `references/report-contracts.md`), and every path crosses the same
+   main-thread boundary: schema validation, then `reconcileReconReports`, then
+   `semanticVerify` on builder reports. A subagent's own PASS is a hypothesis.
+5. **Progressive disclosure.** `SKILL.md` carries only the selector, the
+   invariants, Path C, and pointers; each path's recipe lives in `references/`
+   and is loaded only when selected.
+
+## Considered options
+
+- **Route by surface name** (Claude → workflow, Codex → subagents): rejected —
+  it is a claim, not evidence. A verify spike against codex-cli 0.144.6 found
+  native spawn and wait callable and concurrency ≥2, yet the host exposed tool
+  entries with only a name and a description: no schema, no callable/permitted
+  flags, no thread capacity. Name-based routing would have selected Path B on a
+  host that cannot prove it.
+- **Emulate the missing primitive** (hand-rolled fan-out where no workflow
+  runtime exists): rejected — it reproduces the failure modes the runtime exists
+  to prevent (run identity, resume-exactly-once, runtime output validation)
+  without any of its guarantees, and it fails at the worst moment, mid-wave.
+- **Fail open on unknown evidence** (assume a capability when the host is
+  silent): rejected — the cost asymmetry is severe. A false Path C is slower; a
+  false Path A or B strands a partially dispatched wave.
+- **One monolithic SKILL.md carrying all three recipes**: rejected — every
+  session would pay for two recipes it will never run.
+
+## Consequences
+
+- The current Codex host selects Path C. `references/dispatch-subagents.md` is
+  written and tested but **dormant** until a host supplies the complete
+  normalized inventory; that dormancy is pinned from both sides by tests.
+- Adding a path means adding evidence requirements and a reference, not
+  branching the skill body.
+- Hosts that improve their inventory reporting gain a faster path with no skill
+  change — the selector picks it up as soon as the evidence arrives.
+- The B1 fan-out shape (`spawn_agents_on_csv` plus a host-enforced per-agent
+  `output_schema`) stays out of scope until its own version-pinned verify spike
+  returns a positive verdict.

package/docs/adr/0005-to-issues-is-the-planning-facade.md

@@ -0,0 +1,42 @@
+# to-issues is the single planning facade
+
+Status: accepted (2026-07-22, issue #197)
+
+The planning workflow exposes two mechanisms after `to-prd`: Feature PRDs are
+decomposed by `to-issues`, while Program PRDs are unfolded by a separately
+invoked `to-waves` skill which later calls `to-issues` for each wave. This makes
+the user identify an internal planning altitude even though the PRD already
+carries an explicit, durable identity that can select the correct mechanism.
+
+We decided that `to-issues` is the single user-facing Planning facade:
+
+1. A Feature PRD selects the existing atomic/promote mechanism.
+2. A Program PRD selects the existing program-graph engine currently owned by
+   `to-waves`, including its complete preview, validation, publication,
+   per-wave maturation, and execute-ready audits.
+3. Dispatch uses only explicit PRD identity (`prd: program` or its canonical
+   program type), never size heuristics or model judgment.
+4. The selected mode is reported visibly before mutation. Program mode retains
+   its full preview approval gate.
+5. `to-waves` remains an independently testable internal mechanism and may keep
+   a compatibility entrypoint, but routers and normal documentation always send
+   the user from `to-prd` to `to-issues`.
+
+## Considered options
+
+- **Keep two public next commands:** rejected because it leaks internal
+  decomposition mechanics and makes users repeat an altitude decision already
+  encoded in the PRD.
+- **Infer the mode from plan size or prose:** rejected because hidden heuristics
+  make the same command unpredictable and can publish the wrong board shape.
+- **Merge all program code physically into `to-issues`:** rejected because the
+  program graph is a coherent deep module with valuable separate tests; only
+  its public routing belongs behind the facade.
+
+## Consequences
+
+- The normal user path is always `grill → to-prd → to-issues`.
+- Feature and Program behavior remain distinguishable in audit output without
+  requiring the user to select their implementation skill.
+- Router, overview, skill prose, mirrors, and contract tests must agree on the
+  one-entry contract.

package/docs/adr/0006-routing-knowledge-access-and-policy-are-separate.md

@@ -0,0 +1,91 @@
+# Routing knowledge, access, and policy are separate
+
+Status: accepted (2026-07-22, Program #197)
+
+Planning cannot safely persist a concrete recommended model. Provider catalogs
+change, model names age, effort behavior differs by model, agent surfaces expose
+different controls, and a surface may reach another provider through a plugin
+or CLI transport. A recommendation that is correct in one session can therefore
+be nonexistent, unreachable, or unenforceable in the session that implements
+the work.
+
+We decided to keep three identities separate:
+
+1. The Kit-maintained **Evidence catalog** contains all known provider models
+   and observations, whether or not the active surface can use them. Each
+   decision-grade observation retains the complete configuration identity:
+   model, effort, harness, workload, source, benchmark version, uncertainty,
+   freshness, and cost.
+2. The user-local **Access graph** records the native and cross-provider paths
+   available from each agent surface. Claude Code and Codex attest only their
+   own runtime capabilities. A detected transport is not automatically approved,
+   and neither surface claims another surface's unverified capabilities.
+3. The user-local **Routing policy** records allowed surfaces and transports,
+   switching autonomy, optimization goals, and optional advanced overrides.
+   Personal choices do not alter catalog facts.
+
+Durable plans and issues contain only a provider-neutral **Routing intent**.
+At execution time a resolver compares all evidence-backed candidates, filters
+them through the Access graph and Routing policy, and produces a one-execution
+**Route decision**. It reports the best overall route separately from the best
+currently executable route. An unreachable preference follows the user's
+explicit handoff, fallback, or block policy.
+
+Every surface adapter declares how independently it can control model and
+effort: per spawn, through a named agent definition, through a session default,
+or not at all. Environment precedence is part of the capability proof. An AFK
+subagent requires enforced model and effort selection and emits a **Dispatch
+receipt** containing the requested and applied route, enforcement method, and
+policy/evidence revisions. Silent inheritance and unverified degradation are
+not valid AFK routes.
+
+Setup keeps the technical model behind a simple user decision. It presents a
+registry-driven list of familiar agent surfaces, preselects detected entries,
+and asks whether the Kit may switch automatically, ask before switching, or use
+only the current surface. Adapters establish providers, transports, model
+selectors, and effort controls. Model preferences and optimization overrides
+remain optional advanced settings.
+
+An existing installation without a routing profile receives this choice once
+through setup or the first compatible Kit update. Later updates perform a
+read-only preflight and ask again only when the profile is missing, invalid,
+materially stale, references a removed route, or a newly detected surface makes
+a meaningful choice available. Installing Kit mechanics and changing personal
+policy are separate transactions; unattended update never invents a decision.
+
+BenchLM may populate discovery, catalog, pricing, freshness, coverage, and
+corroboration signals. Its aggregate scores are not decision-grade routing
+observations because effort and harness identity may be collapsed and missing
+evidence may be estimated. DeepSWE, Artificial Analysis, OpenHands, Arena, and
+other benchmark-owner artifacts remain authoritative for the claims they
+actually measure. Local experience may calibrate policy but does not rewrite
+public evidence.
+
+## Considered options
+
+- **Persist a concrete model and effort in every issue:** rejected because the
+  recommendation ages and may not be executable on the implementing surface.
+- **Maintain separate Claude and Codex routing tables:** rejected because it
+  duplicates evidence, hides cross-provider routes, and lets the two surfaces
+  drift.
+- **Filter the shared table during setup:** rejected because current access is
+  a user/runtime fact, not a limit on routing knowledge.
+- **Ask users to describe transports and enforcement capabilities:** rejected
+  because these are adapter facts most users cannot answer reliably.
+- **Route directly from a composite leaderboard:** rejected because benchmark,
+  harness, effort, uncertainty, and workload boundaries would be lost.
+- **Re-run the routing interview on every Kit update:** rejected because a valid
+  user-owned profile should remain stable until a material choice changes.
+
+## Consequences
+
+- Model/provider churn updates the catalog and resolver without rewriting
+  durable issues.
+- Both Claude Code and Codex read one local policy while proving their own
+  execution capabilities independently.
+- Cross-provider dispatch is expressible without pretending that every surface
+  can reach every model.
+- The Kit must maintain source adapters, schema migration, capability probes,
+  last-known-good evidence, and dispatch receipts.
+- Different machines do not share personal routing state unless the user later
+  chooses an explicit export or private synchronization mechanism.

package/docs/agents/skills/local-ci.md

@@ -0,0 +1,89 @@
+<!-- setup-workflow: state=filled -->
+# Project layer — local-ci
+
+This repo is a Node + stdlib-Python repo with no database, no dev server and no
+typecheck step, so the two generic profiles map onto a short command set. Run the
+two commands below; do not infer others.
+
+Prerequisite once per clone (worktrees inherit it):
+
+```sh
+git config core.hooksPath .githooks
+```
+
+## Fast static guards
+
+The skill/manifest lints, ~3s, no network, no DB. This is exactly what
+`.githooks/pre-commit` runs, so a normal commit already covers it:
+
+```sh
+python3 -m unittest discover -s scripts -p 'test_skill_*.py' -q
+```
+
+## Full gate
+
+Mirrors the `test` job in `.github/workflows/ci.yml` step for step. Run it from
+the branch's worktree root before opening a PR:
+
+```sh
+npm test
+npm run kit:staleness
+npm run release:guard -- --base "$(git merge-base origin/main HEAD)"
+npm pack --dry-run
+```
+
+Notes on the individual steps:
+
+- `npm test` is `test:node` (`node --test`) plus `test:python`
+  (`python3 -m unittest discover -s scripts -p 'test_*.py'`). Several negative-path
+  tests print `[FAIL] …` lines by design; only the runner's own summary and exit
+  code decide red or green.
+- CI runs `npm install --ignore-scripts` first. Locally that is only needed after
+  a dependency change.
+- `release:guard` runs in CI on `pull_request` only, against
+  `github.event.pull_request.base.sha`. `git merge-base origin/main HEAD` is the
+  local equivalent; `git fetch origin main` first if `origin/main` is stale.
+- `npm pack --dry-run` catches packaging drift (a file added outside the
+  published set) without publishing anything.
+
+## Enforcement
+
+Since #220 the host **does** enforce: the `main protection` ruleset makes the CI
+job `test` a required status check on `main`, with no bypass actor. So the
+generic skill's "When the host CAN enforce" branch applies to this repo — the
+local gate is a pre-flight that shortens the feedback loop, not the only thing
+standing between a red branch and `main`.
+
+Layered, from cheapest to strongest:
+
+| Layer | Runs | Scope |
+| --- | --- | --- |
+| `pre-commit` | automatic, every commit | fast skill/manifest lints |
+| `pre-push` | automatic, every push | full `npm test` |
+| this full gate | explicit, before a PR | `npm test` + staleness + release guard + pack |
+| CI `test` | automatic, on the PR | the same set, machine-enforced at merge |
+
+Never bypass a hook with `--no-verify`.
+
+**Drift rule.** The full gate above and `.github/workflows/ci.yml` are two copies
+of one list. Change one, change the other in the same PR — otherwise the local
+gate goes green on a set the required check does not accept.
+
+## Contention
+
+Not applicable here. This repo has no dev server and the suites are process-level
+(`node --test`, `unittest`), so the generic boot-contention false-red guidance has
+no target. A red is a real red until an isolated re-run of that one test proves
+otherwise.
+
+## On a red
+
+1. Read the failing assertion — the guards print the exact drift (`file:line`,
+   the offending token, the missing manifest key).
+2. Fix the source. A guard that legitimately cannot be satisfied yet gets a
+   documented allowlist entry with a reason; never widen a guard silently.
+3. Re-run the single failing suite, then the full gate for sign-off.
+
+`kit:staleness` red almost always means the generated kit artefacts lag the
+skill sources — run `npm run kit:build` and commit the result rather than
+editing the generated output by hand.

package/docs/agents/wave-anchor-template.md

@@ -25,7 +25,7 @@ The **candidate stub** (Stage 1) has no cluster/Wave. On **`to-issues` promotion
 - **Source:** <board-to-waves | external-prd | raw-issue | plan | grill> *(provenance-neutral — the shape is the same regardless of origin; fill the following lines where they apply, delete where they don't)*
 - **Member issues:** #<a> #<b> #<c> … *(listed; linked via `to-issues` promotion, To-Do below)*
 - **Why together (firing criteria):** Gate=<Outcome> · <B1 code proximity / B2 type homogeneity / B3 dependency / B4 verify surface, where applicable>
-- **Size + risk:** ~<N> slices · Backend: <yes/no> · Model mix: <Model [Effort], e.g. Sonnet [medium] / Opus [high] / gpt-5.5 [medium]> · Risk: <low/medium/high — reason, e.g. race/cache/forecast/migration>
+- **Size + risk:** ~<N> slices · Backend: <yes/no> · Routing-intent mix: <judgment/development/mechanical + deep/balanced/light> · Risk: <low/medium/high — reason, e.g. race/cache/forecast/migration>
 - **`grill-needed`:** <no> | <yes — this session> | <yes — own session (too big/fuzzy)>
 
 ### To-Do (maturation: grill → to-prd → to-issues) — *(Stage 1/1p only; at promotion this whole checklist collapses to ONE line: `Maturation: grill <✓/–> · to-prd ✓ · to-issues ✓ (<Date>) — Wave gate + tracking open`)*
@@ -53,7 +53,7 @@ Order (WSJF-lite): visible + low-risk first → logic/backend → cleanup. Depen
 | 1 | ⬜ | <Slice title> | #<sub> | <—/🧭/🔬/📐/📝> | <closes #x / refs #y> |
 <!-- slice-table:end -->
 
-Status legend: ⬜ open · 🔄 in progress · ✅ merged #<PR>. **Every slice = one sub-issue** (`#<sub>`). **The volatile Status column is generated by `board-sync.py anchor-sync <anchor#>` from the board** (between the `<!-- slice-table:start/end -->` markers; `wrapup` Step 5e.1 calls it on merge) — monotone (never flips a `✅`/`🔄` back), drift-free idempotent; **stable plan columns (Slice/Gate/refs) stay hand-maintained** and survive verbatim. It appends missing sub-issue rows (gen-b split). **Don't delete the markers** — without them `anchor-sync` can't locate the table (the first run locates it via the `Status`+`Sub-Issue` header row and sets the markers itself). The native "Sub-issues progress" rollup is the secondary %-view. *(Slimmed in: Branch is derivable from the `feat/<#>-<slug>` convention, the model recommendation lives in the leaf's handoff, Backend? carried no navigation value — legacy anchors that still have those columns keep working, `anchor-sync` matches columns by header name and refreshes Branch/Blocked-by only where the column exists.)*
+Status legend: ⬜ open · 🔄 in progress · ✅ merged #<PR>. **Every slice = one sub-issue** (`#<sub>`). **The volatile Status column is generated by `board-sync.py anchor-sync <anchor#>` from the board** (between the `<!-- slice-table:start/end -->` markers; `wrapup` Step 5e.1 calls it on merge) — monotone (never flips a `✅`/`🔄` back), drift-free idempotent; **stable plan columns (Slice/Gate/refs) stay hand-maintained** and survive verbatim. It appends missing sub-issue rows (gen-b split). **Don't delete the markers** — without them `anchor-sync` can't locate the table (the first run locates it via the `Status`+`Sub-Issue` header row and sets the markers itself). The native "Sub-issues progress" rollup is the secondary %-view. *(Slimmed in: Branch is derivable from the `feat/<#>-<slug>` convention, provider-neutral routing intent lives in the leaf's handoff, Backend? carried no navigation value — legacy anchors that still have those columns keep working, `anchor-sync` matches columns by header name and refreshes Branch/Blocked-by only where the column exists.)*
 
 **Gate legend (retro):** `—` AFK build (`/implement`) · 🧭 design grill (`grill-with-docs-codex`, ADR) · 🔬 verify spike (read-only fact question) · 📐 trade-off/research (read-only, below grill threshold) · 📝 review note (not a build slice). A gate slice (🧭/🔬/📐) sits **before** its dependent build slice (gate-before-build) and blocks it.
 

package/docs/methodology.html

@@ -324,7 +324,7 @@
           <span class="station st-program">grill</span><span class="arrow">→</span>
           <span class="station st-program">Program document</span><span class="arrow">→</span>
           <span class="station st-gate">preview gate</span><span class="arrow">→</span>
-          <span class="station st-wave">to-waves</span><span class="arrow">→</span>
+          <span class="station st-wave">to-issues · Program mode</span><span class="arrow">→</span>
           <span class="station st-phase">phases stamped</span><span class="arrow">+</span>
           <span class="station st-wave">Wave 1…n + slices</span>
         </div>

package/docs/methodology.svg

@@ -49,7 +49,7 @@
 
   <!-- top branch: planned top-down -->
   <rect x="350" y="350" width="260" height="40" rx="7" fill="#2E3850" stroke="B2" stroke-width="1.2"/>
-  <text x="480" y="375" font-size="12.5" fill="#8FA9C4" text-anchor="middle">scale-check → grill → to-waves</text>
+  <text x="480" y="375" font-size="12.5" fill="#8FA9C4" text-anchor="middle">scale-check → grill → to-issues</text>
   <line x1="480" y1="390" x2="553" y2="430" stroke="#8A95A6" stroke-width="1.4" marker-end="url(#arrow)"/>
 
   <!-- main spine -->

package/docs/workflow.html

@@ -181,8 +181,8 @@
       <div class="sw-track" style="--lbg: var(--plan-bg);">
         <span class="station st-plan">scale-check</span><span class="arrow">→</span>
         <span class="station st-gate">grill</span><span class="arrow">→</span>
-        <span class="station st-plan">to-waves</span>
-        <span class="decision">preview gate · zero board writes until yes</span><span class="arrow">→</span>
+        <span class="station st-plan">to-issues</span>
+        <span class="decision">Program identity · preview gate · zero writes until yes</span><span class="arrow">→</span>
         <span class="station st-exec">orchestrate-wave</span>
         <span class="decision">per wave, often AFK</span><span class="arrow">→</span>
         <span class="station st-land">wrapup</span><span class="arrow">→</span>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/codex-exec.sh

@@ -4,6 +4,7 @@ set -u
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 PROC_HELPER="$SCRIPT_DIR/codex_proc.py"
 TESTED_VERSIONS=("0.137.0" "0.144.6")
+SUPPORTED_EFFORTS=("low" "medium" "high" "xhigh" "max" "ultra")
 STATE_ROOT=${CODEX_EXEC_STATE_ROOT:-${TMPDIR:-/tmp}/codex-exec-state}
 
 emit_json() {
@@ -118,10 +119,10 @@ preflight() {
 }
 
 parse_options() {
-  CODEX_BIN=codex PROFILE= MODE= SANDBOX= PROMPT= PROMPT_FILE= RUN_ID= TIMEOUT= PROBE_TIMEOUT= DEBUG_RETAIN=false
+  CODEX_BIN=codex PROFILE= MODE= SANDBOX= PROMPT= PROMPT_FILE= RUN_ID= TIMEOUT= PROBE_TIMEOUT= MODEL= EFFORT= DEBUG_RETAIN=false
   while (($#)); do
     case $1 in
-      --codex-bin|--profile|--mode|--prompt|--prompt-file|--run-id|--timeout|--probe-timeout)
+      --codex-bin|--profile|--mode|--prompt|--prompt-file|--run-id|--timeout|--probe-timeout|--model|--effort)
         (($# >= 2)) || { fail INVALID_ARGUMENT "Missing value for $1"; return 1; }
         case $1 in
           --codex-bin) CODEX_BIN=$2 ;;
@@ -132,6 +133,8 @@ parse_options() {
           --run-id) RUN_ID=$2 ;;
           --timeout) TIMEOUT=$2 ;;
           --probe-timeout) PROBE_TIMEOUT=$2 ;;
+          --model) MODEL=$2 ;;
+          --effort) EFFORT=$2 ;;
         esac
         shift 2 ;;
       --debug-retain) DEBUG_RETAIN=true; shift ;;
@@ -140,6 +143,22 @@ parse_options() {
   done
 }
 
+validate_route_controls() {
+  if [[ -z $MODEL && -z $EFFORT ]]; then
+    return 0
+  fi
+  local effort_supported=false supported
+  for supported in "${SUPPORTED_EFFORTS[@]}"; do
+    [[ $EFFORT == "$supported" ]] && effort_supported=true
+  done
+  if [[ -z $MODEL || -z $EFFORT \
+    || ! $MODEL =~ ^[A-Za-z0-9._:-]+$ \
+    || $effort_supported != true ]]; then
+    fail INVALID_ROUTE_CONTROL "Model and effort must be supplied together from the exact safe vocabulary"
+    return 1
+  fi
+}
+
 prepare_prompt() {
   local state_dir=$1
   TEMP_PROMPT="$state_dir/.prompt-input"
@@ -160,10 +179,14 @@ launch_round() {
   prepare_prompt "$state_dir" || return 1
   local command
   if [[ -z $thread_id ]]; then
-    command=("$CODEX_BIN" exec --json --sandbox "$SANDBOX" -)
+    command=("$CODEX_BIN" exec --json --sandbox "$SANDBOX")
   else
-    command=("$CODEX_BIN" exec resume "$thread_id" -c "sandbox_mode=$SANDBOX" --json -)
+    command=("$CODEX_BIN" exec resume "$thread_id" -c "sandbox_mode=$SANDBOX")
   fi
+  if [[ -n $MODEL ]]; then
+    command+=(-c "model=$MODEL" -c "model_reasoning_effort=$EFFORT")
+  fi
+  command+=(--json -)
   python3 "$PROC_HELPER" run --state-dir "$state_dir" --round "$round" \
     --profile "$PROFILE" --sandbox "$SANDBOX" --timeout "$TIMEOUT" \
     --probe-timeout "$PROBE_TIMEOUT" --prompt-file "$TEMP_PROMPT" \
@@ -252,6 +275,7 @@ PY
 
 new_run() {
   parse_options "$@" || return 1
+  validate_route_controls || return 1
   PROFILE=${PROFILE:-review}
   MODE=${MODE:-read-only}
   [[ $PROFILE == review || $PROFILE == build ]] || { fail INVALID_PROFILE "Profile must be review or build"; return 1; }
@@ -285,15 +309,18 @@ new_run() {
   state_dir=$(mktemp -d "$STATE_ROOT/codex-exec.XXXXXXXX") || return 1
   chmod 700 "$state_dir"
   run_id=${state_dir##*.}
-  printf '%s\n' "$run_id" >"$state_dir/run-id"
   printf '%s\n' "$PROFILE" >"$state_dir/profile"
   printf '%s\n' "$SANDBOX" >"$state_dir/sandbox"
+  printf '%s\n' "$MODEL" >"$state_dir/model"
+  printf '%s\n' "$EFFORT" >"$state_dir/effort"
   printf '1\n' >"$state_dir/next-round"
   chmod 600 "$state_dir"/*
   lease_token=$(acquire_lease "$state_dir") || {
     fail ACTIVE_RUN "Run state is already owned by another lifecycle action"
     return 1
   }
+  printf '%s\n' "$run_id" >"$state_dir/run-id"
+  chmod 600 "$state_dir/run-id"
   output=$(launch_round "$state_dir" 1 "$lease_token")
   rc=$?
   release_or_fail "$state_dir" "$lease_token" "$run_id" "$output" || return 1
@@ -307,16 +334,20 @@ new_run() {
 }
 
 resume_run_locked() {
-  local state_dir=$1 lease_token=$2 stored_profile stored_sandbox thread_id round
+  local state_dir=$1 lease_token=$2 stored_profile stored_sandbox stored_model stored_effort thread_id round
   [[ ! -f $state_dir/debug-retain ]] || {
     fail RUN_FINALIZED "Run was finalized with debug retention"; return 1;
   }
   [[ -f $state_dir/profile && ! -L $state_dir/profile \
-    && -f $state_dir/sandbox && ! -L $state_dir/sandbox ]] || {
-    fail INVALID_STATE "Persisted profile or sandbox state is missing or unsafe"; return 1;
+    && -f $state_dir/sandbox && ! -L $state_dir/sandbox \
+    && -f $state_dir/model && ! -L $state_dir/model \
+    && -f $state_dir/effort && ! -L $state_dir/effort ]] || {
+    fail INVALID_STATE "Persisted profile, sandbox, or route controls are missing or unsafe"; return 1;
   }
   stored_profile=$(<"$state_dir/profile")
   stored_sandbox=$(<"$state_dir/sandbox")
+  stored_model=$(<"$state_dir/model")
+  stored_effort=$(<"$state_dir/effort")
   [[ $stored_profile == review || $stored_profile == build ]] || {
     fail INVALID_STATE "Persisted profile is not in the exact allowlist"; return 1;
   }
@@ -328,6 +359,13 @@ resume_run_locked() {
     fail MODE_MISMATCH "Resume mode differs from persisted mode"
     return 1
   fi
+  if [[ -n $MODEL && $MODEL != "$stored_model" ]] || [[ -n $EFFORT && $EFFORT != "$stored_effort" ]]; then
+    fail ROUTE_CONTROL_MISMATCH "Resume model or effort differs from the persisted applied route"
+    return 1
+  fi
+  MODEL=$stored_model
+  EFFORT=$stored_effort
+  validate_route_controls || return 1
   SANDBOX=$stored_sandbox
   [[ -f $state_dir/thread-id ]] || { fail NO_THREAD "Run has no resumable thread" NO-THREAD; return 1; }
   thread_id=$(<"$state_dir/thread-id")
@@ -346,6 +384,7 @@ resume_run_locked() {
 
 resume_run() {
   parse_options "$@" || return 1
+  validate_route_controls || return 1
   [[ -n $RUN_ID ]] || { fail RUN_ID_REQUIRED "Resume requires --run-id"; return 1; }
   local state_dir lease_token rc output
   state_dir=$(find_state "$RUN_ID") || { fail RUN_NOT_FOUND "Run state does not exist"; return 1; }

package/scripts/codex-exec.test.mjs

@@ -143,6 +143,62 @@ test('invalid timeout and mode inputs fail before launch', () => {
   assert.equal(exists(fx.launchLog), false);
 });
 
+test('approved route passes explicit model and effort controls to Codex', () => {
+  const fx = fixture();
+  const result = invoke(fx, [
+    ...launchArgs(),
+    '--model', 'coding-model',
+    '--effort', 'high',
+  ]);
+  assert.equal(result.output.status, 'OK');
+  const command = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim());
+  assert.ok(command.includes('model=coding-model'));
+  assert.ok(command.includes('model_reasoning_effort=high'));
+
+  const resumed = invoke(fx, [
+    'resume', result.output.runId, '--codex-bin', fake,
+    '--prompt', 'Again', '--timeout', '2',
+  ]);
+  assert.equal(resumed.output.status, 'OK');
+  const resumeCommand = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim().split('\n').at(-1));
+  assert.ok(resumeCommand.includes('model=coding-model'));
+  assert.ok(resumeCommand.includes('model_reasoning_effort=high'));
+
+  const mismatch = invoke(fx, [
+    'resume', result.output.runId, '--codex-bin', fake,
+    '--model', 'other-model', '--effort', 'high', '--prompt', 'No',
+  ]);
+  assert.equal(mismatch.output.error, 'ROUTE_CONTROL_MISMATCH');
+});
+
+test('route controls fail closed when incomplete or unsafe', () => {
+  for (const args of [
+    [...launchArgs(), '--model', 'coding-model'],
+    [...launchArgs(), '--effort', 'high'],
+    [...launchArgs(), '--model', 'unsafe value', '--effort', 'high'],
+    [...launchArgs(), '--model', 'coding-model', '--effort', 'unknown'],
+  ]) {
+    const fx = fixture();
+    const result = invoke(fx, args);
+    assert.equal(result.output.error, 'INVALID_ROUTE_CONTROL');
+    assert.equal(exists(fx.launchLog), false);
+  }
+});
+
+test('current extended reasoning efforts are passed through explicitly', () => {
+  for (const effort of ['max', 'ultra']) {
+    const fx = fixture();
+    const result = invoke(fx, [
+      ...launchArgs(),
+      '--model', 'coding-model',
+      '--effort', effort,
+    ]);
+    assert.equal(result.output.status, 'OK', effort);
+    const command = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim());
+    assert.ok(command.includes(`model_reasoning_effort=${effort}`));
+  }
+});
+
 test('finalize deletes state, debug-retain preserves diagnostics, and finalized resume fails', () => {
   const fx = fixture();
   const run = invoke(fx, launchArgs()).output;

package/scripts/test_codex_adapter_sync_contract.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 ADAPTER = REPO_ROOT / ".agents/skills/codex-adapter-sync/SKILL.md"
+AGENTS_README = REPO_ROOT / ".codex/agents/README.md"
 _FRONTMATTER_SPEC = importlib.util.spec_from_file_location(
     "skill_frontmatter_lint", REPO_ROOT / "scripts/test_skill_frontmatter_lint.py")
 frontmatter = importlib.util.module_from_spec(_FRONTMATTER_SPEC)
@@ -39,27 +40,24 @@ class AdapterModesContract(unittest.TestCase):
         self.assertNotIn("before inventory or edits", self.body)
 
 
-class AdapterModelContract(unittest.TestCase):
+class AdapterRoutingContract(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         cls.body = ADAPTER.read_text(encoding="utf-8")
 
-    def test_current_models_inherit_by_default_and_route_by_task_shape(self):
-        routing = " ".join(section(self.body, "Model routing").split())
-
-        self.assertIn("inherited parent model configuration", routing)
-        self.assertIn("`gpt-5.6-sol`", routing)
-        self.assertIn("complex, open-ended judgment work", routing)
-        self.assertIn("`gpt-5.6-terra`", routing)
-        self.assertIn("everyday tool-using development", routing)
-        self.assertIn("`gpt-5.6-luna`", routing)
-        self.assertIn("clear, repeatable, high-volume work", routing)
-        self.assertIn("`model_reasoning_effort`", routing)
+    def test_durable_routing_is_provider_neutral_and_resolved_at_dispatch(self):
+        routing = " ".join(section(self.body, "Routing intent").split())
+
+        self.assertIn("`routing-intent`", routing)
+        self.assertIn("`reasoning-intent`", routing)
+        self.assertIn("Evidence catalog", routing)
+        self.assertIn("Access graph", routing)
+        self.assertIn("Routing policy", routing)
+        self.assertIn("dispatch time", routing)
+        self.assertIn("explicit `inherit`", routing)
+        self.assertIn("Dispatch receipt", routing)
         self.assertIn("`default`, `worker`, and `explorer`", routing)
-        self.assertIn("not a fourth concrete variant", routing)
 
-        for stale in ("gpt-5.4-mini", "gpt-5.5"):
-            self.assertNotIn(stale, self.body)
         self.assertNotRegex(self.body, r"(?<!model_)\breasoning_effort\b")
         self.assertNotRegex(self.body, r"\bagent_type\b")
 
@@ -104,6 +102,23 @@ class AdapterAgentContract(unittest.TestCase):
         self.assertIn("Parse every `.codex/agents/*.toml`", agents)
         self.assertIn("Reject a file", agents)
 
+    def test_codex_host_inventory_is_dated_and_does_not_invent_spawn_selectors(self):
+        inventory = " ".join(
+            AGENTS_README.read_text(encoding="utf-8").split()
+        )
+        for fragment in (
+            "2026-07-23",
+            "`task_name`",
+            "`message`",
+            "`fork_turns`",
+            "no per-spawn `model`",
+            "no per-spawn effort selector",
+            "`src/lib/routingAdapters/codex.mjs`",
+            "blocks differentiated AFK",
+            "Dispatch receipt v2",
+        ):
+            self.assertIn(fragment, inventory)
+
 
 class AdapterValidationContract(unittest.TestCase):
     @classmethod