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

Primary and leaf prompts carry a 3-line narrate-before-tools residual when
the active session resolves to the gpt family (codex, gpt-*); grok and
claude prompts are untouched and the residual appears exactly once.

Fixes CL-8310

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",

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/prompts.test.ts

@@ -373,7 +373,6 @@ describe("grok finish-bias residual gating (extends existing provider-family tes
   });
 });
 
-<<<<<<< HEAD
 describe("promptResidual assembly (CL-8297)", () => {
   const TOOL_BUDGET =
     "Tool budget:\n" +
@@ -468,7 +467,7 @@ describe("gpt narrate-before-tools residual (CL-8310)", () => {
   it("appears exactly once on a gpt leaf prompt", () => {
     const prompt = buildSubAgentSystemPrompt(undefined, undefined, undefined, {
       orchestrator: false,
-      gptNarrateBeforeTools: true,
+      promptResidual: buildGptNarrateBeforeToolsNote(),
     });
     const note = buildGptNarrateBeforeToolsNote();
     expect(countOccurrences(prompt, note)).toBe(1);
@@ -484,7 +483,7 @@ describe("gpt narrate-before-tools residual (CL-8310)", () => {
       "orchestrator",
       undefined,
       undefined,
-      { gptNarrateBeforeTools: true },
+      { promptResidual: buildGptNarrateBeforeToolsNote() },
     );
     const note = buildGptNarrateBeforeToolsNote();
     expect(countOccurrences(prompt, note)).toBe(1);

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

@@ -704,6 +704,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,
   };

src/subagent/provider-family.test.ts

@@ -124,7 +124,7 @@ describe("isKimiLeafProvider", () => {
 });
 
 describe("detectModelFamily", () => {
-  test("detects grok, kimi, claude, and default", () => {
+  test("detects grok, kimi, claude, gpt, and default", () => {
     expect(
       detectModelFamily({ providerName: "xai/default", model: "grok-4.5" }),
     ).toBe("grok");
@@ -142,6 +142,12 @@ describe("detectModelFamily", () => {
     ).toBe("claude");
     expect(
       detectModelFamily({ providerName: "openai", model: "gpt-4.1" }),
+    ).toBe("gpt");
+    expect(
+      detectModelFamily({
+        providerName: "unknown-provider",
+        model: "unknown-model",
+      }),
     ).toBe("default");
   });
 });

src/subagent/provider-family.ts

@@ -1,5 +1,6 @@
 import { GROK_RESPONSES_PROVIDER } from "../provider/grok-responses.js";
 import { isXaiProviderName } from "../config/xai-providers.js";
+import { isCodexProviderName } from "../config/codex-providers.js";
 
 /**
  * True when the leaf inference path is xAI / Grok family.
@@ -49,8 +50,37 @@ export function isClaudeLeafProvider(input: {
   return false;
 }
 
+/**
+ * True when the inference path is the GPT family: a Codex provider name
+ * (codex/ OAuth profiles, the codex-responses adapter, bare codex) or a
+ * gpt-* model id on any provider. Served codex cells (astra/sol/terra/luna)
+ * all match the generic gpt-* model shape — never name them here; CL-8265
+ * characterizes cells later.
+ */
+export function isGptProvider(input: {
+  providerName: string;
+  model?: string;
+}): boolean {
+  const name = input.providerName.toLowerCase();
+  if (
+    isCodexProviderName(name) ||
+    name === "codex" ||
+    name.includes("codex")
+  )
+    return true;
+  if (input.model !== undefined && /^gpt-/i.test(input.model.trim()))
+    return true;
+  return false;
+}
+
 /** Model families the shared directors branch on via ModelFamilyPolicy. */
-export type ModelFamily = "grok" | "kimi" | "muse" | "claude" | "default";
+export type ModelFamily =
+  | "grok"
+  | "kimi"
+  | "muse"
+  | "claude"
+  | "gpt"
+  | "default";
 
 /**
  * Resolves a provider/model to a ModelFamily. Generalizes
@@ -66,6 +96,7 @@ export function detectModelFamily(input: {
   if (isKimiLeafProvider(input)) return "kimi";
   if (isMuseSparkLeafProvider(input)) return "muse";
   if (isClaudeLeafProvider(input)) return "claude";
+  if (isGptProvider(input)) return "gpt";
   return "default";
 }
 

src/tui/runner/session.ts

@@ -447,6 +447,8 @@ export async function assembleTUISession(
     sessionMode: liveSessionMode,
     toolAvailability,
     skills: toolset.skills,
+    providerName: config.providerName,
+    model: config.model,
   });
 
   const directorHolder: { instance?: ReturnType<typeof createChatDirector> } =