feat(subagent): thread explicit parent effort to workers

Author: TheGreatAxios

src/exec/runner.ts

@@ -714,7 +714,12 @@ export async function runExec(config: Config): Promise<ExecResult> {
     });
 
     const liveSubAgentProvider: { current: SubAgentProvider } = {
-      current: buildSubAgentProvider(config),
+      current: buildSubAgentProvider({
+        ...config,
+        ...(config.reasoningEffort !== undefined
+          ? { explicitReasoningEffort: true }
+          : {}),
+      }),
     };
     const fleetSessions = createSubAgentSessionStore({
       admission: getProcessAdmissionQueue(),

src/provider/reasoning-effort.test.ts

@@ -379,6 +379,62 @@ describe("pickEffortFromCascade (precedence table)", () => {
       }),
     ).toBeUndefined();
   });
+
+  test("6. explicit parent outranks role default (CL-10227)", () => {
+    expect(
+      pickEffortFromCascade({
+        roleDefault: "medium",
+        parentEffort: "none",
+        parentExplicit: true,
+        supported: ["none", "low", "medium", "high"],
+      }),
+    ).toBe("none");
+  });
+
+  test("6b. explicit parent wins even when role default is supported", () => {
+    expect(
+      pickEffortFromCascade({
+        roleDefault: "medium",
+        parentEffort: "high",
+        parentExplicit: true,
+        supported: ["low", "medium", "high"],
+      }),
+    ).toBe("high");
+  });
+
+  test("6c. unsupported explicit parent is clamped onto supported", () => {
+    expect(
+      pickEffortFromCascade({
+        roleDefault: "medium",
+        parentEffort: "xhigh",
+        parentExplicit: true,
+        supported: ["low", "medium", "high"],
+      }),
+    ).toBe("high");
+  });
+
+  test("7. explicit pin still wins over explicit parent", () => {
+    expect(
+      pickEffortFromCascade({
+        pin: "low",
+        roleDefault: "medium",
+        parentEffort: "xhigh",
+        parentExplicit: true,
+        supported: ["low", "medium", "high"],
+      }),
+    ).toBe("low");
+  });
+
+  test("8. falsy parentExplicit keeps role default above parent (CL-5162)", () => {
+    expect(
+      pickEffortFromCascade({
+        roleDefault: "medium",
+        parentEffort: "high",
+        parentExplicit: false,
+        supported: ["low", "medium", "high"],
+      }),
+    ).toBe("medium");
+  });
 });
 
 describe("resolveEffortForRole", () => {
@@ -455,6 +511,51 @@ describe("resolveEffortForRole", () => {
       }),
     ).toBe("high");
   });
+
+  test("explicit parent none wins over leaf role default (CL-10227)", () => {
+    expect(
+      resolveEffortForRole({
+        orchestrator: false,
+        parentEffort: "none",
+        parentExplicit: true,
+        model: "gpt-5.1",
+      }),
+    ).toBe("none");
+  });
+
+  test("explicit parent overrides orchestrator high default", () => {
+    expect(
+      resolveEffortForRole({
+        orchestrator: true,
+        parentEffort: "low",
+        parentExplicit: true,
+        model: "gpt-5",
+      }),
+    ).toBe("low");
+  });
+
+  test("unset parent keeps leaf role default (CL-5162)", () => {
+    expect(
+      resolveEffortForRole({
+        orchestrator: false,
+        parentEffort: "high",
+        parentExplicit: false,
+        model: "gpt-5",
+      }),
+    ).toBe("medium");
+  });
+
+  test("explicit pin wins over explicit parent", () => {
+    expect(
+      resolveEffortForRole({
+        orchestrator: false,
+        pin: "low",
+        parentEffort: "high",
+        parentExplicit: true,
+        model: "gpt-5",
+      }),
+    ).toBe("low");
+  });
 });
 
 describe("defaultEffortForModel", () => {

src/provider/reasoning-effort.ts

@@ -382,6 +382,14 @@ export interface ResolveEffortForRoleOpts {
   roleDefault?: ReasoningEffort;
   /** Parent session effort — used only when the role default is not supported. */
   parentEffort?: ReasoningEffort;
+  /**
+   * True when the parent effort was operator-chosen (explicit) rather than a
+   * resolved/derived value. An explicit parent effort is a fleet-wide pin that
+   * outranks the role default; the unset case keeps CL-5162 (leaf medium /
+   * orchestrator high). Kept as a real separate marker — do NOT infer this from
+   * `parentEffort` truthiness.
+   */
+  parentExplicit?: boolean;
   model: string;
   isCodex?: boolean;
   providerEfforts?: readonly ReasoningEffort[];
@@ -393,10 +401,12 @@ export interface ResolveEffortForRoleOpts {
  *
  * Precedence (first match wins):
  * 1. Explicit pin (clamped onto supported when the pin is not in the set)
- * 2. Role default when present in `supported`
- * 3. Parent effort when present in `supported`
- * 4. Clamp of role default onto `supported`
- * 5. undefined when `supported` is empty
+ * 2. Explicit parent effort (operator-chosen fleet pin) when present in
+ *    `supported` — clamped onto the set when not (CL-10227)
+ * 3. Role default when present in `supported`
+ * 4. Parent effort when present in `supported`
+ * 5. Clamp of role default onto `supported`
+ * 6. undefined when `supported` is empty
  *
  * Pins are still highest precedence, but an unsupported pin is clamped so the
  * pure API owns the "never emit an unsupported effort" invariant (callers that
@@ -406,6 +416,7 @@ export function pickEffortFromCascade(opts: {
   pin?: ReasoningEffort;
   roleDefault: ReasoningEffort;
   parentEffort?: ReasoningEffort;
+  parentExplicit?: boolean;
   supported: readonly ReasoningEffort[];
 }): ReasoningEffort | undefined {
   if (opts.supported.length === 0) return undefined;
@@ -414,6 +425,13 @@ export function pickEffortFromCascade(opts: {
       ? opts.pin
       : clampEffort(opts.pin, opts.supported);
   }
+  // An explicit (operator-chosen) parent effort is a fleet-wide pin: it beats
+  // the role default so a primary cycled to none really gives none workers.
+  if (opts.parentExplicit === true && opts.parentEffort !== undefined) {
+    return opts.supported.includes(opts.parentEffort)
+      ? opts.parentEffort
+      : clampEffort(opts.parentEffort, opts.supported);
+  }
   if (opts.supported.includes(opts.roleDefault)) return opts.roleDefault;
   if (
     opts.parentEffort !== undefined &&
@@ -427,10 +445,13 @@ export function pickEffortFromCascade(opts: {
 /**
  * Resolve reasoning effort for a sub-agent spawn.
  *
- * Why parent is below role default: a /agent high selection on the primary must
- * not force every leaf onto high — that multiplies the sol+high latency cliff
- * across the fleet. Parent still fills gaps when the role default is not in the
- * model's supported set but the parent effort is.
+ * Precedence: explicit pin > explicit parent (operator-chosen fleet pin) > role
+ * default > derived parent > clamp. An explicit primary effort — including
+ * `none`/off — is fleet-wide, so it beats both the leaf (medium) and the
+ * orchestrator (high) role default. The unset parent case keeps CL-5162: the
+ * role default outranks a derived parent so a /agent high selection on the
+ * primary does not force every leaf onto high (which would multiply the
+ * sol+high latency cliff across the fleet).
  */
 export function resolveEffortForRole(
   opts: ResolveEffortForRoleOpts,
@@ -452,6 +473,7 @@ export function resolveEffortForRole(
     ...(opts.parentEffort !== undefined
       ? { parentEffort: opts.parentEffort }
       : {}),
+    ...(opts.parentExplicit === true ? { parentExplicit: true } : {}),
     supported,
   });
 }

src/session/runtime-assembly.test.ts

@@ -79,6 +79,42 @@ describe("buildSubAgentProvider", () => {
       bifrostVirtualKey: true,
     });
   });
+
+  test("omits explicitReasoningEffort when not operator-chosen", () => {
+    expect(
+      buildSubAgentProvider({
+        providerName: "openai",
+        baseURL: "https://api.openai.com/v1",
+        model: "gpt-5",
+        reasoningEffort: "medium",
+        providers: [{ name: "openai" }],
+      }),
+    ).toEqual({
+      providerName: "openai",
+      baseURL: "https://api.openai.com/v1",
+      model: "gpt-5",
+      reasoningEffort: "medium",
+    });
+  });
+
+  test("threads explicitReasoningEffort when operator-chosen", () => {
+    expect(
+      buildSubAgentProvider({
+        providerName: "openai",
+        baseURL: "https://api.openai.com/v1",
+        model: "gpt-5",
+        reasoningEffort: "none",
+        explicitReasoningEffort: true,
+        providers: [{ name: "openai" }],
+      }),
+    ).toEqual({
+      providerName: "openai",
+      baseURL: "https://api.openai.com/v1",
+      model: "gpt-5",
+      reasoningEffort: "none",
+      explicitReasoningEffort: true,
+    });
+  });
 });
 
 describe("createLiveSubAgentSources", () => {

src/session/runtime-assembly.ts

@@ -76,6 +76,12 @@ export interface SubAgentProviderConfig {
   apiKey?: string;
   model: string;
   reasoningEffort?: ReasoningEffort;
+  /**
+   * CL-10227: true when `reasoningEffort` was operator-chosen (Config
+   * explicitly set it) rather than derived. Absent = role defaults apply.
+   * Threads the fleet-pin signal from the primary seed into every worker.
+   */
+  explicitReasoningEffort?: boolean;
   providers: readonly Pick<
     ProviderCatalogEntry,
     "name" | "bifrostVirtualKey"
@@ -94,6 +100,9 @@ export function buildSubAgentProvider(
     ...(config.reasoningEffort !== undefined
       ? { reasoningEffort: config.reasoningEffort }
       : {}),
+    ...(config.explicitReasoningEffort === true
+      ? { explicitReasoningEffort: true }
+      : {}),
     ...(config.providers.find((p) => p.name === config.providerName)
       ?.bifrostVirtualKey === true
       ? { bifrostVirtualKey: true }

src/subagent/agent-fleet-effort.test.ts

@@ -166,4 +166,91 @@ describe("custom worker efforts", () => {
       expect(effort).toBe("medium");
     },
   );
+
+  // CL-10227: an explicit (operator-chosen) primary effort is a fleet-wide pin
+  // that overrides the role default for spawned workers.
+  const explicitProvider: ProviderCatalogEntry = {
+    ...provider,
+    reasoningEfforts: ["none", "high", "max"],
+  };
+  test.each([
+    { parent: "none" as const, expected: "none" },
+    { parent: "high" as const, expected: "high" },
+  ])(
+    "explicit parent %j pins the worker effort",
+    async ({ parent, expected }) => {
+      let worker: RunSubAgentParams | undefined;
+      const deps = createFleetDeps(
+        async (params) => {
+          worker = params;
+          return { report: "done" };
+        },
+        {
+          settings: { providers: { custom: explicitProvider } },
+          catalog: [explicitProvider],
+        },
+      );
+      deps.provider = {
+        providerName: explicitProvider.name,
+        baseURL: explicitProvider.baseURL,
+        model: "custom-model",
+        reasoningEffort: parent,
+        explicitReasoningEffort: true,
+      };
+      const result = await callFleetToolRaw(createSpawnAgentTool(deps), {
+        description: "inspect",
+        prompt: "inspect",
+        intent: "explore",
+      });
+      expect(result.isError).not.toBe(true);
+      await callFleetToolRaw(fleetTools(deps).wait, { timeout_ms: 2000 });
+      expect(worker?.provider.reasoningEffort).toBe(expected);
+    },
+  );
+
+  test("explicit effortPin still wins over an explicit parent", async () => {
+    // An explicit parent is a fleet pin, but the cascade still lets an explicit
+    // effortPin outrank it — the legacy pin-max case stays.
+    let worker: RunSubAgentParams | undefined;
+    const deps = createFleetDeps(
+      async (params) => {
+        worker = params;
+        return { report: "done" };
+      },
+      {
+        settings: { providers: { custom: explicitProvider } },
+        catalog: [explicitProvider],
+        profiles: [
+          {
+            id: "custom-leaf",
+            inference: {
+              mode: "pin",
+              order: [
+                {
+                  provider: explicitProvider.name,
+                  model: "custom-model",
+                  reasoningEffort: "max",
+                },
+              ],
+            },
+          },
+        ],
+      },
+    );
+    deps.provider = {
+      providerName: explicitProvider.name,
+      baseURL: explicitProvider.baseURL,
+      model: "custom-model",
+      reasoningEffort: "none",
+      explicitReasoningEffort: true,
+    };
+    const result = await callFleetToolRaw(createSpawnAgentTool(deps), {
+      description: "inspect",
+      prompt: "inspect",
+      agent: "custom-leaf",
+    });
+    expect(result.isError).not.toBe(true);
+    await callFleetToolRaw(fleetTools(deps).wait, { timeout_ms: 2000 });
+    expect(worker?.provider.reasoningEffort).toBe("max");
+  });
 });

src/subagent/agent-fleet.ts

@@ -1183,6 +1183,9 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
           ? { roleDefault: resolved.roleDefault }
           : {}),
         ...(parentEffort !== undefined ? { parentEffort } : {}),
+        ...(parentEffort !== undefined && provider.explicitReasoningEffort
+          ? { parentExplicit: true }
+          : {}),
         model: provider.model,
         isCodex: isCodexProviderName(provider.providerName),
         ...(reasoning?.reasoningEfforts !== undefined

src/subagent/types.ts

@@ -28,10 +28,18 @@ export interface SubAgentProvider {
   apiKey?: string;
   keyless?: boolean;
   model: string;
-  // Resolved effort for this spawn (pin > role default > parent). See
-  // resolveEffortForRole — leaves default to medium, orchestrators to high,
-  // so a primary /agent high selection does not force every leaf onto high.
+  // Resolved effort for this spawn (pin > explicit parent > role default >
+  // derived parent). See resolveEffortForRole — leaves default to medium,
+  // orchestrators to high; an operator-chosen (explicit) primary effort is a
+  // fleet-wide pin and beats the role default.
   reasoningEffort?: ReasoningEffort;
+  /**
+   * CL-10227: true when `reasoningEffort` was operator-chosen (Config sent an
+   * explicit reasoningEffort) rather than derived. Makes the parent effort a
+   * fleet-wide pin for every spawned worker (leaf and orchestrator). Absent =
+   * role defaults apply (CL-5162).
+   */
+  explicitReasoningEffort?: boolean;
   // Mirrors ProviderCatalogEntry.bifrostVirtualKey. Without it the dispatch
   // path builds a plain openai-compatible source and the gateway never
   // receives the x-bf-vk header.