Merge pull request #1135 from corbitsdev/cl-8310-0330-promptresidual-gpt-narrate-before-tools-after-grok-row

feat(prompt): add GPT narrate-before-tools family residual

Author: TheGreatAxios

src/agent/model-family-policy.test.ts

@@ -4,8 +4,8 @@ import { resolveModelFamilyPolicy } from "./model-family-policy.js";
 describe("resolveModelFamilyPolicy", () => {
   test("defaults are permissive for an unrecognized provider", () => {
     const policy = resolveModelFamilyPolicy({
-      providerName: "openai",
-      model: "gpt-4.1",
+      providerName: "unknown-provider",
+      model: "unknown-model",
     });
     expect(policy.family).toBe("default");
     expect(policy.applyGrokFinishBias).toBe(false);
@@ -55,8 +55,8 @@ describe("resolveModelFamilyPolicy", () => {
 
   test("advertisedToolDeny is empty by default and never contains use_skill", () => {
     const leaf = resolveModelFamilyPolicy({
-      providerName: "openai",
-      model: "gpt-4.1",
+      providerName: "unknown-provider",
+      model: "unknown-model",
       orchestrator: false,
     });
     expect(leaf.advertisedToolDeny).toEqual([]);
@@ -124,12 +124,12 @@ describe("resolveModelFamilyPolicy", () => {
         orchestrator: true,
       });
       expect(orchestrator.promptResidual).toBeUndefined();
-      // Default-family probe: anthropic/claude-sonnet-4 would hit the claude
-      // row now, and the gpt row has NOT landed yet (#1135), so openai/gpt-4.1
-      // is the probe that still resolves to the default family.
+      // Default-family probe: anthropic/claude-sonnet-4 hits the claude row
+      // and openai/gpt-4.1 hits the gpt row (#1135), so an unrecognized
+      // provider is the probe that still resolves to the default family.
       const base = resolveModelFamilyPolicy({
-        providerName: "openai",
-        model: "gpt-4.1",
+        providerName: "unknown-provider",
+        model: "unknown-model",
       });
       expect(base.family).toBe("default");
       expect(base.promptResidual).toBeUndefined();
@@ -154,21 +154,22 @@ describe("resolveModelFamilyPolicy", () => {
     expect(orchestrator.promptResidual).toBeUndefined();
   });
 
-  // The gpt family row has NOT landed yet (#1135): openai/gpt-4.1 and
-  // codex/gpt-5.1 are default-family probes here, asserting they resolve to
-  // the default family with no residual. Grok keeps its CL-8297 tool-budget
+  // The gpt family row has landed (#1135): openai/gpt-4.1 and codex/gpt-5.1
+  // resolve to the gpt family with the narrate-before-tools residual, leaf
+  // and orchestrator alike (no carve-out). Grok keeps its CL-8297 tool-budget
   // residual — the "no residual" claim below is default-family-only.
-  test("gpt probes resolve to default with no residual; grok keeps its tool budget", () => {
+  test("gpt probes resolve to gpt with the narrate residual; grok keeps its tool budget", () => {
     for (const input of [
       { providerName: "openai", model: "gpt-4.1" },
       { providerName: "codex", model: "gpt-5.1" },
     ] as const) {
-      const policy = resolveModelFamilyPolicy({
-        ...input,
-        orchestrator: false,
-      });
-      expect(policy.family).toBe("default");
-      expect(policy.promptResidual).toBeUndefined();
+      for (const orchestrator of [false, true]) {
+        const policy = resolveModelFamilyPolicy({ ...input, orchestrator });
+        expect(policy.family).toBe("gpt");
+        expect(policy.promptResidual).toContain(
+          "Narrate before tools (GPT worker):",
+        );
+      }
     }
     const grok = resolveModelFamilyPolicy({
       providerName: "xai/default",
@@ -178,4 +179,24 @@ describe("resolveModelFamilyPolicy", () => {
     expect(grok.family).toBe("grok");
     expect(grok.promptResidual).toContain("Tool budget:");
   });
+  test("gpt resolves its own family on permissive default thresholds (CL-8310)", () => {
+    const gpt = resolveModelFamilyPolicy({
+      providerName: "codex/default",
+      model: "gpt-5.5",
+    });
+    const base = resolveModelFamilyPolicy({
+      providerName: "anthropic",
+      model: "claude-sonnet-4",
+    });
+    expect(gpt.family).toBe("gpt");
+    // No eval characterization for gpt tool-only stretches yet: ship the
+    // permissive default, no finish-bias, no discipline rules. The
+    // narrate-before-tools residual is prompt-level (see prompts.ts), not a
+    // threshold.
+    expect(gpt.toolOnlyTurnNudgeAt).toBe(base.toolOnlyTurnNudgeAt);
+    expect(gpt.subAgentStallTimeoutMs).toBe(base.subAgentStallTimeoutMs);
+    expect(gpt.applyGrokFinishBias).toBe(false);
+    expect(gpt.toolDisciplineRules).toBeUndefined();
+    expect(gpt.advertisedToolDeny).toEqual([]);
+  });
 });

src/agent/model-family-policy.ts

@@ -41,7 +41,8 @@ export interface ModelFamilyPolicy {
   /**
    * Provider-family residual appended once to the assembled leaf system
    * prompt (CL-8297). Tool-budget text for grok, the XML task_guidance block
-   * for claude; the GPT seam stays unfilled until its lane lands (#1135).
+   * for claude, the narrate-before-tools note for gpt (CL-8310, primary and
+   * leaf alike).
    * Withheld from orchestrators and appended at the tail so it cannot
    * disturb the cached prompt prefix. Undefined for families that need none.
    */
@@ -169,6 +170,33 @@ const CLAUDE_POLICY: Omit<ModelFamilyPolicy, "family"> = {
   promptResidual: CLAUDE_TASK_GUIDANCE_NOTE,
 };
 
+// Tiny narrate-before-tools residual for GPT workers (CL-8310): GPT-5.5 runs
+// showed 6–13 silent tool-only turns. Shared thrash harness + spawn contracts
+// do the structural work; this is only a narrate-before-tools nudge.
+// Deliberately not manage_tasks ceremony — that is CL-7769, not this text.
+// The text lives here (policy owns data); buildGptNarrateBeforeToolsNote
+// (prompts.ts) returns it verbatim so the prompt carries exactly one copy.
+// Served cells (astra/sol/terra/…) are never named here — CL-8265
+// characterizes them later.
+export const GPT_NARRATE_BEFORE_TOOLS_NOTE = [
+  "Narrate before tools (GPT worker):",
+  "- Before each tool call, write one short line saying what you are doing and why.",
+  "- Never make back-to-back tool calls with no narration between them.",
+  "- When the dispatch brief's done-definition is met, write the report envelope instead of making another tool call.",
+].join("\n");
+
+// GPT (Codex / gpt-*) thresholds are provisional: we have no eval
+// characterization yet for how GPT behaves under tool-only stretches or
+// background-run stalls. Ship the permissive default rather than guessing at
+// a tightened number; the narrate-before-tools residual is prompt-level (see
+// GPT_NARRATE_BEFORE_TOOLS_NOTE above), not a threshold.
+const GPT_POLICY: Omit<ModelFamilyPolicy, "family"> = {
+  ...DEFAULT_POLICY,
+  // Primary and leaf alike, so unlike the grok finish-bias there is no
+  // orchestrator carve-out: the resolver below returns this as-is.
+  promptResidual: GPT_NARRATE_BEFORE_TOOLS_NOTE,
+};
+
 export function resolveModelFamilyPolicy(input: {
   providerName: string;
   model?: string;
@@ -204,6 +232,9 @@ export function resolveModelFamilyPolicy(input: {
       return orchestrator
         ? { family, ...DEFAULT_POLICY }
         : { family, ...CLAUDE_POLICY };
+    case "gpt":
+      // Primary and leaf alike: no orchestrator carve-out.
+      return { family, ...GPT_POLICY };
     default:
       return { family: "default", ...DEFAULT_POLICY };
   }

src/agent/prompt-sizes.test.ts

@@ -345,10 +345,11 @@ describe("grok tool-budget residual (CL-8297)", () => {
   test("default-family and orchestrator prompts carry no tool budget", () => {
     const defaultPrompt = assembleDirectorPrompt("builder", "default");
     expect(defaultPrompt).not.toContain("Tool budget:");
-    // The default probe (openai/gpt-4.1) resolves to the default family, so
-    // the default column carries no family residual at all — not the claude
-    // task_guidance block either.
+    // The default probe resolves to the default family, so the default
+    // column carries no family residual — neither the claude task_guidance
+    // block nor the gpt narrate-before-tools nudge.
     expect(defaultPrompt).not.toContain("<task_guidance>");
+    expect(defaultPrompt).not.toContain("Narrate before tools (GPT worker):");
     expect(assembleDirectorPrompt("skywalker", "grok")).not.toContain(
       "Tool budget:",
     );

src/agent/prompt-sizes.ts

@@ -57,11 +57,12 @@ export const CANONICAL_PROMPT_ENV: EnvironmentInfo = {
 };
 
 const GROK_PROVIDER = { providerName: "xai/default", model: "grok-4.6" };
-// Default-family probe: openai/gpt-4.1 resolves to the default family (the
-// gpt row lands later in CL-8310), so the default column carries no residual.
+// Default-family probe: an unrecognized provider stays on the default
+// family no matter how many family rows land (claude/gpt already ship),
+// so the default column carries no residual.
 const DEFAULT_PROVIDER = {
-  providerName: "openai",
-  model: "gpt-4.1",
+  providerName: "unknown-provider",
+  model: "unknown-model",
 };
 
 /** Families in the size table: default assembly vs Grok (+finish-bias note). */

src/agent/prompts.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import {
   buildChatSystemPrompt,
   buildClaudeTaskGuidanceNote,
+  buildGptNarrateBeforeToolsNote,
   buildGrokLeafAntiThrashNote,
   buildGuidelines,
   buildPromptDisciplineBlock,
@@ -452,3 +453,89 @@ describe("claude XML task_guidance residual (provider residual, not a prompt for
     );
   });
 });
+
+describe("gpt narrate-before-tools residual (CL-8310)", () => {
+  it("is a 3-line narrate-before-tools note, not manage_tasks ceremony", () => {
+    const note = buildGptNarrateBeforeToolsNote();
+    expect(note).toContain("Narrate before tools (GPT worker):");
+    expect(note).toMatch(/before.*tool call.*one short line/is);
+    expect(note).toMatch(/no narration between them/i);
+    expect(note).toContain("write the report envelope");
+    expect(note.toLowerCase()).not.toContain("manage_tasks");
+  });
+
+  it("appears exactly once on a gpt leaf prompt", () => {
+    const prompt = buildSubAgentSystemPrompt(undefined, undefined, undefined, {
+      orchestrator: false,
+      promptResidual: buildGptNarrateBeforeToolsNote(),
+    });
+    const note = buildGptNarrateBeforeToolsNote();
+    expect(countOccurrences(prompt, note)).toBe(1);
+    expect(prompt.trimEnd().endsWith(note)).toBe(true);
+  });
+
+  it("appears exactly once on a gpt primary prompt", () => {
+    const prompt = buildChatSystemPrompt(
+      undefined,
+      undefined,
+      undefined,
+      [],
+      "orchestrator",
+      undefined,
+      undefined,
+      { promptResidual: buildGptNarrateBeforeToolsNote() },
+    );
+    const note = buildGptNarrateBeforeToolsNote();
+    expect(countOccurrences(prompt, note)).toBe(1);
+  });
+
+  it("is absent by default on both primary and leaf", () => {
+    const leaf = buildSubAgentSystemPrompt(undefined, undefined, undefined, {
+      orchestrator: false,
+      grokAntiThrash: false,
+    });
+    const primary = buildChatSystemPrompt(
+      undefined,
+      undefined,
+      undefined,
+      [],
+      "orchestrator",
+    );
+    expect(leaf).not.toContain("Narrate before tools (GPT worker):");
+    expect(primary).not.toContain("Narrate before tools (GPT worker):");
+  });
+
+  it("is absent on grok and claude prompts", () => {
+    const grokLeaf = buildSubAgentSystemPrompt(
+      undefined,
+      undefined,
+      undefined,
+      {
+        orchestrator: false,
+        grokAntiThrash: true,
+      },
+    );
+    const claudeLeaf = buildSubAgentSystemPrompt(
+      undefined,
+      undefined,
+      undefined,
+      {
+        orchestrator: false,
+        grokAntiThrash: false,
+      },
+    );
+    const claudePrimary = buildChatSystemPrompt(
+      undefined,
+      undefined,
+      undefined,
+      [],
+      "orchestrator",
+    );
+    for (const prompt of [grokLeaf, claudeLeaf, claudePrimary]) {
+      expect(prompt).not.toContain("Narrate before tools (GPT worker):");
+      expect(prompt).not.toContain("Narrate before tools (GPT");
+    }
+    // The grok row keeps its own residual, untouched.
+    expect(grokLeaf).toContain("Finish bias (xAI / Grok worker):");
+  });
+});

src/agent/prompts.ts

@@ -13,6 +13,7 @@ import {
 } from "./worker-contract.js";
 import {
   CLAUDE_TASK_GUIDANCE_NOTE,
+  GPT_NARRATE_BEFORE_TOOLS_NOTE,
   GROK_PROMPT_RESIDUAL,
 } from "./model-family-policy.js";
 
@@ -459,6 +460,13 @@ export function buildChatSystemPrompt(
   sessionMode: SessionMode = "orchestrator",
   toolAvailability: ToolAvailability = DEFAULT_TOOL_AVAILABILITY,
   guidelineConfig?: GuidelineConfig,
+  opts: {
+    /**
+     * Family policy residual (CL-8297) appended once at the tail so it
+     * cannot disturb the cached prompt prefix. Unset for families with none.
+     */
+    promptResidual?: string | undefined;
+  } = {},
 ): string {
   const sections = [
     baseSection(
@@ -477,6 +485,9 @@ export function buildChatSystemPrompt(
   if (extensions !== undefined && extensions.length > 0) {
     sections.push(...extensions);
   }
+  if (opts.promptResidual !== undefined && opts.promptResidual.length > 0) {
+    sections.push(opts.promptResidual);
+  }
   return joinSections(sections);
 }
 
@@ -536,6 +547,17 @@ export function buildClaudeTaskGuidanceNote(): string {
   return CLAUDE_TASK_GUIDANCE_NOTE;
 }
 
+// Tiny residual for GPT workers (CL-8310): GPT-5.5/5.6-luna runs showed 6–13
+// silent tool-only turns. Shared thrash harness + spawn contracts do the
+// structural work; this is only a narrate-before-tools nudge. Deliberately
+// not manage_tasks ceremony — that is CL-7769, not this text.
+// Single source of truth is the GPT_NARRATE_BEFORE_TOOLS_NOTE block in
+// model-family-policy.ts (policy owns data); this returns that block verbatim
+// so the prompt carries one gpt residual with no line twice.
+export function buildGptNarrateBeforeToolsNote(): string {
+  return GPT_NARRATE_BEFORE_TOOLS_NOTE;
+}
+
 export function buildSubAgentSystemPrompt(
   extensions?: string[],
   env?: EnvironmentInfo,

src/exec/runner.ts

@@ -733,6 +733,8 @@ export async function runExec(config: Config): Promise<ExecResult> {
           sessionMode,
           toolAvailability,
           skills: agentToolset.skills,
+          providerName: config.providerName,
+          model: config.model,
         })
       ).systemPrompt;
 

src/session/runtime-assembly.ts

@@ -15,6 +15,7 @@ import type { Compactor } from "@intx/types/runtime";
 
 import { buildChatSystemPrompt } from "../agent/prompts.js";
 import type { GuidelineSubBlockId } from "../agent/prompts.js";
+import { resolveModelFamilyPolicy } from "../agent/model-family-policy.js";
 import type { ToolAvailability } from "../agent/tool-search.js";
 import { gatherEnvironment } from "../agent/environment.js";
 import {
@@ -293,6 +294,10 @@ export interface SessionChatPromptArgs {
   // Guideline sub-block ids to drop (see GUIDELINE_SUB_BLOCK_IDS).
   // Omitted = full guidelines.
   promptSectionOmit?: readonly GuidelineSubBlockId[];
+  // Active session provider/model, for family residuals on the primary
+  // prompt (CL-8310: GPT narrate-before-tools). Omitted = no family residual.
+  providerName?: string;
+  model?: string;
   // Session-start snapshot from createAgentToolset. When provided, skip
   // rediscovery so the prompt listing and skill_search share one catalog.
   skills?: readonly SkillSummary[];
@@ -320,6 +325,19 @@ export async function loadSessionChatPrompt(
     ...(args.systemPromptExtensions ?? []),
     ...overrides.append,
   ];
+  // Family residual on the primary prompt (CL-8310): resolved from the model
+  // family policy as an orchestrator — primaries dispatch rather than doing
+  // the work directly, so grok/claude primaries stay untouched (their rows
+  // withhold the residual from orchestrators) while the gpt row carries its
+  // narrate-before-tools note primary and leaf alike.
+  const { promptResidual } =
+    args.providerName !== undefined
+      ? resolveModelFamilyPolicy({
+          providerName: args.providerName,
+          ...(args.model !== undefined ? { model: args.model } : {}),
+          orchestrator: true,
+        })
+      : { promptResidual: undefined };
   return {
     systemPrompt: buildChatSystemPrompt(
       extensions.length > 0 ? extensions : undefined,
@@ -331,6 +349,7 @@ export async function loadSessionChatPrompt(
       args.promptSectionOmit !== undefined
         ? { omit: args.promptSectionOmit }
         : undefined,
+      { promptResidual },
     ),
     skills,
   };