Merge pull request #1137 from corbitsdev/cl-8309-0330-promptresidual-claude-xml-task_guidance-after-grok-row

feat(agents): claude xml task_guidance prompt 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: "anthropic",
-      model: "claude-sonnet-4",
+      providerName: "openai",
+      model: "gpt-4.1",
     });
     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: "anthropic",
-      model: "claude-opus-4-6",
+      providerName: "openai",
+      model: "gpt-4.1",
       orchestrator: false,
     });
     expect(leaf.advertisedToolDeny).toEqual([]);
@@ -124,11 +124,58 @@ 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.
       const base = resolveModelFamilyPolicy({
-        providerName: "anthropic",
-        model: "claude-sonnet-4",
+        providerName: "openai",
+        model: "gpt-4.1",
       });
+      expect(base.family).toBe("default");
       expect(base.promptResidual).toBeUndefined();
     });
   });
+
+  test("claude leaves carry the XML task_guidance residual; orchestrators do not", () => {
+    const leaf = resolveModelFamilyPolicy({
+      providerName: "anthropic",
+      model: "claude-sonnet-4",
+      orchestrator: false,
+    });
+    expect(leaf.family).toBe("claude");
+    expect(leaf.promptResidual).toContain("<task_guidance>");
+    expect(leaf.promptResidual).toContain("</task_guidance>");
+    expect(leaf.advertisedToolDeny).toEqual([]);
+    const orchestrator = resolveModelFamilyPolicy({
+      providerName: "anthropic",
+      model: "claude-sonnet-4",
+      orchestrator: true,
+    });
+    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
+  // residual — the "no residual" claim below is default-family-only.
+  test("gpt probes resolve to default with no 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();
+    }
+    const grok = resolveModelFamilyPolicy({
+      providerName: "xai/default",
+      model: "grok-4.6",
+      orchestrator: false,
+    });
+    expect(grok.family).toBe("grok");
+    expect(grok.promptResidual).toContain("Tool budget:");
+  });
 });

src/agent/model-family-policy.ts

@@ -40,10 +40,10 @@ export interface ModelFamilyPolicy {
   toolDisciplineRules?: string;
   /**
    * Provider-family residual appended once to the assembled leaf system
-   * prompt (CL-8297). Generic tool-budget text today (grok only); the
-   * ceremony / Claude / GPT seams stay unfilled in sibling lanes. Withheld
-   * from orchestrators and appended at the tail so it cannot disturb the
-   * cached prompt prefix. Undefined for families that need none.
+   * 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).
+   * Withheld from orchestrators and appended at the tail so it cannot
+   * disturb the cached prompt prefix. Undefined for families that need none.
    */
   promptResidual?: string | undefined;
 }
@@ -66,6 +66,7 @@ const GROK_WRAP_UP_NUDGE_TEXT =
 // sits comfortably above the observed healthy ceiling; the nudge is a
 // check-in, not a stop, so erring high costs nothing. Tightened only for
 // families with observed runaway tool-only behavior (see grok below).
+/** Default policy: permissive, no finish bias, no prompt residual. */
 const DEFAULT_POLICY: Omit<ModelFamilyPolicy, "family"> = {
   toolOnlyTurnNudgeAt: 25,
   wrapUpNudgeText: DEFAULT_WRAP_UP_NUDGE_TEXT,
@@ -149,6 +150,24 @@ export const GROK_PROMPT_RESIDUAL = [
   "- Do not narrate a plan before acting on a small task; act, then report.",
   "- Verify with the test command once at the end, not after every edit.",
 ].join("\n");
+// Claude (Anthropic) ships one XML residual, not prose: a prose residual did
+// nothing, but a single <task_guidance> block cut Sonnet tokens. The block is
+// the whole residual — never a full-prompt XML renderer. The text lives here
+// (policy owns data); buildClaudeTaskGuidanceNote (prompts.ts) returns it
+// verbatim so the prompt carries exactly one copy.
+export const CLAUDE_TASK_GUIDANCE_NOTE = [
+  "<task_guidance>",
+  "Autonomous coding turn: finish the work in this turn on your best judgment.",
+  "1. Follow the dispatch brief exactly; its Success criteria are the done-definition.",
+  "2. Batch independent tool calls into a single turn; work from files already read this session.",
+  "3. Finish the task when the done-definition is met: prefer the structured report envelope over another tool call.",
+  "</task_guidance>",
+].join("\n");
+
+const CLAUDE_POLICY: Omit<ModelFamilyPolicy, "family"> = {
+  ...DEFAULT_POLICY,
+  promptResidual: CLAUDE_TASK_GUIDANCE_NOTE,
+};
 
 export function resolveModelFamilyPolicy(input: {
   providerName: string;
@@ -178,6 +197,13 @@ export function resolveModelFamilyPolicy(input: {
       };
     case "muse":
       return { family, ...MUSE_POLICY };
+    case "claude":
+      // Like the grok finish-bias residual, the task_guidance block only makes
+      // sense on leaf workers — orchestrators dispatch rather than doing the
+      // work directly, so they resolve to the permissive default (no residual).
+      return orchestrator
+        ? { family, ...DEFAULT_POLICY }
+        : { family, ...CLAUDE_POLICY };
     default:
       return { family: "default", ...DEFAULT_POLICY };
   }

src/agent/prompt-sizes.test.ts

@@ -343,9 +343,12 @@ describe("grok tool-budget residual (CL-8297)", () => {
   });
 
   test("default-family and orchestrator prompts carry no tool budget", () => {
-    expect(assembleDirectorPrompt("builder", "default")).not.toContain(
-      "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.
+    expect(defaultPrompt).not.toContain("<task_guidance>");
     expect(assembleDirectorPrompt("skywalker", "grok")).not.toContain(
       "Tool budget:",
     );

src/agent/prompt-sizes.ts

@@ -12,12 +12,12 @@ import {
   type DirectorPackage,
 } from "./directors/types.js";
 import { buildChatSystemPrompt, buildSubAgentSystemPrompt } from "./prompts.js";
+import { resolveModelFamilyPolicy } from "./model-family-policy.js";
 import {
   formatAgentsMdExtension,
   MAX_AGENTS_MD_BYTES,
 } from "./context-extensions.js";
 import { shouldApplyGrokAntiThrash } from "../subagent/provider-family.js";
-import { resolveModelFamilyPolicy } from "./model-family-policy.js";
 import { isCodexProviderName } from "../config/codex-providers.js";
 import { shellCollectDefinition } from "./background-shell-tool.js";
 import {
@@ -37,8 +37,9 @@ import { webSearchDefinition } from "../tools/web-search.js";
  * extensions=[director systemPromptRole] + environment + tools +
  * appendix, with the Grok finish-bias note gated by
  * shouldApplyGrokAntiThrash (leaves on Grok-family providers only) and the
- * family promptResidual (CL-8297 tool budget, grok leaves only) resolved
- * from the model family policy.
+ * family promptResidual (CL-8297 tool budget for grok leaves, XML
+ * task_guidance block for claude leaves) resolved from the model family
+ * policy.
  *
  * The env and provider inputs are pinned here so sizes never drift with the
  * machine, date, or checkout — only real prompt changes move the numbers.
@@ -56,9 +57,11 @@ 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.
 const DEFAULT_PROVIDER = {
-  providerName: "anthropic",
-  model: "claude-sonnet-4",
+  providerName: "openai",
+  model: "gpt-4.1",
 };
 
 /** Families in the size table: default assembly vs Grok (+finish-bias note). */

src/agent/prompts.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import {
   buildChatSystemPrompt,
+  buildClaudeTaskGuidanceNote,
   buildGrokLeafAntiThrashNote,
   buildGuidelines,
   buildPromptDisciplineBlock,
@@ -396,3 +397,58 @@ describe("promptResidual assembly (CL-8297)", () => {
     expect(prompt).not.toContain("Tool budget:");
   });
 });
+
+describe("claude XML task_guidance residual (provider residual, not a prompt fork)", () => {
+  it("appends exactly one balanced <task_guidance> block for a claude worker", () => {
+    const prompt = buildSubAgentSystemPrompt(undefined, undefined, undefined, {
+      orchestrator: false,
+      promptResidual: buildClaudeTaskGuidanceNote(),
+    });
+    expect(countOccurrences(prompt, "<task_guidance>")).toBe(1);
+    expect(countOccurrences(prompt, "</task_guidance>")).toBe(1);
+  });
+
+  it("is absent without promptResidual — grok, gpt, and orchestrator rows untouched", () => {
+    for (const opts of [
+      { orchestrator: false },
+      { orchestrator: false, grokAntiThrash: true },
+      { orchestrator: true },
+    ] as const) {
+      const prompt = buildSubAgentSystemPrompt(
+        undefined,
+        undefined,
+        undefined,
+        opts,
+      );
+      expect(prompt).not.toContain("<task_guidance>");
+      expect(prompt).not.toContain("</task_guidance>");
+    }
+  });
+
+  it("emits one block with balanced tags, never a full-prompt XML renderer", () => {
+    const note = buildClaudeTaskGuidanceNote();
+    expect(countOccurrences(note, "<task_guidance>")).toBe(1);
+    expect(countOccurrences(note, "</task_guidance>")).toBe(1);
+    expect(note).not.toMatch(/<system_prompt>|<prompt>|<identity>/);
+  });
+
+  it("keeps the measured CL-7775 shape: rationale first, numbered approach, named output contract, positively framed", () => {
+    const lines = buildClaudeTaskGuidanceNote().split("\n");
+    // Rationale first: the lead line frames the turn before any directive.
+    expect(lines[1]).toMatch(/^Autonomous coding turn:/);
+    // Numbered approach, not bullets.
+    expect(lines.slice(2, 5).map((l) => l.split(".")[0])).toEqual([
+      "1",
+      "2",
+      "3",
+    ]);
+    // Named output contract.
+    expect(buildClaudeTaskGuidanceNote()).toContain(
+      "structured report envelope",
+    );
+    // Positive framing: no negative imperatives.
+    expect(buildClaudeTaskGuidanceNote()).not.toMatch(
+      /\b(do not|don't|never|stop calling)\b/i,
+    );
+  });
+});

src/agent/prompts.ts

@@ -11,7 +11,10 @@ import {
   buildWorkerContract,
   buildWorkerToolNames,
 } from "./worker-contract.js";
-import { GROK_PROMPT_RESIDUAL } from "./model-family-policy.js";
+import {
+  CLAUDE_TASK_GUIDANCE_NOTE,
+  GROK_PROMPT_RESIDUAL,
+} from "./model-family-policy.js";
 
 // Advertise every gated core tool when the caller has no session-start facts
 // (tests, ad-hoc prompt previews) — except wait_agents, which is mount-gated:
@@ -520,6 +523,19 @@ export function buildGrokLeafAntiThrashNote(): string {
   return GROK_PROMPT_RESIDUAL;
 }
 
+// Single XML residual for Claude-family workers: a prose residual did
+// nothing, but one <task_guidance> block cut Sonnet tokens. One block only —
+// never a full-prompt XML renderer, never applied outside the claude family.
+// Rebuilt end to end from Anthropic's prompting docs (CL-8309): rationale
+// first, numbered approach, named output contract; every line is positively
+// framed and scope-explicit for Sonnet's literal instruction-following.
+// Single source of truth is the CLAUDE_TASK_GUIDANCE_NOTE block in
+// model-family-policy.ts (policy owns data); this returns that block verbatim
+// so the prompt carries one claude residual with no line twice.
+export function buildClaudeTaskGuidanceNote(): string {
+  return CLAUDE_TASK_GUIDANCE_NOTE;
+}
+
 export function buildSubAgentSystemPrompt(
   extensions?: string[],
   env?: EnvironmentInfo,

src/subagent/provider-family.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   detectModelFamily,
+  isClaudeLeafProvider,
   isKimiLeafProvider,
   isXaiGrokLeafProvider,
   shouldApplyGrokAntiThrash,
@@ -121,7 +122,7 @@ describe("isKimiLeafProvider", () => {
 });
 
 describe("detectModelFamily", () => {
-  test("detects grok, kimi, and default", () => {
+  test("detects grok, kimi, claude, and default", () => {
     expect(
       detectModelFamily({ providerName: "xai/default", model: "grok-4.5" }),
     ).toBe("grok");
@@ -136,6 +137,60 @@ describe("detectModelFamily", () => {
         providerName: "anthropic",
         model: "claude-sonnet-4",
       }),
+    ).toBe("claude");
+    expect(
+      detectModelFamily({ providerName: "openai", model: "gpt-4.1" }),
     ).toBe("default");
   });
 });
+
+describe("isClaudeLeafProvider", () => {
+  test("matches anthropic provider names and claude model ids", () => {
+    expect(isClaudeLeafProvider({ providerName: "anthropic" })).toBe(true);
+    expect(isClaudeLeafProvider({ providerName: "ANTHROPIC" })).toBe(true);
+    expect(
+      isClaudeLeafProvider({
+        providerName: "openai-compat",
+        model: "claude-sonnet-4",
+      }),
+    ).toBe(true);
+  });
+
+  test("rejects grok, gpt, kimi, and muse rows", () => {
+    expect(
+      isClaudeLeafProvider({ providerName: "xai/default", model: "grok-4.5" }),
+    ).toBe(false);
+    expect(
+      isClaudeLeafProvider({ providerName: "openai", model: "gpt-4.1" }),
+    ).toBe(false);
+    expect(
+      isClaudeLeafProvider({ providerName: "codex", model: "gpt-5.1" }),
+    ).toBe(false);
+    expect(
+      isClaudeLeafProvider({ providerName: "moonshot", model: "kimi-k2" }),
+    ).toBe(false);
+    expect(
+      isClaudeLeafProvider({
+        providerName: "opencode-go/abklabs",
+        model: "muse-spark-1.3-contributor",
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("detectModelFamily claude row", () => {
+  test("resolves anthropic/claude to the claude family", () => {
+    expect(
+      detectModelFamily({
+        providerName: "anthropic",
+        model: "claude-sonnet-4",
+      }),
+    ).toBe("claude");
+    expect(
+      detectModelFamily({
+        providerName: "openai-compat",
+        model: "claude-opus-4-6",
+      }),
+    ).toBe("claude");
+  });
+});