Merge pull request #1133 from corbitsdev/cl-8297-0330-add-promptresidual-and-append-grok-tool-budget-once

feat(prompts): promptResidual with grok tool budget, appended once

Author: TheGreatAxios

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

@@ -102,4 +102,33 @@ describe("resolveModelFamilyPolicy", () => {
     expect(muse.toolDisciplineRules).toContain("Never re-read a file");
     expect(base.toolDisciplineRules).toBeUndefined();
   });
+
+  describe("promptResidual (CL-8297)", () => {
+    test("grok leaf carries the generic 4-line tool-budget residual", () => {
+      const leaf = resolveModelFamilyPolicy({
+        providerName: "xai/default",
+        model: "grok-4.6",
+      });
+      expect(leaf.family).toBe("grok");
+      expect(leaf.promptResidual).toBeDefined();
+      if (!leaf.promptResidual)
+        throw new Error("expected promptResidual to be defined");
+      expect(leaf.promptResidual.split("\n")).toHaveLength(4);
+      expect(leaf.promptResidual).toContain("Tool budget:");
+    });
+
+    test("grok orchestrators and default family carry no residual", () => {
+      const orchestrator = resolveModelFamilyPolicy({
+        providerName: "xai/default",
+        model: "grok-4.6",
+        orchestrator: true,
+      });
+      expect(orchestrator.promptResidual).toBeUndefined();
+      const base = resolveModelFamilyPolicy({
+        providerName: "anthropic",
+        model: "claude-sonnet-4",
+      });
+      expect(base.promptResidual).toBeUndefined();
+    });
+  });
 });

src/agent/model-family-policy.ts

@@ -38,6 +38,14 @@ export interface ModelFamilyPolicy {
    * at the tail so it cannot disturb the cached prompt prefix.
    */
   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.
+   */
+  promptResidual?: string | undefined;
 }
 
 const DEFAULT_WRAP_UP_NUDGE_TEXT =
@@ -66,6 +74,16 @@ const DEFAULT_POLICY: Omit<ModelFamilyPolicy, "family"> = {
   advertisedToolDeny: [],
 };
 
+// Generic 4-line tool-budget residual (CL-8297). Grok leaves get this via
+// promptResidual today; other families leave the seam unfilled until their
+// own lanes land. Deliberately free of ceremony lines and family-specific
+// routing — pure tool-loop budget.
+export const GROK_TOOL_BUDGET_RESIDUAL =
+  "Tool budget:\n" +
+  "- Batch independent tool calls into a single turn.\n" +
+  "- Never re-issue a tool call whose result you already have.\n" +
+  "- When the next call would only repeat prior work, write the report instead.";
+
 // A directly observed 14-turn pure-tool-call session for this family
 // previously motivated a tightened nudge/pause pair here (6/10). That pair
 // was miscalibrated: it fired on a session that was making real progress
@@ -83,6 +101,8 @@ const GROK_POLICY: Omit<ModelFamilyPolicy, "family"> = {
   applyGrokFinishBias: true,
   // Leaf value; the resolver clears it for orchestrators below.
   advertisedToolDeny: ["skill_search"],
+  // Leaf value; the resolver clears it for orchestrators below.
+  promptResidual: GROK_TOOL_BUDGET_RESIDUAL,
 };
 
 // Kimi (Moonshot) detection ships now so callers can branch on family, but
@@ -126,6 +146,7 @@ export function resolveModelFamilyPolicy(input: {
         ...policy,
         applyGrokFinishBias: policy.applyGrokFinishBias && !orchestrator,
         advertisedToolDeny: orchestrator ? [] : policy.advertisedToolDeny,
+        promptResidual: orchestrator ? undefined : policy.promptResidual,
       };
     }
     case "kimi":

src/agent/prompt-sizes.test.ts

@@ -332,3 +332,22 @@ describe("skywalker grok prefix (infer envelope vs trimmed director)", () => {
     }
   });
 });
+
+describe("grok tool-budget residual (CL-8297)", () => {
+  const countOccurrences = (haystack: string, needle: string): number =>
+    haystack.split(needle).length - 1;
+
+  test("a grok leaf director prompt contains the tool budget exactly once", () => {
+    const prompt = assembleDirectorPrompt("builder", "grok");
+    expect(countOccurrences(prompt, "Tool budget:")).toBe(1);
+  });
+
+  test("default-family and orchestrator prompts carry no tool budget", () => {
+    expect(assembleDirectorPrompt("builder", "default")).not.toContain(
+      "Tool budget:",
+    );
+    expect(assembleDirectorPrompt("skywalker", "grok")).not.toContain(
+      "Tool budget:",
+    );
+  });
+});

src/agent/prompt-sizes.ts

@@ -17,6 +17,7 @@ import {
   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 {
@@ -35,7 +36,9 @@ import { webSearchDefinition } from "../tools/web-search.js";
  * Assembles each director prompt exactly as src/subagent/run.ts does:
  * extensions=[director systemPromptRole] + environment + tools +
  * appendix, with the Grok finish-bias note gated by
- * shouldApplyGrokAntiThrash (leaves on Grok-family providers only).
+ * shouldApplyGrokAntiThrash (leaves on Grok-family providers only) and the
+ * family promptResidual (CL-8297 tool budget, grok leaves only) 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.
@@ -156,6 +159,7 @@ export function assembleDirectorPrompt(
   const pkg = DIRECTOR_REGISTRY[directorId];
   const orchestrator = pkg.spawn.maySpawn;
   const provider = family === "grok" ? GROK_PROVIDER : DEFAULT_PROVIDER;
+  const policy = resolveModelFamilyPolicy({ ...provider, orchestrator });
   return buildSubAgentSystemPrompt(
     [formatDirectorSystemPrompt(pkg)],
     CANONICAL_PROMPT_ENV,
@@ -164,6 +168,7 @@ export function assembleDirectorPrompt(
       orchestrator,
       toolNames: canonicalToolNamesForDirector(pkg, family),
       grokAntiThrash: shouldApplyGrokAntiThrash({ ...provider, orchestrator }),
+      promptResidual: policy.promptResidual,
     },
   );
 }

src/agent/prompts.test.ts

@@ -370,3 +370,29 @@ describe("grok finish-bias residual gating (extends existing provider-family tes
     expect(prompt.toLowerCase()).not.toContain("kimi");
   });
 });
+
+describe("promptResidual assembly (CL-8297)", () => {
+  const TOOL_BUDGET =
+    "Tool budget:\n" +
+    "- Batch independent tool calls into a single turn.\n" +
+    "- Never re-issue a tool call whose result you already have.\n" +
+    "- When the next call would only repeat prior work, write the report instead.";
+
+  it("appends promptResidual exactly once at the tail for a grok leaf", () => {
+    const prompt = buildSubAgentSystemPrompt(undefined, undefined, undefined, {
+      orchestrator: false,
+      grokAntiThrash: true,
+      promptResidual: TOOL_BUDGET,
+    });
+    expect(countOccurrences(prompt, TOOL_BUDGET)).toBe(1);
+    expect(prompt.trimEnd().endsWith(TOOL_BUDGET)).toBe(true);
+  });
+
+  it("omits the tool budget when promptResidual is unset", () => {
+    const prompt = buildSubAgentSystemPrompt(undefined, undefined, undefined, {
+      orchestrator: false,
+      grokAntiThrash: true,
+    });
+    expect(prompt).not.toContain("Tool budget:");
+  });
+});

src/agent/prompts.ts

@@ -530,6 +530,11 @@ export function buildSubAgentSystemPrompt(
     toolNames?: readonly string[];
     /** When true, append the tiny Grok/xAI finish-bias note (provider residual). */
     grokAntiThrash?: boolean;
+    /**
+     * 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 toolListForPrompt =
@@ -556,5 +561,8 @@ export function buildSubAgentSystemPrompt(
   if (opts.grokAntiThrash === true) {
     sections.push(buildGrokLeafAntiThrashNote());
   }
+  if (opts.promptResidual !== undefined && opts.promptResidual.length > 0) {
+    sections.push(opts.promptResidual);
+  }
   return joinSections(sections);
 }

src/subagent/run.ts

@@ -1055,6 +1055,7 @@ async function runSubAgentInner(
           model: params.provider.model,
           orchestrator: params.orchestrator === true,
         }),
+        promptResidual: modelFamilyPolicy.promptResidual,
       },
     );