@sublang/playbook 17.0.0 → 17.2.0

package/docs/cli.md

@@ -202,8 +202,8 @@ The former positional `<from>`, `resume`, `--player`, `--captain`,
 `--option`, `--cwd`, `--last`, run-only `--config`, and top-level `run:`
 config are removed from `playbook run`. Enable a registry under `playbooks`,
 declare provider agents once under top-level `players`, bind every local role
-under `playbooks.<id>.roles`, tune compatible model, effort, and fast mode in a `--with`
-overlay, invoke the effective `/command`, and run from the working directory
+under `playbooks.<id>.roles`, tune compatible model, effort, fast mode, and
+subagent model in a `--with` overlay, invoke the effective `/command`, and run from the working directory
 you want agents to use. Legacy `playbooks.<id>.players` blocks are rejected and
 are not auto-migrated because choosing equal or distinct new player IDs chooses
 conversation sharing or isolation; see [Migrating per-playbook
@@ -280,10 +280,11 @@ competing front end fails closed instead of forking the history.
 An ordinary reopen reads current config and any opening `--with` fragments,
 projects them to the stored catalog and player roster, and requires the stored
 role bindings plus every structural setting to remain exact. Compatible
-current `model`, `effort`, and optional `fastMode` settings apply to the next
-call. Boolean `false` explicitly resets model or effort to the provider
-default, but `fastMode: false` is a literal disabled request; omission selects
-the fast-mode provider default or inherits the player value at a role binding.
+current `model`, `effort`, and optional `fastMode` and `subagentModel` settings
+apply to the next call. Boolean `false` explicitly resets model, effort, or
+subagent model to the provider default, but `fastMode: false` is a literal
+disabled request; omission selects the provider default or inherits the player
+value at a role binding.
 Provider conversations are local hints. Missing hints start fresh from stored
 context; a definite pre-execution rejection permits one fresh attempt.
 Unsupported settings and ambiguous failures do not trigger that fallback

package/docs/configuration.md

@@ -48,8 +48,8 @@ names, nesting, and ancestry never infer a binding.
 
 Each `captain` or `players.<player-id>` value is either an adapter shorthand
 (`claude`, `codex`) or a block carrying that agent's own `adapter`, `model`,
-`effort`, `fastMode`, `instruction`, and `permissions`. Settings are inline per
-stable agent
+`effort`, `fastMode`, `subagentModel`, `instruction`, and `permissions`.
+Settings are inline per stable agent
 ([DR-021](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/021-inline-agent-settings.md)).
 Dots in a player ID are literal characters, not YAML hierarchy. Other adapter
 IDs pass through to `tmux-play` with a warning because `playbook` cannot
@@ -62,8 +62,8 @@ exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
 The launcher seeds one adapter for the Captain and all stable players from
-locally visible credentials: Claude first, then Codex. It uses Claude Opus 5
-for Claude or GPT-5.6 Sol for Codex, with Captain and Coder at `high` effort
+locally visible credentials: Claude first, then Codex. It uses Claude Opus 5.5
+for Claude or GPT-6 Sol for Codex, with Captain and Coder at `high` effort
 and Reviewer and Analyst at `xhigh`. If neither adapter is configured, it
 seeds Claude and prints a notice. Credentials do not prove SDK availability
 or remaining quota; launch still checks the configured adapter. Existing
@@ -75,7 +75,7 @@ The Claude default is shown below. A Codex seed also adds
 ```yaml
 captain:
   adapter: claude
-  model: claude-opus-5
+  model: claude-opus-5-5
   effort: high
   permissions:
     mode: auto # protected auto mode for the Claude Captain
@@ -83,21 +83,21 @@ captain:
 players:
   dev.coder:
     adapter: claude
-    model: claude-opus-5
+    model: claude-opus-5-5
     effort: high
     permissions:
       mode: auto # protected auto mode for the Claude Coder
 
   dev.reviewer:
     adapter: claude
-    model: claude-opus-5
+    model: claude-opus-5-5
     effort: xhigh
     permissions:
       mode: auto # protected auto mode for the Claude Reviewer
 
   dev.analyst:
     adapter: claude
-    model: claude-opus-5
+    model: claude-opus-5-5
     effort: xhigh
     permissions:
       mode: auto # protected auto mode for the Claude Analyst
@@ -156,26 +156,37 @@ roles:
   coder: dev.coder
 ```
 
-Use a block to override only that role invocation's model, effort, or fast
-mode:
+Use a block to override only that role invocation's model, effort, fast mode,
+or subagent model:
 
 ```yaml
 roles:
   coder:
     player: dev.coder
-    model: gpt-5.6-sol
+    model: claude-sonnet-5-5
     effort: false # explicitly reset to this provider's default
     fastMode: false # literal disabled request, not a default sentinel
+  reviewer:
+    player: dev.reviewer
+    subagentModel: claude-sonnet-5-5 # every subagent of this role runs on it
 ```
 
-Omitting any override inherits that player's top-level default. For `model`
-and `effort`, boolean `false` selects the provider default explicitly, so a
-resumed conversation cannot accidentally retain an earlier selection. For
-`fastMode`, `false` is a literal request to disable fast mode; omitting the
-top-level setting selects the provider default. A present fast-mode boolean is
-accepted only for adapters Cligent reports as supporting it. A role binding
-cannot override adapter, instruction, permissions, workspace, or tool posture;
-those define the stable player envelope.
+Omitting any override inherits that player's top-level default. For `model`,
+`effort`, and `subagentModel`, boolean `false` selects the provider default
+explicitly, so a resumed conversation cannot accidentally retain an earlier
+selection. For `fastMode`, `false` is a literal request to disable fast mode;
+omitting the top-level setting selects the provider default. A present
+fast-mode boolean or subagent model is accepted only for adapters Cligent
+reports as supporting it. A role binding cannot override adapter, instruction,
+permissions, workspace, or tool posture; those define the stable player
+envelope, so an overriding model must be one that player's adapter serves.
+
+A subagent model makes every subagent the agent starts run on that model, and
+tells the agent to hand well-defined, fine-grained tasks to its subagents while
+keeping the deep thinking, reasoning, and design work itself, without lowering
+the quality of what it delivers
+([DR-075](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/075-subagent-model-is-tuning.md)).
+Nothing sets one by default.
 
 ## Sharing, isolation, and concurrency
 
@@ -198,8 +209,11 @@ second top-level player and change only its binding:
 players:
   review.coder:
     adapter: codex
-    model: gpt-5.6-sol
+    model: gpt-6-sol
     effort: ultra
+    permissions:
+      mode: auto
+      writablePaths: ['.git'] # lets the Codex Coder commit its review fixes
 
 playbooks:
   review:
@@ -247,7 +261,7 @@ playbook run --with fast-lineup.yaml "/code implement the approved change"
 # fast-lineup.yaml — retune the shared Coder; nothing is written back.
 players:
   dev.coder:
-    model: gpt-5.6-sol
+    model: claude-sonnet-5-5
     effort: medium
     fastMode: false
 ```
@@ -272,9 +286,9 @@ The global file is never modified, and `--with` is not forwarded to
 Overlays apply when creating a fresh session and as current-config input for a
 compatible ordinary reopen. A selected session keeps its stored catalog,
 player roster, role bindings, adapter, instruction, permissions, and working
-directory; only model, effort, and fast mode may change. The next call reapplies
-both complete model and effort selections and the optional effective fast-mode
-boolean. An uncertain retry accepts no tuning overlay and only restores and reports the recorded attempt. Later turns use the current compatible settings.
+directory; only model, effort, fast mode, and subagent model may change. The
+next call reapplies both complete model and effort selections, the optional
+effective fast-mode boolean, and the optional effective subagent model. An uncertain retry accepts no tuning overlay and only restores and reports the recorded attempt. Later turns use the current compatible settings.
 
 ## Session storage
 
@@ -315,8 +329,8 @@ public UUID. Presentation-only fields are inert headlessly.
 An ordinary reopen reads current config and opening overlays, but first
 projects them to the stored playbooks and referenced players. An unrelated new
 entry cannot enter or invalidate the session. Structural drift fails closed;
-compatible model, effort, or fast-mode changes apply on the next provider
-call. Legacy record, shell, runtime-snapshot, and trace schemas are rejected
+compatible model, effort, fast-mode, or subagent-model changes apply on the
+next provider call. Legacy record, shell, runtime-snapshot, and trace schemas are rejected
 rather than having role or player identity guessed.
 
 ## External playbooks
@@ -365,12 +379,12 @@ playbooks:
   code:
     from: '@sublang/playbook/code/registry'
     players:
-      coder: { adapter: claude, model: claude-opus-4-8[1m] }
+      coder: { adapter: claude, model: claude-opus-5-5 }
   review:
     from: '@sublang/playbook/review/registry'
     players:
-      coder: { adapter: claude, model: claude-opus-4-8[1m] }
-      reviewer: { adapter: codex, model: gpt-5.5 }
+      coder: { adapter: claude, model: claude-opus-5-5 }
+      reviewer: { adapter: codex, model: gpt-6-sol }
 ```
 
 Move each provider agent into the flat top-level map, choose stable IDs, and
@@ -378,8 +392,8 @@ bind the local roles explicitly:
 
 ```yaml
 players:
-  dev.coder: { adapter: claude, model: claude-opus-4-8[1m] }
-  dev.reviewer: { adapter: codex, model: gpt-5.5 }
+  dev.coder: { adapter: claude, model: claude-opus-5-5 }
+  dev.reviewer: { adapter: codex, model: gpt-6-sol }
 
 playbooks:
   code:

package/docs/embedding.md

@@ -78,11 +78,11 @@ declare const playerAdapter: {
 const roleBindings = {
   coder: {
     playerId: 'team.coder',
-    promptIdentity: 'claude-opus-4-8[1m]',
+    promptIdentity: 'claude-opus-5-5',
   },
   reviewer: {
     playerId: 'team.reviewer',
-    promptIdentity: 'gpt-5.5',
+    promptIdentity: 'gpt-6-sol',
   },
 } satisfies Readonly<Record<string, PlaybookRoleBinding>>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.0.0",
+  "version": "17.2.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -243,15 +243,15 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.27.0",
+    "@sublang/cligent": "^0.29.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.283",
-    "@openai/codex-sdk": "^0.157.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.284",
+    "@openai/codex-sdk": "^0.159.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -442,7 +442,8 @@ export async function normalizeSelectedLaunchPlanDataOnly(
       if (
         binding.model !== undefined ||
         binding.effort !== undefined ||
-        binding.fastMode !== undefined
+        binding.fastMode !== undefined ||
+        binding.subagentModel !== undefined
       ) {
         let checkId;
         do {
@@ -558,6 +559,7 @@ export async function normalizeSelectedLaunchPlanDataOnly(
                       ? {}
                       : { fastMode: agent.fastMode }
                     : { fastMode: binding.fastMode }),
+                  ...effectiveSubagentModel(binding, agent),
                 },
               ];
             }),
@@ -787,7 +789,8 @@ export async function normalizeLaunchPlan(
       if (
         binding.model !== undefined ||
         binding.effort !== undefined ||
-        binding.fastMode !== undefined
+        binding.fastMode !== undefined ||
+        binding.subagentModel !== undefined
       ) {
         let checkId;
         do {
@@ -999,6 +1002,7 @@ export async function normalizeLaunchPlan(
                 ? {}
                 : { fastMode: agent.fastMode }
               : { fastMode: binding.fastMode }),
+            ...effectiveSubagentModel(binding, agent),
           },
         ];
       }),
@@ -1380,10 +1384,12 @@ function assertLegacyRelocationLocatorsSafe(
 
 // PBCLI-11 / DR-053: the adapters a seeded lineup may take, highest
 // precedence first. A fixed order — not whichever the probe answers
-// first — is what makes one machine seed one file twice.
+// first — is what makes one machine seed one file twice. DR-074: each
+// row names the latest model of its adapter's line; the template names
+// the first row's model, because the default seed is its byte copy.
 const SEED_LINEUP = Object.freeze([
-  Object.freeze({ adapter: "claude", model: "claude-opus-5" }),
-  Object.freeze({ adapter: "codex", model: "gpt-5.6-sol" }),
+  Object.freeze({ adapter: "claude", model: "claude-opus-5-5" }),
+  Object.freeze({ adapter: "codex", model: "gpt-6-sol" }),
 ]);
 
 /**
@@ -1482,7 +1488,7 @@ function migrateUserConfigIfRetired(userConfigPath, onNotice) {
     throw new Error(
       `cannot migrate the retired profiles config at ${userConfigPath}: ` +
         `${errorMessage(error)} — edit it by hand: each agent takes its own ` +
-        "adapter, model, effort, fast mode, and permissions",
+        "adapter, model, effort, fast mode, subagent model, and permissions",
     );
   }
   if (migrated === undefined) return;
@@ -1618,7 +1624,7 @@ function assertNoRetiredProfiles(top, configPath) {
     throw new Error(
       `top-level "profiles" was removed${where}: write each agent's settings ` +
         "inline under captain and each top-level players.<player-id> " +
-        "(adapter, model, effort, fast mode, permissions)",
+        "(adapter, model, effort, fast mode, subagent model, permissions)",
     );
   }
   const legacyPath = findLegacyPlayersPath(top);
@@ -1633,7 +1639,8 @@ function assertNoRetiredProfiles(top, configPath) {
     if (isObject(block) && block.profile !== undefined) {
       throw new Error(
         `${path}.profile was removed${where}: write the agent's settings ` +
-          "inline in that block (adapter, model, effort, fast mode, permissions)",
+          "inline in that block (adapter, model, effort, fast mode, " +
+          "subagent model, permissions)",
       );
     }
   }
@@ -2032,13 +2039,14 @@ function resolveRoleBinding(value, path) {
   }
   const block = requireObject(value, path);
   const unknown = Object.keys(block).filter(
-    (key) => !["player", "model", "effort", "fastMode"].includes(key),
+    (key) =>
+      !["player", "model", "effort", "fastMode", "subagentModel"].includes(key),
   );
   if (unknown.length > 0) {
     throw new Error(`${path} has unknown ${formatKeyList(unknown)}`);
   }
   assertPlayerId(block.player, `${path}.player`);
-  for (const field of ["model", "effort"]) {
+  for (const field of ["model", "effort", "subagentModel"]) {
     if (
       block[field] !== undefined &&
       block[field] !== false &&
@@ -2060,9 +2068,24 @@ function resolveRoleBinding(value, path) {
     ...(block.model === undefined ? {} : { model: block.model }),
     ...(block.effort === undefined ? {} : { effort: block.effort }),
     ...(block.fastMode === undefined ? {} : { fastMode: block.fastMode }),
+    ...(block.subagentModel === undefined
+      ? {}
+      : { subagentModel: block.subagentModel }),
   };
 }
 
+// A binding's subagent model overrides the player's; `false` selects the
+// provider default, which a complete call expresses by omission.
+function effectiveSubagentModel(binding, agent) {
+  if (binding.subagentModel === false) return {};
+  if (binding.subagentModel !== undefined) {
+    return { subagentModel: binding.subagentModel };
+  }
+  return agent.subagentModel === undefined
+    ? {}
+    : { subagentModel: agent.subagentModel };
+}
+
 function applyTuningOverrides(agent, binding) {
   const effective = { ...agent };
   if (binding.model === false) delete effective.model;
@@ -2073,6 +2096,10 @@ function applyTuningOverrides(agent, binding) {
     else effective.effort = binding.effort;
   }
   if (binding.fastMode !== undefined) effective.fastMode = binding.fastMode;
+  if (binding.subagentModel === false) delete effective.subagentModel;
+  else if (binding.subagentModel !== undefined) {
+    effective.subagentModel = binding.subagentModel;
+  }
   return effective;
 }
 
@@ -2087,6 +2114,14 @@ function sessionAgentFromHostAgent(agent, path) {
     ...(agent.fastMode === undefined
       ? {}
       : { fastMode: fastModeSelection(agent.fastMode, `${path}.fastMode`) }),
+    ...(agent.subagentModel === undefined
+      ? {}
+      : {
+          subagentModel: subagentModelSelection(
+            agent.subagentModel,
+            `${path}.subagentModel`,
+          ),
+        }),
     ...(agent.instruction === undefined
       ? {}
       : { instruction: agent.instruction }),
@@ -2112,6 +2147,9 @@ export function projectHostAgent(agent, path = "agent") {
     ...(normalized.fastMode === undefined
       ? {}
       : { fastMode: normalized.fastMode }),
+    ...(normalized.subagentModel === undefined
+      ? {}
+      : { subagentModel: normalized.subagentModel }),
     ...(normalized.instruction === undefined
       ? {}
       : { instruction: normalized.instruction }),
@@ -2128,6 +2166,13 @@ function fastModeSelection(value, path) {
   return value;
 }
 
+function subagentModelSelection(value, path) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${path} must be a nonblank string`);
+  }
+  return value;
+}
+
 function tuningSelection(value, path) {
   if (
     value !== undefined &&

package/reference/sdlc/code.playbook/bin/playbook.js

@@ -966,8 +966,9 @@ function helpText({
     "  - set the top-level captain and each stable players.<id> to an",
     "    adapter shorthand (claude, codex) or an inline agent block",
     "  - bind every playbooks.<id>.roles.<role> explicitly to a player id;",
-    "    a scalar names the id, while { player, model?, effort?, fastMode? }",
-    "    may retune one role; false selects provider-default model/effort,",
+    "    a scalar names the id, while { player, model?, effort?, fastMode?,",
+    "    subagentModel? } may retune one role;",
+    "    false selects provider-default model/effort/subagentModel,",
     "    while fastMode false is a literal disabled request",
     "  - reusing one id deliberately shares that provider conversation;",
     "    distinct ids stay isolated even when their agent blocks are equal",

package/reference/sdlc/code.playbook/bin/run.js

@@ -11,7 +11,10 @@ import { attachSessionHints, validateSessionContext } from "./portable-codec.js"
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { assertFastModeSupported } from "@sublang/cligent";
+import {
+  assertFastModeSupported,
+  assertSubagentModelSupported,
+} from "@sublang/cligent";
 import { createTmuxPlayRuntime } from "@sublang/cligent/tmux-play";
 import {
   assertPlaybookEffectLedger,
@@ -1307,7 +1310,7 @@ export async function validateFrozenExecutionConfig(
     structuralProjection,
     executionProjection,
   );
-  assertFrozenFastModesSupported(config);
+  assertFrozenTuningSupported(config);
   const catalogItems = Object.entries(config.catalog);
 
   // Preserve the complete-catalog preparation transaction: prepare every
@@ -1364,28 +1367,42 @@ export async function validateFrozenExecutionConfig(
   return config;
 }
 
-function assertFrozenFastModesSupported(config) {
-  if (config.captain.fastMode !== undefined) {
-    assertFastModeSupported(
-      config.captain.adapter,
-      "stored Captain fastMode",
-    );
-  }
+// Fast mode and the subagent model are adapter-scoped tuning (DR-075): a
+// frozen record re-validates each present value against its adapter.
+const FROZEN_ADAPTER_SCOPED_TUNING = [
+  ["fastMode", assertFastModeSupported],
+  ["subagentModel", assertSubagentModelSupported],
+];
+
+function assertFrozenTuningSupported(config) {
+  const assertSupported = (record, adapter, path) => {
+    for (const [field, assertFieldSupported] of FROZEN_ADAPTER_SCOPED_TUNING) {
+      if (record[field] !== undefined) {
+        assertFieldSupported(adapter, `${path} ${field}`);
+      }
+    }
+  };
+  assertSupported(config.captain, config.captain.adapter, "stored Captain");
 
   const playerAdapters = new Map();
   for (const player of config.players) {
     playerAdapters.set(player.id, player.adapter);
-    if (player.fastMode !== undefined) {
-      assertFastModeSupported(
-        player.adapter,
-        `stored player ${JSON.stringify(player.id)} fastMode`,
-      );
-    }
+    assertSupported(
+      player,
+      player.adapter,
+      `stored player ${JSON.stringify(player.id)}`,
+    );
   }
 
   for (const [playbookId, item] of Object.entries(config.catalog)) {
     for (const [roleId, binding] of Object.entries(item.roles)) {
-      if (binding.fastMode === undefined) continue;
+      if (
+        FROZEN_ADAPTER_SCOPED_TUNING.every(
+          ([field]) => binding[field] === undefined,
+        )
+      ) {
+        continue;
+      }
       const adapter = playerAdapters.get(binding.playerId);
       if (adapter === undefined) {
         throw new Error(
@@ -1393,10 +1410,11 @@ function assertFrozenFastModesSupported(config) {
             `${JSON.stringify(roleId)} names an unknown player`,
         );
       }
-      assertFastModeSupported(
+      assertSupported(
+        binding,
         adapter,
         `stored playbook ${JSON.stringify(playbookId)} role ` +
-          `${JSON.stringify(roleId)} fastMode`,
+          `${JSON.stringify(roleId)}`,
       );
     }
   }
@@ -1869,7 +1887,7 @@ function runHelpText(userConfigPath) {
     "working directory and reports when it uses the global newest fallback.",
     "An ordinary continued run restores that stored structure and working",
     "directory, then reads current config and overlays for model, effort,",
-    "and fast mode.",
+    "fast mode, and subagent model.",
     "Uncertain retry only restores and reports; later work uses current settings.",
     "",
     "Options:",

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -5402,7 +5402,7 @@ function validateCaptainSessionProjection(
         : ['id', 'adapter', 'model', 'effort'],
       structural
         ? ['instruction', 'permissions']
-        : ['instruction', 'permissions', 'fastMode'],
+        : ['instruction', 'permissions', 'fastMode', 'subagentModel'],
       playerPath,
     );
     assertPlayerId(player.id, `${playerPath}.id`);
@@ -5503,12 +5503,16 @@ function validateCaptainSessionProjection(
         structural
           ? ['playerId']
           : ['playerId', 'model', 'effort'],
-        structural ? [] : ['fastMode'],
+        structural ? [] : ['fastMode', 'subagentModel'],
         bindingPath,
       );
       assertPlayerId(binding.playerId, `${bindingPath}.playerId`);
       if (!structural) {
         validateProjectedFastMode(binding, `${bindingPath}.fastMode`);
+        validateProjectedSubagentModel(
+          binding,
+          `${bindingPath}.subagentModel`,
+        );
         validateTuningSelection(binding.model, `${bindingPath}.model`);
         const player = projection.players.find(
           (candidate) => candidate.id === binding.playerId,
@@ -5556,16 +5560,26 @@ function validateProjectedFastMode(record, path) {
   }
 }
 
+// Like fast mode, absence is the canonical provider default (DR-075).
+function validateProjectedSubagentModel(record, path) {
+  if (Object.hasOwn(record, 'subagentModel')) {
+    requireNonblank(record.subagentModel, path);
+  }
+}
+
 function validateProjectedAgent(value, path, { structural, hasId = false }) {
   const agent = requireRecord(value, path);
-  if (!structural) validateProjectedFastMode(agent, `${path}.fastMode`);
+  if (!structural) {
+    validateProjectedFastMode(agent, `${path}.fastMode`);
+    validateProjectedSubagentModel(agent, `${path}.subagentModel`);
+  }
   if (!hasId) {
     exactOptionalKeys(
       agent,
       structural ? ['adapter'] : ['adapter', 'model', 'effort'],
       structural
         ? ['instruction', 'permissions']
-        : ['instruction', 'permissions', 'fastMode'],
+        : ['instruction', 'permissions', 'fastMode', 'subagentModel'],
       path,
     );
   }

package/reference/sdlc/code.playbook/playbook-captain.d.ts

@@ -10,9 +10,14 @@ interface SessionAgent {
     /** Adapter-scoped fast mode. Absence is the provider default; `false` is a
      * literal request, so this carries no provider-default sentinel. */
     readonly fastMode?: boolean;
+    /** The model every subagent of this agent runs on (DR-075). Absence is the
+     * provider default. */
+    readonly subagentModel?: string;
     readonly instruction?: string;
     readonly permissions?: PermissionPolicy;
 }
+/** Per-call tuning: erased from every structural envelope and snapshot. */
+type TuningKey = 'model' | 'effort' | 'fastMode' | 'subagentModel';
 interface PlayerLedgerEntry {
     readonly adapter: string;
     readonly instruction?: string;
@@ -32,7 +37,7 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
     readonly rootPlaybookId: string;
     readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
 }
-type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, 'model' | 'effort' | 'fastMode'>>;
+type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey>>;
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 export interface ProgressChange {
     snapshot?: PlaybookCaptainShellSnapshot | null;

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -2098,10 +2098,28 @@ function snapshotFastMode(value, path) {
     }
     return value;
 }
+function snapshotSubagentModel(value, path) {
+    if (value !== undefined &&
+        (typeof value !== 'string' || value.trim().length === 0)) {
+        throw new TypeError(`${path} must be a nonblank string`);
+    }
+    return value;
+}
 function snapshotSessionAgent(value, path) {
     const agent = snapshotRecord(value, path);
-    rejectSnapshotKeys(agent, ['adapter', 'model', 'effort', 'fastMode', 'instruction', 'permissions'], path);
-    const fixed = snapshotFixedAgent(Object.fromEntries(Object.entries(agent).filter(([key]) => key !== 'model' && key !== 'effort' && key !== 'fastMode')), path);
+    rejectSnapshotKeys(agent, [
+        'adapter',
+        'model',
+        'effort',
+        'fastMode',
+        'subagentModel',
+        'instruction',
+        'permissions',
+    ], path);
+    const fixed = snapshotFixedAgent(Object.fromEntries(Object.entries(agent).filter(([key]) => key !== 'model' &&
+        key !== 'effort' &&
+        key !== 'fastMode' &&
+        key !== 'subagentModel')), path);
     return {
         adapter: fixed.adapter,
         ...(fixed.instruction === undefined
@@ -2115,6 +2133,11 @@ function snapshotSessionAgent(value, path) {
         ...(agent.fastMode === undefined
             ? {}
             : { fastMode: snapshotFastMode(agent.fastMode, `${path}.fastMode`) }),
+        ...(agent.subagentModel === undefined
+            ? {}
+            : {
+                subagentModel: snapshotSubagentModel(agent.subagentModel, `${path}.subagentModel`),
+            }),
     };
 }
 function fixedAgent(agent) {
@@ -2126,12 +2149,15 @@ function fixedAgent(agent) {
 }
 function callSettings(agent, tuning = agent) {
     // cligent treats supplied call settings as a complete replacement, so an
-    // omitted fastMode here is a request for the provider default, never an
-    // inheritance of whatever the previous call left behind.
+    // omitted fastMode or subagentModel here is a request for the provider
+    // default, never an inheritance of whatever the previous call left behind.
     return {
         model: tuning.model,
         effort: tuning.effort,
         ...(tuning.fastMode === undefined ? {} : { fastMode: tuning.fastMode }),
+        ...(tuning.subagentModel === undefined
+            ? {}
+            : { subagentModel: tuning.subagentModel }),
         ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
         ...(agent.permissions === undefined ? {} : { permissions: agent.permissions }),
     };
@@ -2259,7 +2285,7 @@ async function buildEnablements(options, loadModule, hostCapabilities) {
         for (const role of entry.requiredRoleIds) {
             const path = `captain.options.playbooks.${id}.roles.${role}`;
             const rawBinding = snapshotRecord(roleRecord[role], path);
-            rejectSnapshotKeys(rawBinding, ['playerId', 'model', 'effort', 'fastMode'], path);
+            rejectSnapshotKeys(rawBinding, ['playerId', 'model', 'effort', 'fastMode', 'subagentModel'], path);
             const playerId = snapshotString(rawBinding.playerId, `${path}.playerId`);
             if (!PLAYER_ID_PATTERN.test(playerId) || playerId === INTERNAL_CAPTAIN_ID) {
                 throw new Error(`${path}.playerId is not a canonical player id`);
@@ -2277,6 +2303,11 @@ async function buildEnablements(options, loadModule, hostCapabilities) {
                     : {
                         fastMode: snapshotFastMode(rawBinding.fastMode, `${path}.fastMode`),
                     }),
+                ...(rawBinding.subagentModel === undefined
+                    ? {}
+                    : {
+                        subagentModel: snapshotSubagentModel(rawBinding.subagentModel, `${path}.subagentModel`),
+                    }),
                 agent,
             });
         }

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -69,10 +69,16 @@ interface SessionAgent {
   /** Adapter-scoped fast mode. Absence is the provider default; `false` is a
    * literal request, so this carries no provider-default sentinel. */
   readonly fastMode?: boolean;
+  /** The model every subagent of this agent runs on (DR-075). Absence is the
+   * provider default. */
+  readonly subagentModel?: string;
   readonly instruction?: string;
   readonly permissions?: PermissionPolicy;
 }
 
+/** Per-call tuning: erased from every structural envelope and snapshot. */
+type TuningKey = 'model' | 'effort' | 'fastMode' | 'subagentModel';
+
 interface PlayerLedgerEntry {
   readonly adapter: string;
   readonly instruction?: string;
@@ -107,9 +113,7 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
   readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
 }
 
-type SnapshotAgentEnvelope = DeepReadonly<
-  Omit<SessionAgent, 'model' | 'effort' | 'fastMode'>
->;
+type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey>>;
 
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 
@@ -447,6 +451,7 @@ interface EffectivePlayerBinding {
   readonly model: TuningSelection;
   readonly effort: TuningSelection<Effort>;
   readonly fastMode?: boolean;
+  readonly subagentModel?: string;
   readonly agent: SessionAgent;
 }
 
@@ -3722,6 +3727,19 @@ function snapshotFastMode(
   return value;
 }
 
+function snapshotSubagentModel(
+  value: JsonValue | undefined,
+  path: string,
+): string | undefined {
+  if (
+    value !== undefined &&
+    (typeof value !== 'string' || value.trim().length === 0)
+  ) {
+    throw new TypeError(`${path} must be a nonblank string`);
+  }
+  return value;
+}
+
 function snapshotSessionAgent(
   value: JsonValue | undefined,
   path: string,
@@ -3729,14 +3747,25 @@ function snapshotSessionAgent(
   const agent = snapshotRecord(value, path);
   rejectSnapshotKeys(
     agent,
-    ['adapter', 'model', 'effort', 'fastMode', 'instruction', 'permissions'],
+    [
+      'adapter',
+      'model',
+      'effort',
+      'fastMode',
+      'subagentModel',
+      'instruction',
+      'permissions',
+    ],
     path,
   );
   const fixed = snapshotFixedAgent(
     Object.fromEntries(
       Object.entries(agent).filter(
         ([key]) =>
-          key !== 'model' && key !== 'effort' && key !== 'fastMode',
+          key !== 'model' &&
+          key !== 'effort' &&
+          key !== 'fastMode' &&
+          key !== 'subagentModel',
       ),
     ) as JsonValue,
     path,
@@ -3754,12 +3783,18 @@ function snapshotSessionAgent(
     ...(agent.fastMode === undefined
       ? {}
       : { fastMode: snapshotFastMode(agent.fastMode, `${path}.fastMode`) }),
+    ...(agent.subagentModel === undefined
+      ? {}
+      : {
+          subagentModel: snapshotSubagentModel(
+            agent.subagentModel,
+            `${path}.subagentModel`,
+          ),
+        }),
   };
 }
 
-function fixedAgent(
-  agent: SessionAgent,
-): Omit<SessionAgent, 'model' | 'effort' | 'fastMode'> {
+function fixedAgent(agent: SessionAgent): Omit<SessionAgent, TuningKey> {
   return {
     adapter: agent.adapter,
     ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
@@ -3769,15 +3804,18 @@ function fixedAgent(
 
 function callSettings(
   agent: SessionAgent,
-  tuning: Pick<SessionAgent, 'model' | 'effort' | 'fastMode'> = agent,
+  tuning: Pick<SessionAgent, TuningKey> = agent,
 ): AgentCallSettings {
   // cligent treats supplied call settings as a complete replacement, so an
-  // omitted fastMode here is a request for the provider default, never an
-  // inheritance of whatever the previous call left behind.
+  // omitted fastMode or subagentModel here is a request for the provider
+  // default, never an inheritance of whatever the previous call left behind.
   return {
     model: tuning.model,
     effort: tuning.effort,
     ...(tuning.fastMode === undefined ? {} : { fastMode: tuning.fastMode }),
+    ...(tuning.subagentModel === undefined
+      ? {}
+      : { subagentModel: tuning.subagentModel }),
     ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
     ...(agent.permissions === undefined ? {} : { permissions: agent.permissions }),
   };
@@ -4005,7 +4043,7 @@ async function buildEnablements(
       const rawBinding = snapshotRecord(roleRecord[role], path);
       rejectSnapshotKeys(
         rawBinding,
-        ['playerId', 'model', 'effort', 'fastMode'],
+        ['playerId', 'model', 'effort', 'fastMode', 'subagentModel'],
         path,
       );
       const playerId = snapshotString(rawBinding.playerId, `${path}.playerId`);
@@ -4030,6 +4068,14 @@ async function buildEnablements(
                 `${path}.fastMode`,
               ),
             }),
+        ...(rawBinding.subagentModel === undefined
+          ? {}
+          : {
+              subagentModel: snapshotSubagentModel(
+                rawBinding.subagentModel,
+                `${path}.subagentModel`,
+              ),
+            }),
         agent,
       });
     }

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -8,10 +8,11 @@
 
 # The Captain and each stable session player carries its own defaults inline:
 # an adapter shorthand (claude, codex) or a block with
-# adapter/model/effort/fastMode/permissions. A role may override only model,
-# effort, or fastMode.
-# Omit an override to inherit the player default. For model and effort, false
-# selects the provider default; fastMode false is a literal disabled request.
+# adapter/model/effort/fastMode/subagentModel/permissions. A role may override
+# only model, effort, fastMode, or subagentModel.
+# Omit an override to inherit the player default. For model, effort, and
+# subagentModel, false selects the provider default; fastMode false is a
+# literal disabled request.
 
 # Each adapter needs its vendor SDK installed as its own top-level
 # install root — they are optional peer dependencies, so you pay only
@@ -31,7 +32,7 @@
 # list, so those captains degrade to a prompt-level restriction (DR-013 A1).
 captain:
   adapter: claude
-  model: claude-opus-5
+  model: claude-opus-5-5
   effort: high
   permissions:
     mode: auto
@@ -48,7 +49,7 @@ notifications:
 players:
   dev.coder:
     adapter: claude
-    model: claude-opus-5
+    model: claude-opus-5-5
     effort: high
     # Adapter-scoped fast mode is validated by the installed Cligent contract;
     # omitting it takes the provider default.
@@ -57,7 +58,7 @@ players:
 
   dev.reviewer:
     adapter: claude
-    model: claude-opus-5
+    model: claude-opus-5-5
     effort: xhigh
     permissions:
       mode: auto
@@ -67,7 +68,7 @@ players:
   # conversations (DR-044).
   dev.analyst:
     adapter: claude
-    model: claude-opus-5
+    model: claude-opus-5-5
     effort: xhigh
     permissions:
       mode: auto