@sublang/playbook 17.1.0 → 17.3.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,
+subagent model, and subagent effort 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,12 @@ 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`, `subagentModel`, and
+`subagentEffort` settings apply to the next call. Boolean `false` explicitly
+resets model, effort, subagent model, or subagent effort 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`, `subagentEffort`, `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
@@ -156,8 +156,8 @@ 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,
+subagent model, or subagent effort:
 
 ```yaml
 roles:
@@ -166,17 +166,38 @@ roles:
     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: inherit # inherit | <model> | false
+    subagentEffort: medium # <effort> | false
 ```
 
-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, so an overriding model must be one
-that player's adapter serves.
+Omitting any override inherits that player's top-level default. For `model`,
+`effort`, `subagentModel`, and `subagentEffort`, 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, subagent model, or subagent effort 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.
+
+`subagentModel` makes every subagent the agent starts run on one model —
+`inherit` names the agent's own, a model name pins another, and `false` on a
+`captain` or `players.<player-id>` block switches delegation off — 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)).
+`subagentEffort` pins the effort every subagent runs at, any effort the
+adapter accepts other than `ultracode`; left unset, the agent chooses an effort
+per task, so its own effort never silently governs its subagents.
+An agent whose adapter serves a subagent model (Claude today) and whose block
+leaves `subagentModel` unset resolves to `inherit`: it delegates by default.
+The launcher resolves this on its own copy and never rewrites your config, and
+the starter config names neither field
+([DR-076](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/076-subagents-delegate-by-default.md)).
+
 
 ## Sharing, isolation, and concurrency
 
@@ -269,6 +290,7 @@ playbooks:
       coder:
         player: dev.coder
         effort: low
+        subagentEffort: high # its subagents still run at high effort
 ```
 
 The global file is never modified, and `--with` is not forwarded to
@@ -276,9 +298,10 @@ 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, subagent model, and subagent effort
+may change. The next call reapplies both complete model and effort selections,
+the optional effective fast-mode boolean, and the optional effective subagent
+model and subagent effort. An uncertain retry accepts no tuning overlay and only restores and reports the recorded attempt. Later turns use the current compatible settings.
 
 ## Session storage
 
@@ -319,8 +342,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, subagent-model, or subagent-effort
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.1.0",
+  "version": "17.3.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,7 +243,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.28.0",
+    "@sublang/cligent": "^0.30.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

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

@@ -28,6 +28,7 @@ import {
   parseDocument as parseYamlDocument,
   stringify as stringifyYaml,
 } from "yaml";
+import { isSubagentModelSupported } from "@sublang/cligent";
 import { loadTmuxPlayConfig } from "@sublang/cligent/tmux-play";
 import {
   defaultCaptainSessionsDir,
@@ -379,12 +380,14 @@ export async function normalizeSelectedLaunchPlanDataOnly(
   const configuredAgents = new Map();
   for (const playerId of expectedMembers.playerIds) {
     assertPlayerId(playerId, `players.${playerId}`);
-    const agent = resolveAgent(playersCfg[playerId], `players.${playerId}`, [
-      "id",
-    ]);
+    const agent = resolveDelegationDefault(
+      resolveAgent(playersCfg[playerId], `players.${playerId}`, ["id"]),
+    );
     configuredAgents.set(playerId, agent);
   }
-  let captain = resolveAgent(top.captain, "captain", ["from", "options"]);
+  let captain = resolveDelegationDefault(
+    resolveAgent(top.captain, "captain", ["from", "options"]),
+  );
 
   const playbooksCfg = requireObject(top.playbooks, "playbooks");
   const tuningChecks = [];
@@ -442,7 +445,9 @@ export async function normalizeSelectedLaunchPlanDataOnly(
       if (
         binding.model !== undefined ||
         binding.effort !== undefined ||
-        binding.fastMode !== undefined
+        binding.fastMode !== undefined ||
+        binding.subagentModel !== undefined ||
+        binding.subagentEffort !== undefined
       ) {
         let checkId;
         do {
@@ -558,6 +563,8 @@ export async function normalizeSelectedLaunchPlanDataOnly(
                       ? {}
                       : { fastMode: agent.fastMode }
                     : { fastMode: binding.fastMode }),
+                  ...effectiveOptionalTuning(binding, agent, "subagentModel"),
+                  ...effectiveOptionalTuning(binding, agent, "subagentEffort"),
                 },
               ];
             }),
@@ -687,9 +694,9 @@ export async function normalizeLaunchPlan(
   const configuredAgents = new Map();
   for (const playerId of allPlayerIds) {
     assertPlayerId(playerId, `players.${playerId}`);
-    const agent = resolveAgent(playersCfg[playerId], `players.${playerId}`, [
-      "id",
-    ]);
+    const agent = resolveDelegationDefault(
+      resolveAgent(playersCfg[playerId], `players.${playerId}`, ["id"]),
+    );
     if (
       typeof agent.adapter !== "string" ||
       agent.adapter.trim().length === 0
@@ -708,7 +715,9 @@ export async function normalizeLaunchPlan(
     throw new Error("playbooks keys must be canonical trimmed nonblank ids");
   }
 
-  let captain = resolveAgent(top.captain, "captain", ["from", "options"]);
+  let captain = resolveDelegationDefault(
+    resolveAgent(top.captain, "captain", ["from", "options"]),
+  );
   if (
     typeof captain.adapter !== "string" ||
     captain.adapter.trim().length === 0
@@ -787,7 +796,9 @@ export async function normalizeLaunchPlan(
       if (
         binding.model !== undefined ||
         binding.effort !== undefined ||
-        binding.fastMode !== undefined
+        binding.fastMode !== undefined ||
+        binding.subagentModel !== undefined ||
+        binding.subagentEffort !== undefined
       ) {
         let checkId;
         do {
@@ -999,6 +1010,8 @@ export async function normalizeLaunchPlan(
                 ? {}
                 : { fastMode: agent.fastMode }
               : { fastMode: binding.fastMode }),
+            ...effectiveOptionalTuning(binding, agent, "subagentModel"),
+            ...effectiveOptionalTuning(binding, agent, "subagentEffort"),
           },
         ];
       }),
@@ -1484,7 +1497,8 @@ 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, subagent effort, " +
+        "and permissions",
     );
   }
   if (migrated === undefined) return;
@@ -1620,7 +1634,8 @@ 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, subagent effort, " +
+        "permissions)",
     );
   }
   const legacyPath = findLegacyPlayersPath(top);
@@ -1635,7 +1650,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, subagent effort, permissions)",
       );
     }
   }
@@ -2034,13 +2050,21 @@ 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",
+        "subagentEffort",
+      ].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", "subagentEffort"]) {
     if (
       block[field] !== undefined &&
       block[field] !== false &&
@@ -2062,9 +2086,46 @@ 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 }),
+    ...(block.subagentEffort === undefined
+      ? {}
+      : { subagentEffort: block.subagentEffort }),
   };
 }
 
+// A binding's subagent model or subagent effort overrides the player's;
+// `false` selects the provider default, which a complete call expresses by
+// omission (for the effort: the agent chooses per task).
+function effectiveOptionalTuning(binding, agent, field) {
+  if (binding[field] === false) return {};
+  if (binding[field] !== undefined) return { [field]: binding[field] };
+  return agent[field] === undefined ? {} : { [field]: agent[field] };
+}
+
+// DR-076: an agent whose adapter serves a subagent model delegates by
+// default. Resolved on the launcher's detached copy of a Captain or player
+// block — never the user's file — before cligent normalization, so cligent
+// validates a subagent effort against the resolved model, and both front
+// ends and the headless run share the result. A block's `false` opts out:
+// nothing is sent and no delegation directive is composed.
+function resolveDelegationDefault(agent) {
+  if (!isObject(agent)) return agent;
+  if (agent.subagentModel === false) {
+    const { subagentModel: _off, ...rest } = agent;
+    return rest;
+  }
+  if (
+    agent.subagentModel === undefined &&
+    typeof agent.adapter === "string" &&
+    isSubagentModelSupported(agent.adapter)
+  ) {
+    return { ...agent, subagentModel: "inherit" };
+  }
+  return agent;
+}
+
 function applyTuningOverrides(agent, binding) {
   const effective = { ...agent };
   if (binding.model === false) delete effective.model;
@@ -2075,6 +2136,10 @@ function applyTuningOverrides(agent, binding) {
     else effective.effort = binding.effort;
   }
   if (binding.fastMode !== undefined) effective.fastMode = binding.fastMode;
+  for (const field of ["subagentModel", "subagentEffort"]) {
+    if (binding[field] === false) delete effective[field];
+    else if (binding[field] !== undefined) effective[field] = binding[field];
+  }
   return effective;
 }
 
@@ -2089,6 +2154,22 @@ function sessionAgentFromHostAgent(agent, path) {
     ...(agent.fastMode === undefined
       ? {}
       : { fastMode: fastModeSelection(agent.fastMode, `${path}.fastMode`) }),
+    ...(agent.subagentModel === undefined
+      ? {}
+      : {
+          subagentModel: nonblankSelection(
+            agent.subagentModel,
+            `${path}.subagentModel`,
+          ),
+        }),
+    ...(agent.subagentEffort === undefined
+      ? {}
+      : {
+          subagentEffort: nonblankSelection(
+            agent.subagentEffort,
+            `${path}.subagentEffort`,
+          ),
+        }),
     ...(agent.instruction === undefined
       ? {}
       : { instruction: agent.instruction }),
@@ -2114,6 +2195,12 @@ export function projectHostAgent(agent, path = "agent") {
     ...(normalized.fastMode === undefined
       ? {}
       : { fastMode: normalized.fastMode }),
+    ...(normalized.subagentModel === undefined
+      ? {}
+      : { subagentModel: normalized.subagentModel }),
+    ...(normalized.subagentEffort === undefined
+      ? {}
+      : { subagentEffort: normalized.subagentEffort }),
     ...(normalized.instruction === undefined
       ? {}
       : { instruction: normalized.instruction }),
@@ -2130,6 +2217,13 @@ function fastModeSelection(value, path) {
   return value;
 }
 
+function nonblankSelection(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,9 +966,12 @@ 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,",
-    "    while fastMode false is a literal disabled request",
+    "    a scalar names the id, while { player, model?, effort?, fastMode?,",
+    "    subagentModel?, subagentEffort? } may retune one role;",
+    "    false selects provider-default model/effort/subagentModel/",
+    "    subagentEffort, while fastMode false is a literal disabled request",
+    "  - a Claude agent delegates by default: subagentModel resolves to",
+    "    inherit (its own model) unless the block sets false",
     "  - reusing one id deliberately shares that provider conversation;",
     "    distinct ids stay isolated even when their agent blocks are equal",
     "  - the launcher injects captain.from and retains referenced player ids",

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,45 @@ export async function validateFrozenExecutionConfig(
   return config;
 }
 
-function assertFrozenFastModesSupported(config) {
-  if (config.captain.fastMode !== undefined) {
-    assertFastModeSupported(
-      config.captain.adapter,
-      "stored Captain fastMode",
-    );
-  }
+// Fast mode, the subagent model and the subagent effort are adapter-scoped
+// tuning (DR-075, DR-076): a frozen record re-validates each present value
+// against its adapter. Cligent serves the subagent effort exactly where it
+// serves a subagent model, so one capability assertion covers both.
+const FROZEN_ADAPTER_SCOPED_TUNING = [
+  ["fastMode", assertFastModeSupported],
+  ["subagentModel", assertSubagentModelSupported],
+  ["subagentEffort", 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 +1413,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 +1890,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, subagent model, and subagent effort.",
     "Uncertain retry only restores and reports; later work uses current settings.",
     "",
     "Options:",

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

@@ -5402,7 +5402,13 @@ function validateCaptainSessionProjection(
         : ['id', 'adapter', 'model', 'effort'],
       structural
         ? ['instruction', 'permissions']
-        : ['instruction', 'permissions', 'fastMode'],
+        : [
+            'instruction',
+            'permissions',
+            'fastMode',
+            'subagentModel',
+            'subagentEffort',
+          ],
       playerPath,
     );
     assertPlayerId(player.id, `${playerPath}.id`);
@@ -5503,12 +5509,13 @@ function validateCaptainSessionProjection(
         structural
           ? ['playerId']
           : ['playerId', 'model', 'effort'],
-        structural ? [] : ['fastMode'],
+        structural ? [] : ['fastMode', 'subagentModel', 'subagentEffort'],
         bindingPath,
       );
       assertPlayerId(binding.playerId, `${bindingPath}.playerId`);
       if (!structural) {
         validateProjectedFastMode(binding, `${bindingPath}.fastMode`);
+        validateProjectedSubagentTuning(binding, bindingPath);
         validateTuningSelection(binding.model, `${bindingPath}.model`);
         const player = projection.players.find(
           (candidate) => candidate.id === binding.playerId,
@@ -5556,16 +5563,36 @@ function validateProjectedFastMode(record, path) {
   }
 }
 
+// Like fast mode, absence is the canonical provider default (DR-075); the
+// subagent model may be the literal `inherit`, and an absent subagent effort
+// leaves each subagent's effort to the agent (DR-076).
+function validateProjectedSubagentTuning(record, path) {
+  for (const field of ['subagentModel', 'subagentEffort']) {
+    if (Object.hasOwn(record, field)) {
+      requireNonblank(record[field], `${path}.${field}`);
+    }
+  }
+}
+
 function validateProjectedAgent(value, path, { structural, hasId = false }) {
   const agent = requireRecord(value, path);
-  if (!structural) validateProjectedFastMode(agent, `${path}.fastMode`);
+  if (!structural) {
+    validateProjectedFastMode(agent, `${path}.fastMode`);
+    validateProjectedSubagentTuning(agent, path);
+  }
   if (!hasId) {
     exactOptionalKeys(
       agent,
       structural ? ['adapter'] : ['adapter', 'model', 'effort'],
       structural
         ? ['instruction', 'permissions']
-        : ['instruction', 'permissions', 'fastMode'],
+        : [
+            'instruction',
+            'permissions',
+            'fastMode',
+            'subagentModel',
+            'subagentEffort',
+          ],
       path,
     );
   }

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

@@ -10,9 +10,17 @@ 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), or `inherit`
+     * for the agent's own model (DR-076). Absence is the provider default. */
+    readonly subagentModel?: string;
+    /** The effort every subagent of this agent runs at (DR-076). Absence leaves
+     * each subagent's effort to the agent. */
+    readonly subagentEffort?: string;
     readonly instruction?: string;
     readonly permissions?: PermissionPolicy;
 }
+/** Per-call tuning: erased from every structural envelope and snapshot. */
+type TuningKey = 'model' | 'effort' | 'fastMode' | 'subagentModel' | 'subagentEffort';
 interface PlayerLedgerEntry {
     readonly adapter: string;
     readonly instruction?: string;
@@ -32,7 +40,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,30 @@ function snapshotFastMode(value, path) {
     }
     return value;
 }
+function snapshotNonblankTuning(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',
+        'subagentEffort',
+        'instruction',
+        'permissions',
+    ], path);
+    const fixed = snapshotFixedAgent(Object.fromEntries(Object.entries(agent).filter(([key]) => key !== 'model' &&
+        key !== 'effort' &&
+        key !== 'fastMode' &&
+        key !== 'subagentModel' &&
+        key !== 'subagentEffort')), path);
     return {
         adapter: fixed.adapter,
         ...(fixed.instruction === undefined
@@ -2115,6 +2135,16 @@ function snapshotSessionAgent(value, path) {
         ...(agent.fastMode === undefined
             ? {}
             : { fastMode: snapshotFastMode(agent.fastMode, `${path}.fastMode`) }),
+        ...(agent.subagentModel === undefined
+            ? {}
+            : {
+                subagentModel: snapshotNonblankTuning(agent.subagentModel, `${path}.subagentModel`),
+            }),
+        ...(agent.subagentEffort === undefined
+            ? {}
+            : {
+                subagentEffort: snapshotNonblankTuning(agent.subagentEffort, `${path}.subagentEffort`),
+            }),
     };
 }
 function fixedAgent(agent) {
@@ -2126,12 +2156,20 @@ 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, and an omitted subagentEffort leaves each subagent's effort to
+    // the agent — 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 }),
+        ...(tuning.subagentEffort === undefined
+            ? {}
+            : { subagentEffort: tuning.subagentEffort }),
         ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
         ...(agent.permissions === undefined ? {} : { permissions: agent.permissions }),
     };
@@ -2259,7 +2297,14 @@ 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',
+                'subagentEffort',
+            ], 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 +2322,16 @@ async function buildEnablements(options, loadModule, hostCapabilities) {
                     : {
                         fastMode: snapshotFastMode(rawBinding.fastMode, `${path}.fastMode`),
                     }),
+                ...(rawBinding.subagentModel === undefined
+                    ? {}
+                    : {
+                        subagentModel: snapshotNonblankTuning(rawBinding.subagentModel, `${path}.subagentModel`),
+                    }),
+                ...(rawBinding.subagentEffort === undefined
+                    ? {}
+                    : {
+                        subagentEffort: snapshotNonblankTuning(rawBinding.subagentEffort, `${path}.subagentEffort`),
+                    }),
                 agent,
             });
         }

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

@@ -69,10 +69,24 @@ 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), or `inherit`
+   * for the agent's own model (DR-076). Absence is the provider default. */
+  readonly subagentModel?: string;
+  /** The effort every subagent of this agent runs at (DR-076). Absence leaves
+   * each subagent's effort to the agent. */
+  readonly subagentEffort?: string;
   readonly instruction?: string;
   readonly permissions?: PermissionPolicy;
 }
 
+/** Per-call tuning: erased from every structural envelope and snapshot. */
+type TuningKey =
+  | 'model'
+  | 'effort'
+  | 'fastMode'
+  | 'subagentModel'
+  | 'subagentEffort';
+
 interface PlayerLedgerEntry {
   readonly adapter: string;
   readonly instruction?: string;
@@ -107,9 +121,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 +459,8 @@ interface EffectivePlayerBinding {
   readonly model: TuningSelection;
   readonly effort: TuningSelection<Effort>;
   readonly fastMode?: boolean;
+  readonly subagentModel?: string;
+  readonly subagentEffort?: string;
   readonly agent: SessionAgent;
 }
 
@@ -3722,6 +3736,19 @@ function snapshotFastMode(
   return value;
 }
 
+function snapshotNonblankTuning(
+  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 +3756,27 @@ function snapshotSessionAgent(
   const agent = snapshotRecord(value, path);
   rejectSnapshotKeys(
     agent,
-    ['adapter', 'model', 'effort', 'fastMode', 'instruction', 'permissions'],
+    [
+      'adapter',
+      'model',
+      'effort',
+      'fastMode',
+      'subagentModel',
+      'subagentEffort',
+      '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' &&
+          key !== 'subagentEffort',
       ),
     ) as JsonValue,
     path,
@@ -3754,12 +3794,26 @@ function snapshotSessionAgent(
     ...(agent.fastMode === undefined
       ? {}
       : { fastMode: snapshotFastMode(agent.fastMode, `${path}.fastMode`) }),
+    ...(agent.subagentModel === undefined
+      ? {}
+      : {
+          subagentModel: snapshotNonblankTuning(
+            agent.subagentModel,
+            `${path}.subagentModel`,
+          ),
+        }),
+    ...(agent.subagentEffort === undefined
+      ? {}
+      : {
+          subagentEffort: snapshotNonblankTuning(
+            agent.subagentEffort,
+            `${path}.subagentEffort`,
+          ),
+        }),
   };
 }
 
-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 +3823,23 @@ 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, and an omitted subagentEffort leaves each subagent's effort to
+  // the agent — 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 }),
+    ...(tuning.subagentEffort === undefined
+      ? {}
+      : { subagentEffort: tuning.subagentEffort as Effort }),
     ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
     ...(agent.permissions === undefined ? {} : { permissions: agent.permissions }),
   };
@@ -4005,7 +4067,14 @@ async function buildEnablements(
       const rawBinding = snapshotRecord(roleRecord[role], path);
       rejectSnapshotKeys(
         rawBinding,
-        ['playerId', 'model', 'effort', 'fastMode'],
+        [
+          'playerId',
+          'model',
+          'effort',
+          'fastMode',
+          'subagentModel',
+          'subagentEffort',
+        ],
         path,
       );
       const playerId = snapshotString(rawBinding.playerId, `${path}.playerId`);
@@ -4030,6 +4099,22 @@ async function buildEnablements(
                 `${path}.fastMode`,
               ),
             }),
+        ...(rawBinding.subagentModel === undefined
+          ? {}
+          : {
+              subagentModel: snapshotNonblankTuning(
+                rawBinding.subagentModel,
+                `${path}.subagentModel`,
+              ),
+            }),
+        ...(rawBinding.subagentEffort === undefined
+          ? {}
+          : {
+              subagentEffort: snapshotNonblankTuning(
+                rawBinding.subagentEffort,
+                `${path}.subagentEffort`,
+              ),
+            }),
         agent,
       });
     }

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

@@ -8,10 +8,15 @@
 
 # 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/subagentEffort/permissions. A
+# role may override only model, effort, fastMode, subagentModel, or
+# subagentEffort.
+# Omit an override to inherit the player default. For model, effort,
+# subagentModel, and subagentEffort, false selects the provider default;
+# fastMode false is a literal disabled request.
+# A Claude agent delegates by default: its subagents run on its own model
+# (subagentModel: inherit) at efforts it chooses per task; subagentModel: false
+# on its block switches delegation off.
 
 # Each adapter needs its vendor SDK installed as its own top-level
 # install root — they are optional peer dependencies, so you pay only