Route each Claude agent definition to its table's model and effort - #1045

Scope

• What this PR changes, in one or two sentences: every shipped Claude agent definition ran at effort max; each now carries the model and effort of the command center's 2026-10-12 routing table (the blind roles and the landscape sweep keep their protocol's max), and a new decision record supersedes the 2026-09-23 max-effort default for effort, with the measurement of what decides a child's effort on Claude Code 2.1.296.
• Base commit: d6056831 (main, after fix(trading): accept paper host version paths in capacity env URLs #1069; first opened on 2f59d744, rebased five times, each time for a registry-only conflict in manifests/evidence.json). The last rebase (head 7906b883 to af1d2a6c) kept this change's own rows: all 34 registered files this change touches have a current row, and every non-registry file keeps its git patch-id --stable. The earlier rebase, at the landing cue (head 70ff2753 to 6c8348d2), re-registered this change's files with scripts/host_receipts.py register_file, not a hand merge. Every one of the 34 other changed files keeps its git patch-id --stable; validate.py passes. That rebase re-registered only the paths main's manifest already listed, so it dropped four rows this change had added. Astra's registry read at 6c8348d2 (P2) caught it, and 7906b883 restores them with register_file, each equal to its 70ff2753 row: .claude/agents/semantic-evidence-reviewer.md, source-scout.md, stack-verifier.md and docs/decisions/2026-10-12-model-effort-routing.md. ShippedAgentEffortTests.test_every_routed_definition_and_the_routing_record_are_registered fails at 6c8348d2 on exactly those four and passes here; validate.py checks only rows that exist.
• Lane: lane:foundation
• Owned paths touched: adoption/agents/claude/*.md, .claude/agents/*.md, examples/claude-native/agents/*.md (the three byte-identical copies), examples/claude-native/workflows/README.md (agent, routing and role tables; coordinator guidance), examples/claude-native/workflows/test-envelope.mjs and test-contract-mutations.mjs (and their SHA256SUMS), tests/test_install_claude_profile.py, tests/test_task_model_routing.py, tests/test_token_e2e_preregistration.py, docs/decisions/2026-09-30-task-model-routing.md (seven agent rows restated, addendum), evidence/artifacts/token-adoption-e2e-20260926/README.md (append-only Amendment 5: the five role-body pins), catalogs/foundation/decisions.json (the lean-workflow-child-routing activation text), docs/decisions/2026-10-12-model-effort-routing.md (new), docs/decisions/2026-09-23-max-effort-default.md (supersession banner), catalogs/foundation/upstream-surface-dispositions.json (four locators moved past the new lines, second commit), manifests/evidence.json (re-registration)

The table (agent: model, effort):

• source-scout, stack-verifier: Sonnet, medium (extraction, inventories, re-runs and claim checks without judgment)
• stack-researcher: Sonnet, high (research and synthesis on named sources)
• isolated-builder: Opus, high (builders, gate-code tier by default; a non-gate build is launched with a per-launch Sonnet)
• evidence-reviewer, security-reviewer, semantic-evidence-reviewer: Opus, xhigh (reviews)
• blind-lane-reviewer, blind-adjudicator, blind-judge, landscape-sweep-worker: Opus, max (unchanged, their protocol's value)

No definition is on Haiku: the only same-packet extraction trial (2026-09-21) scored Haiku at 9/14 against Sonnet's 14/14 (the record names no Haiku version), and Haiku 5.5 is unmeasured on that task; Haiku stays a per-launch choice for mechanical work.

What decides a child's effort on 2.1.296 (fresh headless one-turn probes and interactive children, read from the effort field of the native transcripts; full table in the decision record):

• An unnamed child: a per-launch effort, else its definition's, else the session's level. A session started with --effort max does not override either.
• A named child (launched with name, a teammate) in an interactive session: its definition's effort, else the session's level; a per-launch effort is dropped. The per-launch model is honored either way. Under -p or the Agent SDK the named case is not measured.
• So the command center's observation (23 named children at max despite per-launch efforts from low to xhigh) came from naming, not from the session flag, and in interactive sessions the definition is the lever that reaches every child (under -p or the Agent SDK the named case is not measured). Coordinator guidance, now in the workflows README and the registry: launch without name for a per-launch effort.

Follow-ups (not in this change):

• The launchers that still pass --effort max set the session level and that of named children whose definition sets none:
  • the command-center and trading launchers, outside this repository, which the ruling changes at each session's next relaunch;
  • the repository's own ecosystem launcher (adoption/bootstrap-linux.sh:907-924, adoption/bootstrap-macos.sh:1083-1096), inside this repository. It still adds --effort max to an interactive launch that names no effort, and this change leaves it as it is (the command center's Claude delta read, P2-B). A main session runs at the ruling's xhigh when launched with --effort xhigh. The coordinator's terminal default (docs/decisions/2026-09-29-max-default-effort.md) is not decided here.
• The saved workflows' stage effort (effort: 'max', the contract's STAGE_EFFORT) is unchanged; routing stages by work class is its own reviewed change.
• The recipes that narrate the 2026-09-23 rule (recipes/claude-native-ultracode.md, recipes/claude-native-profile.md) keep their dated sections; the old record's banner points to the new one.
• After landing: a 24-hour usage sample by model and effort (the ruling's after-measurement); hosts reinstall user-scope agents with tools/adoption/install_claude_profile.py.
• From Astra's full read at eb188d0f (ACK, no blockers). It carried to adf3d70b, a pure rebase by patch-id, and not to 1bb32f44: fix round 1 changes the tests, the README and the contract, so it is read as a delta. Four P3s (the first is taken in fix round 1):
  • Reader packets should carry captures of sub-agents.md, model-config.md and the cited changelog lines (mirror commit 3deb8736), and a sanitized structured record of the named-child observation without private transcript hashes.
  • The after-measurement should separate fresh from resumed children, user-scope reinstallation, scope overrides and restart exceptions, and report requested and resolved values apart.
  • Inherited hostname labels in the dispositions catalog and the evidence manifest; none is in the patch or this body. Not required for landing.
• From Astra's round-2 delta at 70ff2753 (ACK, no blockers):
  • The OSV oauthlib ignores expired on 2026-10-13. That is inherited from main and is the command center's incident; this change touches neither the config nor its tests.
  • test-contract-mutations.mjs:76, a comment outside the changed lines, still says a stage or agent off max must fail. At the next contract-comment edit it should say max for stages and the routed effort for definitions.
  • Source custody: the next native acceptance or reader packet should carry the documentation captures, sanitized probe results and a pinned source or measurement for the headless case. The 24-hour after-measurement keeps the cases listed above.
  • Gate briefs should give command results to the source-only reviewers, or use the unnamed Opus/xhigh verifier. The verifier's own body should carry the non-gate limit when role guidance next changes.
  • The changelog summary's plugin-defined qualifier is restored in this body edit.
  • Inherited hostname labels, as above.
• From the command center's Claude delta at 70ff2753 (PASS_WITH_P3):
  • P3-1: two README guidance lines still put project agents at max, and the envelope's stale-guidance pattern does not match them. One (:1195) says the lead and the project definitions both specify max; the other (:1197) says project agents declare effort: max. The next contract edit should correct both and extend the pattern, with a mutation for each.
  • P3-2: stale comments. test-contract-mutations.mjs:76-77 says an agent off max must fail, which :89-94 contradict, and test-envelope.mjs:442 still says "saved xhigh fallback".

Corrections (fix round 1, 1bb32f44). The command center's Claude read at eb188d0f (CHANGES_REQUESTED; Astra ACKed) found two P2s and P3s:

• P2-a: the decision record now carries the ruling's unchanged routing run 5 clause: Opus for trading, gate reads and sole-Claude-read micros, and Sonnet only for non-gate foundation work.
  • stack-verifier (Sonnet, medium) checks claims on non-gate work.
  • Gate verification uses evidence-reviewer, or stack-verifier launched without name and with a per-launch Opus at xhigh, because a named child drops a per-launch effort.
  • The README's agent, role and routing rows say so.
• P2-b: that a saved Workflow stage's effort wins over a definition's rests on Q3 of 2026-09-23-max-effort-default.md (Claude Code 2.1.281, Sonnet 5), not on the 2.1.296 probes, which were Agent-tool spawns. The envelope, the task-model-routing row and the decision record cite Q3 and say the rule is not re-measured on 2.1.296. Re-measuring needs a Workflow run; the record's after-measurement includes it.
• P3s:
  • source-scout's Sonnet/medium is stated as this record's departure from the ruling's Haiku/low row;
  • the named-child rule is scoped to the interactive sessions it was measured in;
  • changelog line 657 is quoted as the plugin-defined agent it names;
  • "Haiku 4.5" becomes the unversioned Haiku the cited record names;
  • the vacuous != effort: max test now exercises the routed check;
  • the README's coordinator rows follow the ruling's main-session xhigh, and the contract pin and its mutation move with them;
  • Astra's P3: the "effort max" guidance bullet and the envelope comments distinguish a saved stage's max from each definition's routed effort.

Corrections (fix round 2, 70ff2753). Astra's delta read and the command center's Claude delta read at 1bb32f44 both asked for changes. The command center accepted the source-scout departure: Sonnet at medium, for non-gate extraction, per routing run 5.

• P2-A (Astra's first blocker, which the Claude read agreed with):
  • Three places still put every project agent at max and said the contract fails an agent off max: the README's contract summary (:1076-1077), its task-matched-models bullet (:1098), and an envelope comment.
  • Each now says that a saved stage binds max and each project agent its routed effort (AGENT_EFFORT). The :1098 bullet's coordinator clause follows the routing row, as in round 1.
  • A contract assertion rejects the stale phrases, backed by three mutations, one of them replace-all.
• P2-B (the Claude read's): the repository's ecosystem launcher still adds --effort max, so the README must not say the launchers drop it at relaunch.
  • Changed: the routing paragraph (:1161), the coordinator row (:1165), the contract pin, its mutation, and the decision record's launcher alternative. They now say that launcher still adds the flag and that a main session gets xhigh with --effort xhigh.
  • A new assertion, with its mutation, rejects the relaunch claim.
  • The 2026-09-29 row the first Claude read had called stale was accurate.
• Fail-before: on 1bb32f44's README the envelope fails 3 of 256 checks: the coordinator pin, the stale per-agent phrases and the relaunch claim. Here it passes all 256. The mutations pass 80 of 80.
• The workflows SHA256SUMS and the evidence manifest follow the new bytes.
• Body: the earlier ACK is limited to adf3d70b (edited 2026-10-12, 23:51Z). The launcher sentence and the named-child scope above are fixed in this edit.
• Rebase: against main c63c83a8 the merge conflicts only in manifests/evidence.json; a registry-only rebase is ready on cue.

SOTA sources

• Claude Code sub-agents documentation, https://code.claude.com/docs/en/sub-agents.md, read 2026-10-12T17:01:02Z (sha256 dd3f22aa021a3525f48227321c34eab28b322d7ab77cb3d5fc01ddd048e8f6ea): line 316 (the effort frontmatter field overrides the session level, not CLAUDE_CODE_EFFORT_LEVEL) and lines 417-421 (a per-invocation effort overrides the field for a non-fork subagent, from 2.1.292).
• Claude Code model configuration, https://code.claude.com/docs/en/model-config.md, read 2026-10-12T17:01:02Z (sha256 8f65d1b1463bc7e24fa0eeeadd290278162b1f26c56be6190a1db510de8d7ca0): lines 605-613 (the session's effort resolution order; per-model levels for Opus 5.5).
• anthropics/claude-code CHANGELOG.md (local mirror; 2.1.296 at line 3): line 298 (2.1.292 added the Agent tool's effort parameter) and line 657 (a plugin-defined agent spawned by name runs with its own definition's effort; the named-child rule for project agents rests on this PR's own probes, not on that line).
• The installed client, claude --version 2.1.296, measured as above.

Evidence-class table

Local commands run

$ python3 -m unittest tests.test_install_claude_profile tests.test_adjudicate
Ran 254 tests ... OK (skipped=1)
$ (cd examples/claude-native/workflows && node test-envelope.mjs && node test-contract-mutations.mjs)
254 PASS, 0 FAIL; SUMMARY passed=76 failed=0 total=76
$ python3 -m unittest tests.test_install_claude_profile.ShippedAgentEffortTests   # on main's agent definitions
FAILED (failures=7)
$ python3 -m unittest <the 67 test modules that name the agent definitions, decisions.json, the routing records or the workflows> tests.test_evidence_manifest tests.test_validate
Ran 5385 tests in 2355.001s
OK (skipped=245)
$ python3 scripts/validate.py
Integrity and scope checks only; no live provider or GPU execution.   (rc 0)
$ python3 scripts/evidence_manifest.py --check
{"files": 11804, "status": "passed"}
$ gitleaks git --log-opts="origin/main..HEAD" --redact .
no leaks found   (rc 0)
# Second commit (adf3d70b after the rebases): CI shard 6 at the first head (1cd00190) failed DispositionCitationTests.test_every_cited_line_names_the_key
# three times (two records' lines moved down); four locators moved, each checked to name its key.
$ python3 -m unittest tests.test_upstream_surface_watch
Ran 116 tests ... OK (skipped=6)
# Fix round 1 (1bb32f44):
$ python3 -m unittest <the same 70 related modules> tests.test_evidence_manifest tests.test_validate tests.test_upstream_surface_watch
Ran 5538 tests in 2856.561s
OK (skipped=253)
$ (cd examples/claude-native/workflows && node test-envelope.mjs && node test-contract-mutations.mjs)
SUMMARY passed=254 failed=0 total=254; SUMMARY passed=76 failed=0 total=76
# Fix round 2 (70ff2753):
$ (cd examples/claude-native/workflows && node test-envelope.mjs)   # with 1bb32f44's README
SUMMARY passed=253 failed=3 total=256
$ (cd examples/claude-native/workflows && node test-envelope.mjs && node test-contract-mutations.mjs)
SUMMARY passed=256 failed=0 total=256; SUMMARY passed=80 failed=0 total=80
$ python3 -m unittest tests.test_adoption_bootstrap tests.test_install_claude_profile tests.test_context_mode_practice_docs tests.test_task_model_routing tests.test_native_practice_doc_corrections tests.test_token_e2e_preregistration tests.test_upstream_surface_watch tests.test_validate tests.test_evidence_manifest
Ran 465 tests in 30.539s
OK (skipped=11)
$ python3 scripts/validate.py; python3 scripts/evidence_manifest.py --check
(rc 0); {"files": 11858, "status": "passed"}
$ gitleaks git --log-opts="origin/main..HEAD" --redact .
no leaks found
$ git merge-tree --write-tree origin/main HEAD   # main c63c83a8
rc 1: CONFLICT (content) in manifests/evidence.json only

Decision record

docs/decisions/2026-10-12-model-effort-routing.md (supersedes docs/decisions/2026-09-23-max-effort-default.md for effort): the table, the probe evidence and the upstream lines, the alternatives (a per-launch effort only; the launcher flag only; Haiku for the scout) and the reopen rule.

Host evidence

Not applicable: no receipt changes.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a
  version comment (no floating tags). (none changed)
• New/changed workflows declare top-level permissions: {} and grant each job
  only what it needs (contents: read, or an explicitly justified addition). (none changed)
• No secrets are printed, logged or committed; no new required secret was
  added without a documented owner.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved (not deleted,
  moved or overwritten).

🤖 Generated with Claude Code