fix(agents): keep AGENTS.md tool-dispatch guidance inside small-budget head window

lonexreb · lonexreb · commit 205e83e76350 · 2026-04-30T15:21:00.000-05:00
Codex review on PR #75248 noted that the prior reorder still left `## Tools` starting at char ~1110 in the stripped template, outside the bootstrap trimmer's effective ~1044-char head window at agents.defaults.bootstrapMaxChars=1500 (0.75 head ratio of contentBudget after marker reservation). The injected content kept `Red Lines` and `External vs Internal` but dropped `Tools` along with the tool-dispatch guidance, so the issue's small-model failure mode would persist. Restructure the workspace AGENTS.md template: - Move `## Tools` directly after `## Session Startup` so its body appears in the head window. Add an explicit `Tool dispatch:` rule (emit real structured tool calls, fix args on error rather than repeating). - Condense `## Session Startup` from a multi-list block into a single paragraph, freeing room before `## Tools` without losing semantics. - Split the secondary `Voice Storytelling` and `Platform Formatting` bullets out into a new `## Tool Notes` section lower in the file. They remain available in the full file but no longer crowd the head budget. Section starts (post-frontmatter): First Run @72, Session Startup @220, Tools @555, Red Lines @846, External vs Internal @1021. All four load-bearing sections now sit inside the 1044-char head budget. Add a regression in pi-embedded-helpers.buildbootstrapcontextfiles.test.ts that runs the actual stripped template through buildBootstrapContextFiles with maxChars=1500 and asserts the truncation marker fires and the injected content contains `## Tools`, `Tool dispatch:`, `## Red Lines`, and `## External vs Internal`. This covers the real bootstrap injection path the prior section-order tests did not exercise. Refs #75187
diff --git a/docs/reference/templates/AGENTS.md b/docs/reference/templates/AGENTS.md
@@ -15,19 +15,13 @@ If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out w
 
 ## Session Startup
 
-Use runtime-provided startup context first.
+Use runtime-provided startup context first. It may already include `AGENTS.md`, `SOUL.md`, `USER.md`, recent `memory/YYYY-MM-DD.md` files, and `MEMORY.md` (main session only). Don't reread startup files unless the user asks, the provided context is missing something you need, or you need a deeper follow-up read.
 
-That context may already include:
-
-- `AGENTS.md`, `SOUL.md`, and `USER.md`
-- recent daily memory such as `memory/YYYY-MM-DD.md`
-- `MEMORY.md` when this is the main session
+## Tools
 
-Do not manually reread startup files unless:
+Skills provide your tools. When you need one, read its `SKILL.md`. Keep local notes (cameras, SSH, voice prefs) in `TOOLS.md`.
 
-1. The user explicitly asks
-2. The provided context is missing something you need
-3. You need a deeper follow-up read beyond the provided startup context
+**Tool dispatch:** Emit real structured tool calls — don't describe a tool call in prose. If a tool errors, fix the args; don't repeat the same call.
 
 ## Red Lines
 
@@ -50,18 +44,6 @@ Do not manually reread startup files unless:
 - Anything that leaves the machine
 - Anything you're uncertain about
 
-## Tools
-
-Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
-
-**🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
-
-**📝 Platform Formatting:**
-
-- **Discord/WhatsApp:** No markdown tables! Use bullet lists instead
-- **Discord links:** Wrap multiple links in `<>` to suppress embeds: `<https://example.com>`
-- **WhatsApp:** No headers — use **bold** or CAPS for emphasis
-
 ## Memory
 
 You wake up fresh each session. These files are your continuity:
@@ -137,6 +119,16 @@ Reactions are lightweight social signals. Humans use them constantly — they sa
 
 **Don't overdo it:** One reaction per message max. Pick the one that fits best.
 
+## Tool Notes
+
+**🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
+
+**📝 Platform Formatting:**
+
+- **Discord/WhatsApp:** No markdown tables! Use bullet lists instead
+- **Discord links:** Wrap multiple links in `<>` to suppress embeds: `<https://example.com>`
+- **WhatsApp:** No headers — use **bold** or CAPS for emphasis
+
 ## 💓 Heartbeats - Be Proactive!
 
 When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
diff --git a/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts b/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts
@@ -190,6 +190,34 @@ describe("buildBootstrapContextFiles", () => {
     expect(result[0]?.content.startsWith("[MISSING]")).toBe(true);
   });
 
+  it("preserves load-bearing tool-use guidance from the AGENTS.md template at the small-model bootstrap budget", async () => {
+    // Regression for #75187: at agents.defaults.bootstrapMaxChars=1500 (typical
+    // small/mid-model trim) the trimmer reserves a marker plus tail, so only the
+    // first ~1k characters of the template's head survive. The auto-generated
+    // workspace AGENTS.md must keep tool-dispatch guidance, Red Lines, and
+    // External vs Internal action policy inside that head window so small models
+    // get the rules they need to emit structured tool calls.
+    const templatePath = path.resolve("docs", "reference", "templates", "AGENTS.md");
+    const raw = await fs.readFile(templatePath, "utf-8");
+    const stripped = raw.startsWith("---")
+      ? raw.slice(raw.indexOf("\n---", 3) + "\n---".length).replace(/^\s+/, "")
+      : raw;
+
+    const files = [makeFile({ name: DEFAULT_AGENTS_FILENAME, content: stripped })];
+    const [result] = buildBootstrapContextFiles(files, { maxChars: 1500 });
+
+    expect(result?.content).toBeTruthy();
+    const injected = result?.content ?? "";
+    // Truncation marker proves we're in the small-budget head/tail path the
+    // issue describes, not just returning the file untrimmed.
+    expect(injected).toContain("[...truncated, read AGENTS.md for full content");
+    // The three load-bearing sections must all survive head-truncation.
+    expect(injected).toContain("## Tools");
+    expect(injected).toContain("Tool dispatch:");
+    expect(injected).toContain("## Red Lines");
+    expect(injected).toContain("## External vs Internal");
+  });
+
   it("skips files with missing or invalid paths and emits warnings", () => {
     const malformedMissingPath = {
       name: "SKILL-SECURITY.md",
