fix(subagent): tighten explicit effort, drop flag on clamp

Author: TheGreatAxios

src/provider/reasoning-effort.test.ts

@@ -385,7 +385,7 @@ describe("pickEffortFromCascade (precedence table)", () => {
       pickEffortFromCascade({
         roleDefault: "medium",
         parentEffort: "none",
-        parentExplicit: true,
+        explicitParentEffort: true,
         supported: ["none", "low", "medium", "high"],
       }),
     ).toBe("none");
@@ -396,7 +396,7 @@ describe("pickEffortFromCascade (precedence table)", () => {
       pickEffortFromCascade({
         roleDefault: "medium",
         parentEffort: "high",
-        parentExplicit: true,
+        explicitParentEffort: true,
         supported: ["low", "medium", "high"],
       }),
     ).toBe("high");
@@ -407,7 +407,7 @@ describe("pickEffortFromCascade (precedence table)", () => {
       pickEffortFromCascade({
         roleDefault: "medium",
         parentEffort: "xhigh",
-        parentExplicit: true,
+        explicitParentEffort: true,
         supported: ["low", "medium", "high"],
       }),
     ).toBe("high");
@@ -419,18 +419,17 @@ describe("pickEffortFromCascade (precedence table)", () => {
         pin: "low",
         roleDefault: "medium",
         parentEffort: "xhigh",
-        parentExplicit: true,
+        explicitParentEffort: true,
         supported: ["low", "medium", "high"],
       }),
     ).toBe("low");
   });
 
-  test("8. falsy parentExplicit keeps role default above parent (CL-5162)", () => {
+  test("8. unset explicitParentEffort keeps role default above parent (CL-5162)", () => {
     expect(
       pickEffortFromCascade({
         roleDefault: "medium",
         parentEffort: "high",
-        parentExplicit: false,
         supported: ["low", "medium", "high"],
       }),
     ).toBe("medium");
@@ -517,7 +516,7 @@ describe("resolveEffortForRole", () => {
       resolveEffortForRole({
         orchestrator: false,
         parentEffort: "none",
-        parentExplicit: true,
+        explicitParentEffort: true,
         model: "gpt-5.1",
       }),
     ).toBe("none");
@@ -528,7 +527,7 @@ describe("resolveEffortForRole", () => {
       resolveEffortForRole({
         orchestrator: true,
         parentEffort: "low",
-        parentExplicit: true,
+        explicitParentEffort: true,
         model: "gpt-5",
       }),
     ).toBe("low");
@@ -539,7 +538,6 @@ describe("resolveEffortForRole", () => {
       resolveEffortForRole({
         orchestrator: false,
         parentEffort: "high",
-        parentExplicit: false,
         model: "gpt-5",
       }),
     ).toBe("medium");
@@ -551,7 +549,7 @@ describe("resolveEffortForRole", () => {
         orchestrator: false,
         pin: "low",
         parentEffort: "high",
-        parentExplicit: true,
+        explicitParentEffort: true,
         model: "gpt-5",
       }),
     ).toBe("low");

src/provider/reasoning-effort.ts

@@ -382,12 +382,8 @@ 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.
-   */
-  parentExplicit?: boolean;
+  /** Marker when the parent effort was operator-chosen (see SubAgentProvider). */
+  explicitParentEffort?: true;
   model: string;
   isCodex?: boolean;
   providerEfforts?: readonly ReasoningEffort[];
@@ -414,7 +410,7 @@ export function pickEffortFromCascade(opts: {
   pin?: ReasoningEffort;
   roleDefault: ReasoningEffort;
   parentEffort?: ReasoningEffort;
-  parentExplicit?: boolean;
+  explicitParentEffort?: true;
   supported: readonly ReasoningEffort[];
 }): ReasoningEffort | undefined {
   if (opts.supported.length === 0) return undefined;
@@ -425,7 +421,7 @@ export function pickEffortFromCascade(opts: {
   }
   // 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) {
+  if (opts.explicitParentEffort === true && opts.parentEffort !== undefined) {
     return opts.supported.includes(opts.parentEffort)
       ? opts.parentEffort
       : clampEffort(opts.parentEffort, opts.supported);
@@ -471,7 +467,9 @@ export function resolveEffortForRole(
     ...(opts.parentEffort !== undefined
       ? { parentEffort: opts.parentEffort }
       : {}),
-    ...(opts.parentExplicit === true ? { parentExplicit: true } : {}),
+    ...(opts.explicitParentEffort === true
+      ? { explicitParentEffort: true }
+      : {}),
     supported,
   });
 }

src/session/runtime-assembly.ts

@@ -76,11 +76,8 @@ export interface SubAgentProviderConfig {
   apiKey?: string;
   model: string;
   reasoningEffort?: ReasoningEffort;
-  /**
-   * True when `reasoningEffort` was operator-chosen (Config explicitly set it)
-   * rather than derived. Absent = role defaults apply (CL-5162).
-   */
-  explicitReasoningEffort?: boolean;
+  /** Present when operator-chosen — see SubAgentProvider.explicitReasoningEffort. */
+  explicitReasoningEffort?: true;
   providers: readonly Pick<
     ProviderCatalogEntry,
     "name" | "bifrostVirtualKey"

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

@@ -208,6 +208,45 @@ describe("custom worker efforts", () => {
     },
   );
 
+  test("clamped explicit parent drops the explicit marker (CL-10227)", async () => {
+    // An explicit parent `none` on a model whose ladder rejects `none` is
+    // clamped onto the supported set (low). The clamped value is derived, not
+    // operator-chosen, so the explicit marker must not survive — otherwise the
+    // worker would carry a fleet-wide explicit pin it never actually received.
+    let worker: RunSubAgentParams | undefined;
+    const noNoneProvider: ProviderCatalogEntry = {
+      ...provider,
+      reasoningEfforts: ["low", "high", "max"],
+    };
+    const deps = createFleetDeps(
+      async (params) => {
+        worker = params;
+        return { report: "done" };
+      },
+      {
+        settings: { providers: { custom: noNoneProvider } },
+        catalog: [noNoneProvider],
+      },
+    );
+    deps.provider = {
+      providerName: noNoneProvider.name,
+      baseURL: noNoneProvider.baseURL,
+      model: "custom-model",
+      reasoningEffort: "none",
+      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("low");
+    // The clamped value is derived, so the flag is dropped (absent), not `true`.
+    expect(worker?.provider.explicitReasoningEffort).toBeUndefined();
+  });
+
   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.

src/subagent/agent-fleet.ts

@@ -1184,7 +1184,7 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
           : {}),
         ...(parentEffort !== undefined ? { parentEffort } : {}),
         ...(parentEffort !== undefined && provider.explicitReasoningEffort
-          ? { parentExplicit: true }
+          ? { explicitParentEffort: true }
           : {}),
         model: provider.model,
         isCodex: isCodexProviderName(provider.providerName),
@@ -1193,9 +1193,31 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
           : {}),
       });
       if (effort !== undefined) {
-        provider = { ...provider, reasoningEffort: effort };
+        // The explicit marker travels only when the re-resolved effort is
+        // exactly the operator-chosen parent value. Clamping an explicit
+        // parent effort onto the supported set yields a derived (not
+        // operator-chosen) value, so the flag is dropped — a clamped value
+        // must not mislabel itself as a fleet-wide explicit pin for every
+        // descendant. `true` is the only value the type allows.
+        const carriedExplicit =
+          provider.explicitReasoningEffort === true &&
+          parentEffort !== undefined &&
+          effort === parentEffort;
+        provider = {
+          ...provider,
+          reasoningEffort: effort,
+          ...(carriedExplicit ? { explicitReasoningEffort: true } : {}),
+        };
+        if (!carriedExplicit) {
+          const { explicitReasoningEffort: _drop, ...rest } = provider;
+          provider = rest;
+        }
       } else {
-        const { reasoningEffort: _drop, ...rest } = provider;
+        const {
+          reasoningEffort: _drop,
+          explicitReasoningEffort: _dropExplicit,
+          ...rest
+        } = provider;
         provider = rest;
       }
 

src/subagent/types.ts

@@ -33,9 +33,13 @@ export interface SubAgentProvider {
   // orchestrators to high; an operator-chosen (explicit) primary effort is a
   // fleet-wide pin and beats the role default.
   reasoningEffort?: ReasoningEffort;
-  // True when `reasoningEffort` was operator-chosen (Config sent an explicit
-  // reasoningEffort) rather than derived. Absent = role defaults apply (CL-5162).
-  explicitReasoningEffort?: boolean;
+  /**
+   * Present (true) when `reasoningEffort` was operator-chosen (Config sent an
+   * explicit reasoningEffort) rather than derived. A present marker is a
+   * fleet-wide pin that outranks the role default; absent = role defaults
+   * apply (CL-5162).
+   */
+  explicitReasoningEffort?: true;
   // Mirrors ProviderCatalogEntry.bifrostVirtualKey. Without it the dispatch
   // path builds a plain openai-compatible source and the gateway never
   // receives the x-bf-vk header.