@sublang/playbook 17.2.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, fast mode, and
-subagent model 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,9 +280,10 @@ 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` 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
+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

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`, `subagentModel`, `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
@@ -157,7 +157,7 @@ roles:
 ```
 
 Use a block to override only that role invocation's model, effort, fast mode,
-or subagent model:
+subagent model, or subagent effort:
 
 ```yaml
 roles:
@@ -168,25 +168,36 @@ roles:
     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
+    subagentModel: inherit # inherit | <model> | false
+    subagentEffort: medium # <effort> | false
 ```
 
 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,
+`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.
 
-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
+`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)).
-Nothing sets one by default.
+`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
 
@@ -279,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
@@ -286,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, 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.
+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
 
@@ -329,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, fast-mode, or subagent-model 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.2.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.29.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 = [];
@@ -443,7 +446,8 @@ export async function normalizeSelectedLaunchPlanDataOnly(
         binding.model !== undefined ||
         binding.effort !== undefined ||
         binding.fastMode !== undefined ||
-        binding.subagentModel !== undefined
+        binding.subagentModel !== undefined ||
+        binding.subagentEffort !== undefined
       ) {
         let checkId;
         do {
@@ -559,7 +563,8 @@ export async function normalizeSelectedLaunchPlanDataOnly(
                       ? {}
                       : { fastMode: agent.fastMode }
                     : { fastMode: binding.fastMode }),
-                  ...effectiveSubagentModel(binding, agent),
+                  ...effectiveOptionalTuning(binding, agent, "subagentModel"),
+                  ...effectiveOptionalTuning(binding, agent, "subagentEffort"),
                 },
               ];
             }),
@@ -689,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
@@ -710,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
@@ -790,7 +797,8 @@ export async function normalizeLaunchPlan(
         binding.model !== undefined ||
         binding.effort !== undefined ||
         binding.fastMode !== undefined ||
-        binding.subagentModel !== undefined
+        binding.subagentModel !== undefined ||
+        binding.subagentEffort !== undefined
       ) {
         let checkId;
         do {
@@ -1002,7 +1010,8 @@ export async function normalizeLaunchPlan(
                 ? {}
                 : { fastMode: agent.fastMode }
               : { fastMode: binding.fastMode }),
-            ...effectiveSubagentModel(binding, agent),
+            ...effectiveOptionalTuning(binding, agent, "subagentModel"),
+            ...effectiveOptionalTuning(binding, agent, "subagentEffort"),
           },
         ];
       }),
@@ -1488,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, subagent model, and permissions",
+        "adapter, model, effort, fast mode, subagent model, subagent effort, " +
+        "and permissions",
     );
   }
   if (migrated === undefined) return;
@@ -1624,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, subagent model, permissions)",
+        "(adapter, model, effort, fast mode, subagent model, subagent effort, " +
+        "permissions)",
     );
   }
   const legacyPath = findLegacyPlayersPath(top);
@@ -1640,7 +1651,7 @@ function assertNoRetiredProfiles(top, configPath) {
       throw new Error(
         `${path}.profile was removed${where}: write the agent's settings ` +
           "inline in that block (adapter, model, effort, fast mode, " +
-          "subagent model, permissions)",
+          "subagent model, subagent effort, permissions)",
       );
     }
   }
@@ -2040,13 +2051,20 @@ function resolveRoleBinding(value, path) {
   const block = requireObject(value, path);
   const unknown = Object.keys(block).filter(
     (key) =>
-      !["player", "model", "effort", "fastMode", "subagentModel"].includes(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", "subagentModel"]) {
+  for (const field of ["model", "effort", "subagentModel", "subagentEffort"]) {
     if (
       block[field] !== undefined &&
       block[field] !== false &&
@@ -2071,19 +2089,41 @@ function resolveRoleBinding(value, path) {
     ...(block.subagentModel === undefined
       ? {}
       : { subagentModel: block.subagentModel }),
+    ...(block.subagentEffort === undefined
+      ? {}
+      : { subagentEffort: block.subagentEffort }),
   };
 }
 
-// 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 };
+// 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;
   }
-  return agent.subagentModel === undefined
-    ? {}
-    : { subagentModel: agent.subagentModel };
+  if (
+    agent.subagentModel === undefined &&
+    typeof agent.adapter === "string" &&
+    isSubagentModelSupported(agent.adapter)
+  ) {
+    return { ...agent, subagentModel: "inherit" };
+  }
+  return agent;
 }
 
 function applyTuningOverrides(agent, binding) {
@@ -2096,9 +2136,9 @@ 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;
+  for (const field of ["subagentModel", "subagentEffort"]) {
+    if (binding[field] === false) delete effective[field];
+    else if (binding[field] !== undefined) effective[field] = binding[field];
   }
   return effective;
 }
@@ -2117,11 +2157,19 @@ function sessionAgentFromHostAgent(agent, path) {
     ...(agent.subagentModel === undefined
       ? {}
       : {
-          subagentModel: subagentModelSelection(
+          subagentModel: nonblankSelection(
             agent.subagentModel,
             `${path}.subagentModel`,
           ),
         }),
+    ...(agent.subagentEffort === undefined
+      ? {}
+      : {
+          subagentEffort: nonblankSelection(
+            agent.subagentEffort,
+            `${path}.subagentEffort`,
+          ),
+        }),
     ...(agent.instruction === undefined
       ? {}
       : { instruction: agent.instruction }),
@@ -2150,6 +2198,9 @@ export function projectHostAgent(agent, path = "agent") {
     ...(normalized.subagentModel === undefined
       ? {}
       : { subagentModel: normalized.subagentModel }),
+    ...(normalized.subagentEffort === undefined
+      ? {}
+      : { subagentEffort: normalized.subagentEffort }),
     ...(normalized.instruction === undefined
       ? {}
       : { instruction: normalized.instruction }),
@@ -2166,7 +2217,7 @@ function fastModeSelection(value, path) {
   return value;
 }
 
-function subagentModelSelection(value, path) {
+function nonblankSelection(value, path) {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(`${path} must be a nonblank string`);
   }

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

@@ -967,9 +967,11 @@ function helpText({
     "    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?,",
-    "    subagentModel? } may retune one role;",
-    "    false selects provider-default model/effort/subagentModel,",
-    "    while fastMode false is a literal disabled request",
+    "    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

@@ -1367,11 +1367,14 @@ export async function validateFrozenExecutionConfig(
   return config;
 }
 
-// Fast mode and the subagent model are adapter-scoped tuning (DR-075): a
-// frozen record re-validates each present value against its adapter.
+// 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) {
@@ -1887,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,",
-    "fast mode, and subagent model.",
+    "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', 'subagentModel'],
+        : [
+            'instruction',
+            'permissions',
+            'fastMode',
+            'subagentModel',
+            'subagentEffort',
+          ],
       playerPath,
     );
     assertPlayerId(player.id, `${playerPath}.id`);
@@ -5503,16 +5509,13 @@ function validateCaptainSessionProjection(
         structural
           ? ['playerId']
           : ['playerId', 'model', 'effort'],
-        structural ? [] : ['fastMode', 'subagentModel'],
+        structural ? [] : ['fastMode', 'subagentModel', 'subagentEffort'],
         bindingPath,
       );
       assertPlayerId(binding.playerId, `${bindingPath}.playerId`);
       if (!structural) {
         validateProjectedFastMode(binding, `${bindingPath}.fastMode`);
-        validateProjectedSubagentModel(
-          binding,
-          `${bindingPath}.subagentModel`,
-        );
+        validateProjectedSubagentTuning(binding, bindingPath);
         validateTuningSelection(binding.model, `${bindingPath}.model`);
         const player = projection.players.find(
           (candidate) => candidate.id === binding.playerId,
@@ -5560,10 +5563,14 @@ 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);
+// 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}`);
+    }
   }
 }
 
@@ -5571,7 +5578,7 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
   const agent = requireRecord(value, path);
   if (!structural) {
     validateProjectedFastMode(agent, `${path}.fastMode`);
-    validateProjectedSubagentModel(agent, `${path}.subagentModel`);
+    validateProjectedSubagentTuning(agent, path);
   }
   if (!hasId) {
     exactOptionalKeys(
@@ -5579,7 +5586,13 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
       structural ? ['adapter'] : ['adapter', 'model', 'effort'],
       structural
         ? ['instruction', 'permissions']
-        : ['instruction', 'permissions', 'fastMode', 'subagentModel'],
+        : [
+            'instruction',
+            'permissions',
+            'fastMode',
+            'subagentModel',
+            'subagentEffort',
+          ],
       path,
     );
   }

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

@@ -10,14 +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). Absence is the
-     * provider default. */
+    /** 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';
+type TuningKey = 'model' | 'effort' | 'fastMode' | 'subagentModel' | 'subagentEffort';
 interface PlayerLedgerEntry {
     readonly adapter: string;
     readonly instruction?: string;

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

@@ -2098,7 +2098,7 @@ function snapshotFastMode(value, path) {
     }
     return value;
 }
-function snapshotSubagentModel(value, path) {
+function snapshotNonblankTuning(value, path) {
     if (value !== undefined &&
         (typeof value !== 'string' || value.trim().length === 0)) {
         throw new TypeError(`${path} must be a nonblank string`);
@@ -2113,13 +2113,15 @@ function snapshotSessionAgent(value, path) {
         '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')), path);
+        key !== 'subagentModel' &&
+        key !== 'subagentEffort')), path);
     return {
         adapter: fixed.adapter,
         ...(fixed.instruction === undefined
@@ -2136,7 +2138,12 @@ function snapshotSessionAgent(value, path) {
         ...(agent.subagentModel === undefined
             ? {}
             : {
-                subagentModel: snapshotSubagentModel(agent.subagentModel, `${path}.subagentModel`),
+                subagentModel: snapshotNonblankTuning(agent.subagentModel, `${path}.subagentModel`),
+            }),
+        ...(agent.subagentEffort === undefined
+            ? {}
+            : {
+                subagentEffort: snapshotNonblankTuning(agent.subagentEffort, `${path}.subagentEffort`),
             }),
     };
 }
@@ -2150,7 +2157,9 @@ function fixedAgent(agent) {
 function callSettings(agent, tuning = agent) {
     // cligent treats supplied call settings as a complete replacement, so an
     // omitted fastMode or subagentModel here is a request for the provider
-    // default, never an inheritance of whatever the previous call left behind.
+    // 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,
@@ -2158,6 +2167,9 @@ function callSettings(agent, tuning = agent) {
         ...(tuning.subagentModel === undefined
             ? {}
             : { subagentModel: tuning.subagentModel }),
+        ...(tuning.subagentEffort === undefined
+            ? {}
+            : { subagentEffort: tuning.subagentEffort }),
         ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
         ...(agent.permissions === undefined ? {} : { permissions: agent.permissions }),
     };
@@ -2285,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', 'subagentModel'], 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`);
@@ -2306,7 +2325,12 @@ async function buildEnablements(options, loadModule, hostCapabilities) {
                 ...(rawBinding.subagentModel === undefined
                     ? {}
                     : {
-                        subagentModel: snapshotSubagentModel(rawBinding.subagentModel, `${path}.subagentModel`),
+                        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,15 +69,23 @@ 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. */
+  /** 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';
+type TuningKey =
+  | 'model'
+  | 'effort'
+  | 'fastMode'
+  | 'subagentModel'
+  | 'subagentEffort';
 
 interface PlayerLedgerEntry {
   readonly adapter: string;
@@ -452,6 +460,7 @@ interface EffectivePlayerBinding {
   readonly effort: TuningSelection<Effort>;
   readonly fastMode?: boolean;
   readonly subagentModel?: string;
+  readonly subagentEffort?: string;
   readonly agent: SessionAgent;
 }
 
@@ -3727,7 +3736,7 @@ function snapshotFastMode(
   return value;
 }
 
-function snapshotSubagentModel(
+function snapshotNonblankTuning(
   value: JsonValue | undefined,
   path: string,
 ): string | undefined {
@@ -3753,6 +3762,7 @@ function snapshotSessionAgent(
       'effort',
       'fastMode',
       'subagentModel',
+      'subagentEffort',
       'instruction',
       'permissions',
     ],
@@ -3765,7 +3775,8 @@ function snapshotSessionAgent(
           key !== 'model' &&
           key !== 'effort' &&
           key !== 'fastMode' &&
-          key !== 'subagentModel',
+          key !== 'subagentModel' &&
+          key !== 'subagentEffort',
       ),
     ) as JsonValue,
     path,
@@ -3786,11 +3797,19 @@ function snapshotSessionAgent(
     ...(agent.subagentModel === undefined
       ? {}
       : {
-          subagentModel: snapshotSubagentModel(
+          subagentModel: snapshotNonblankTuning(
             agent.subagentModel,
             `${path}.subagentModel`,
           ),
         }),
+    ...(agent.subagentEffort === undefined
+      ? {}
+      : {
+          subagentEffort: snapshotNonblankTuning(
+            agent.subagentEffort,
+            `${path}.subagentEffort`,
+          ),
+        }),
   };
 }
 
@@ -3808,7 +3827,9 @@ function callSettings(
 ): AgentCallSettings {
   // cligent treats supplied call settings as a complete replacement, so an
   // omitted fastMode or subagentModel here is a request for the provider
-  // default, never an inheritance of whatever the previous call left behind.
+  // 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,
@@ -3816,6 +3837,9 @@ function callSettings(
     ...(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 }),
   };
@@ -4043,7 +4067,14 @@ async function buildEnablements(
       const rawBinding = snapshotRecord(roleRecord[role], path);
       rejectSnapshotKeys(
         rawBinding,
-        ['playerId', 'model', 'effort', 'fastMode', 'subagentModel'],
+        [
+          'playerId',
+          'model',
+          'effort',
+          'fastMode',
+          'subagentModel',
+          'subagentEffort',
+        ],
         path,
       );
       const playerId = snapshotString(rawBinding.playerId, `${path}.playerId`);
@@ -4071,11 +4102,19 @@ async function buildEnablements(
         ...(rawBinding.subagentModel === undefined
           ? {}
           : {
-              subagentModel: snapshotSubagentModel(
+              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,11 +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/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.
+# 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