fix(agent): single-source grok residual, drop duplicate promptResidual seam

Author: TheGreatAxios

src/agent/grok-residual.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect, it } from "bun:test";
-import { promptResidual } from "./model-family-policy.js";
+import { GROK_PROMPT_RESIDUAL } from "./model-family-policy.js";
 import {
   buildGrokLeafAntiThrashNote,
   buildSubAgentSystemPrompt,
 } from "./prompts.js";
+import { shouldApplyGrokAntiThrash } from "../subagent/provider-family.js";
 
 // The three Grok ceremony lines (CL-7768 Design, merged by CL-8296): no git,
 // no pre-plan, verify once.
@@ -19,28 +20,47 @@ function countOccurrences(haystack: string, needle: string): number {
 
 describe("grok ceremony merge (CL-8296)", () => {
   it("exposes a single grok residual with each ceremony line exactly once", () => {
-    const residual = promptResidual("grok");
-    expect(residual).toContain("Finish bias (xAI / Grok worker):");
+    expect(GROK_PROMPT_RESIDUAL).toContain("Finish bias (xAI / Grok worker):");
     for (const line of CEREMONY_LINES) {
-      expect(countOccurrences(residual, line)).toBe(1);
+      expect(countOccurrences(GROK_PROMPT_RESIDUAL, line)).toBe(1);
     }
   });
 
   it("keeps the don't re-read line exactly once — no duplicate", () => {
-    const residual = promptResidual("grok");
-    expect(countOccurrences(residual, "re-open paths you already read")).toBe(
-      1,
-    );
+    expect(
+      countOccurrences(GROK_PROMPT_RESIDUAL, "re-open paths you already read"),
+    ).toBe(1);
   });
 
-  it("is grok-only: every other family resolves to an empty residual", () => {
-    expect(promptResidual("default")).toBe("");
-    expect(promptResidual("kimi")).toBe("");
-    expect(promptResidual("muse")).toBe("");
+  it("is grok-only: the finish-bias gate fires for grok leaves alone", () => {
+    expect(
+      shouldApplyGrokAntiThrash({
+        providerName: "xai/default",
+        model: "grok-4.6",
+        orchestrator: false,
+      }),
+    ).toBe(true);
+    for (const input of [
+      { providerName: "anthropic", model: "claude-sonnet-4" },
+      { providerName: "moonshot", model: "kimi-k2" },
+      { providerName: "opencode-go", model: "muse-spark-1.3-contributor" },
+      { providerName: "openai", model: "gpt-4.1" },
+    ] as const) {
+      expect(shouldApplyGrokAntiThrash({ ...input, orchestrator: false })).toBe(
+        false,
+      );
+    }
+    expect(
+      shouldApplyGrokAntiThrash({
+        providerName: "xai/default",
+        model: "grok-4.6",
+        orchestrator: true,
+      }),
+    ).toBe(false);
   });
 
   it("buildGrokLeafAntiThrashNote is the same single residual (one source of truth)", () => {
-    expect(buildGrokLeafAntiThrashNote()).toBe(promptResidual("grok"));
+    expect(buildGrokLeafAntiThrashNote()).toBe(GROK_PROMPT_RESIDUAL);
   });
 
   it("the assembled grok worker prompt carries the merged residual exactly once", () => {

src/agent/model-family-policy.ts

@@ -129,15 +129,17 @@ const MUSE_POLICY: Omit<ModelFamilyPolicy, "family"> = {
   toolDisciplineRules: MUSE_TOOL_DISCIPLINE_RULES,
 };
 
-// Single grok prompt residual (CL-8296): the finish-bias bullets plus the
-// three ceremony lines from the CL-7768 design (no git, no pre-plan, verify
-// once), merged into one block with no line twice. The don't re-read idea
-// appears exactly once (the "re-open paths" bullet) — it is not repeated.
-// Grok-only: detectModelFamily has no glm family, so per the <30min rule no
-// GLM row ships here. The text lives here once; buildGrokLeafAntiThrashNote
-// (prompts.ts) returns it verbatim, so the prompt carries exactly one grok
-// residual and the sibling CL-8297 hook resolves to the same block.
-const GROK_PROMPT_RESIDUAL = [
+// Single grok finish-bias + ceremony residual (CL-8296): the finish-bias
+// bullets plus the three ceremony lines from the CL-7768 design (no git, no
+// pre-plan, verify once), merged into one block with no line twice. The don't
+// re-read idea appears exactly once (the "re-open paths" bullet) — it is not
+// repeated. Grok-only: detectModelFamily has no glm family, so per the <30min
+// rule no GLM row ships here. The text lives here once; exported for
+// buildGrokLeafAntiThrashNote (prompts.ts), which returns it verbatim, so the
+// prompt carries exactly one copy. This is a different block from the CL-8297
+// tool-budget hook (GROK_TOOL_BUDGET_RESIDUAL, surfaced via the
+// ModelFamilyPolicy.promptResidual field): grok leaves carry both, each once.
+export const GROK_PROMPT_RESIDUAL = [
   "Finish bias (xAI / Grok worker):",
   "- Once you can answer the dispatch brief, prefer the structured report over another speculative tool call.",
   "- If the next call would only re-open paths you already read, write the report instead.",
@@ -148,15 +150,6 @@ const GROK_PROMPT_RESIDUAL = [
   "- Verify with the test command once at the end, not after every edit.",
 ].join("\n");
 
-/**
- * Minimal per-family prompt residual hook. The sibling CL-8297 owns the
- * canonical hook; this local copy keeps the branch self-contained so tests
- * pass standalone — the two reconcile when CL-8297 lands.
- */
-export function promptResidual(family: ModelFamily): string {
-  return family === "grok" ? GROK_PROMPT_RESIDUAL : "";
-}
-
 export function resolveModelFamilyPolicy(input: {
   providerName: string;
   model?: string;

src/agent/prompts.ts

@@ -11,7 +11,7 @@ import {
   buildWorkerContract,
   buildWorkerToolNames,
 } from "./worker-contract.js";
-import { promptResidual } from "./model-family-policy.js";
+import { 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:
@@ -512,12 +512,12 @@ export function buildSubAgentReportContract(
 // Tiny residual for Grok/xAI workers: mining showed higher tools-only thrash
 // than Codex on the same harness. Shared thrash harness + spawn contracts do
 // the structural work; this is only a finish-bias nudge, not a full rewrite.
-// Single source of truth is the promptResidual("grok") block in
+// Single source of truth is the GROK_PROMPT_RESIDUAL block in
 // model-family-policy.ts (CL-8296 merged the three ceremony lines into it);
-// this composes that block verbatim so the prompt carries one grok residual
+// this returns that block verbatim so the prompt carries one grok residual
 // with no line twice.
 export function buildGrokLeafAntiThrashNote(): string {
-  return promptResidual("grok");
+  return GROK_PROMPT_RESIDUAL;
 }
 
 export function buildSubAgentSystemPrompt(