docs(prompts): keep AGENTS.md and core schemas on grok prefixes

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -348,6 +348,8 @@ The primary session identity is **Skywalker** (`buildChatRole` → `createSkywal
 
 **Overrides.** `loadSystemPromptOverrides` (`src/agent/context-extensions.ts`) resolves a project `SYSTEM.md` (repo root, then `.corbits/`) that **replaces** the static base block, and an `APPEND_SYSTEM.md` that is **appended** as an extension. These compose with `config.systemPromptExtensions` (profile config) and the auto-discovered `AGENTS.md`, all of which attach as appended sections after the base.
 
+**Grok prefix.** The provider cache prefix is the advertised tools array plus the system prompt. Grok does **not** get a trimmed fork of that prefix. `AGENTS.md` (capped at 32 KiB, framed as reference) and the full CORE+CATALOG schemas stay on every Grok primary prefix, same as every other family. Family residuals are additive lines only (`buildGrokLeafAntiThrashNote` on leaves); stripping project guidance or core schemas for Grok would be a prompt fork and would force `tool_search` round-trips — the thrash Grok is already sensitive to. The cheaper split already exists: workers use `buildSubAgentSystemPrompt` (trimmed director prompt, no `AGENTS.md`, mounted-tool schemas only). Skywalker's infer envelope is the primary chat prompt, not a spawned skywalker package. Prefix bytes are measured in `src/agent/prompt-sizes.ts` (`assembleSkywalkerInferEnvelope` vs `assembleDirectorPrompt("skywalker")`). `present` stays off the advertised prefix on every family.
+
 ### State Persistence (`src/session/state.ts`)
 
 - `RunState` — `running` | `done` | `failed`, turns used, task, timestamps, error

docs/IMPLEMENTATION.md

@@ -163,6 +163,8 @@ Twenty packages under `src/agent/directors/<id>/` register in `DIRECTOR_REGISTRY
 4. `directorProfiles()` is the spawn catalog (`default-agents.ts`) — closed set minus skywalker. Plugin and local `.agents/agents/` profiles still load, but closed `DIRECTOR_IDS` cannot be overridden or aliased.
 5. Primary chat role is Skywalker: `buildChatRole()` → `createSkywalkerSystemPrompt()`. Product mutation tools (`write_file` / `edit_file` / `delete_file`) live in CORE (and `SKYWALKER_TOOLS`) so they are advertised on the primary without a `tool_search` round-trip. DIY tiny/bounded edits on the parent; spawn builder/docs directors for substantial work — a prompt judgment call, not a toolset strip. `PRIMARY_DENIED_PRODUCT_TOOLS` is gone. Shell file-writes stay denied; MCP tools are not re-filtered by a product-write deny list. There is no static per-profile write-path lock (CL-6952).
 
+   **Grok infer envelope.** `loadSessionChatPrompt` always appends `loadAgentContextExtensions` (`AGENTS.md`, capped at `MAX_AGENTS_MD_BYTES`) and advertises CORE+CATALOG full schemas via `advertisedToolNamesForSessionMode`. That assembly is family-agnostic — Grok does not substitute the trimmed director prompt (`buildSubAgentSystemPrompt` + `formatDirectorSystemPrompt`). Workers already use that trimmed path (no `AGENTS.md`, mounted-tool schemas only). Keep the infer envelope on Grok; do not strip `AGENTS.md` or core schemas. Measure in `src/agent/prompt-sizes.ts` (`assembleSkywalkerInferEnvelope` vs `assembleDirectorPrompt("skywalker")`).
+
    **Codex tool proxies.** When the active provider is Codex (`isCodexProviderName`), `createAgentToolset` and `runSubAgent` mount `apply_patch`, `shell`, and `update_plan` stringTools from `createCodexToolProxies`, all forwarding through the same posix `ToolRunner` seam (`runTool`) so permission plugins still apply. `apply_patch` parses the Codex envelope and forwards each op (`write_file` / `delete_file` / `read_file`). `shell` — the native Codex name is `shell`, not `exec_command` — normalizes Codex's `command` (string or `["bash","-lc",script]`-style argv array), `workdir`, and `timeout_ms` onto `run_shell`'s `{command, cwd?, timeout?}` and is gated by `allowShellFromCapabilities` (mirrors `allowDeleteFromCapabilities` against `run_shell`). `update_plan` maps Codex's `plan: [{step, status}]` onto `manage_tasks(action: "create")`; `pending`/`in_progress`/`completed` map to `todo`/`doing`/`done` — `manage_tasks`'s `cancelled` status has no Codex equivalent and is never produced by this proxy. Primary strips `apply_patch` after mount (Corbits DIY stays on `write_file` / `edit_file` / `delete_file`); `shell` and `update_plan` stay on primary (same classification as `run_shell` / `manage_tasks`). Build and docs worker allowlists (`BUILD_TOOLS` / `DOCS_TOOLS`) include `apply_patch` so Codex workers keep the proxy after the capability filter. `CORE_TOOL_NAMES` does not list it.
 
 6. There is no static write-path declaration on packages or profiles (CL-6952 removed it — no shipped director ever set one). Instead, `agent-fleet.ts` tracks each running dispatch by cwd; a new mutating dispatch that lands on the same cwd as a live mutating peer (`pending_init`/`running`, and not a declared read-only `modelRole` of `explore`/`plan`/`review`/`test`) records at most one `concurrent-lane-overlap` entry per cwd wave in `intervention-log.ts` (class `conflict`). The wave flag clears when no live mutating writer remains for that cwd. Terminal-but-unsettled lanes (for example cancelled with `finishedAt` set while the run promise has not reached `finally`) are pruned from the map and do not warn. This is advisory only — it never blocks the spawn, since cwd overlap does not prove the two lanes touch the same files.

src/agent/context-extensions.ts

@@ -1,6 +1,19 @@
 import { join } from "node:path";
 import { SETTINGS_DIR_NAME } from "../branding.js";
 
+// Cap so a huge AGENTS.md cannot blow the provider cache prefix.
+export const MAX_AGENTS_MD_BYTES = 32_000;
+
+export function formatAgentsMdExtension(content: string): string {
+  return (
+    `## Project guidance (AGENTS.md, reference)\n\n` +
+    `The following is the repository's AGENTS.md, provided as background about the project. ` +
+    `Do not execute its agent-onboarding or session-initialization steps (loading skills, reading skill files) — ` +
+    `they target other tools and those files may not exist in this repo. Use it as reference when it helps the task.\n\n` +
+    content.slice(0, MAX_AGENTS_MD_BYTES)
+  );
+}
+
 export async function loadAgentContextExtensions(
   cwd: string,
 ): Promise<string[]> {
@@ -9,19 +22,12 @@ export async function loadAgentContextExtensions(
   try {
     const content = await Bun.file(agentsMdPath).text();
     if (content.trim().length > 0) {
-      const MAX_AGENTS_MD_BYTES = 32_000;
       if (content.length > MAX_AGENTS_MD_BYTES) {
         process.stderr.write(
           `[interchange] Warning: AGENTS.md exceeds ${MAX_AGENTS_MD_BYTES} bytes and will be truncated.\n`,
         );
       }
-      extensions.push(
-        `## Project guidance (AGENTS.md, reference)\n\n` +
-          `The following is the repository's AGENTS.md, provided as background about the project. ` +
-          `Do not execute its agent-onboarding or session-initialization steps (loading skills, reading skill files) — ` +
-          `they target other tools and those files may not exist in this repo. Use it as reference when it helps the task.\n\n` +
-          content.slice(0, MAX_AGENTS_MD_BYTES),
-      );
+      extensions.push(formatAgentsMdExtension(content));
     }
   } catch (err: unknown) {
     if ((err as NodeJS.ErrnoException).code !== "ENOENT") {

src/agent/prompt-sizes.test.ts

@@ -5,8 +5,13 @@ import {
   canonicalToolNamesForDirector,
   directorPromptSizeTable,
   formatPromptSizeTable,
+  formatSkywalkerPrefixTable,
+  assembleSkywalkerInferEnvelope,
+  measureSkywalkerPrefix,
   type PromptSizeFamily,
 } from "./prompt-sizes.js";
+import { CORE_TOOL_NAMES } from "./tool-search.js";
+import { MAX_AGENTS_MD_BYTES } from "./context-extensions.js";
 
 /**
  * Prompt size budget (CL-7664). Numeric asserts only — copy edits must not
@@ -208,3 +213,40 @@ describe("director prompt size budget", () => {
     }
   });
 });
+
+describe("skywalker grok prefix (infer envelope vs trimmed director)", () => {
+  test("keeps AGENTS.md and core tools on the infer envelope", () => {
+    const prompt = assembleSkywalkerInferEnvelope();
+    expect(prompt).toContain("## Project guidance (AGENTS.md, reference)");
+    expect(prompt).toContain("Follow the repository conventions.");
+    for (const name of CORE_TOOL_NAMES) {
+      if (name === "wait_agents") continue;
+      expect(prompt, name).toContain(`- ${name}:`);
+    }
+  });
+
+  test("does not substitute the trimmed director prompt on grok", () => {
+    const size = measureSkywalkerPrefix();
+    expect(size.agentsMdCap).toBe(MAX_AGENTS_MD_BYTES);
+    expect(size.inferEnvelopeChars).toBeGreaterThan(5000);
+    expect(size.trimmedDirectorChars).toBeGreaterThan(5000);
+    expect(size.inferEnvelopeBytes).toBeGreaterThanOrEqual(
+      size.inferEnvelopeChars,
+    );
+    expect(size.inferEnvelopeChars).not.toBe(size.trimmedDirectorChars);
+    const infer = assembleSkywalkerInferEnvelope();
+    expect(infer).not.toContain("Finish bias (xAI / Grok worker):");
+  });
+
+  test("formatSkywalkerPrefixTable reports both prefixes and the AGENTS.md cap", () => {
+    const size = measureSkywalkerPrefix();
+    const table = formatSkywalkerPrefixTable(size);
+    expect(table).toContain(
+      `| skywalker infer envelope (canonical AGENTS.md) | ${size.inferEnvelopeChars} (${size.inferEnvelopeBytes}) |`,
+    );
+    expect(table).toContain(
+      `| skywalker trimmed director (grok) | ${size.trimmedDirectorChars} (${size.trimmedDirectorBytes}) |`,
+    );
+    expect(table).toContain(`| live AGENTS.md cap | ${size.agentsMdCap} |`);
+  });
+});

src/agent/prompt-sizes.ts

@@ -11,7 +11,11 @@ import {
   type DirectorId,
   type DirectorPackage,
 } from "./directors/types.js";
-import { buildSubAgentSystemPrompt } from "./prompts.js";
+import { buildChatSystemPrompt, buildSubAgentSystemPrompt } from "./prompts.js";
+import {
+  formatAgentsMdExtension,
+  MAX_AGENTS_MD_BYTES,
+} from "./context-extensions.js";
 import { shouldApplyGrokAntiThrash } from "../subagent/provider-family.js";
 import { isCodexProviderName } from "../config/codex-providers.js";
 import { shellCollectDefinition } from "./background-shell-tool.js";
@@ -57,6 +61,14 @@ const DEFAULT_PROVIDER = {
 /** Families in the size table: default assembly vs Grok (+finish-bias note). */
 export type PromptSizeFamily = "default" | "grok";
 
+/**
+ * Pinned AGENTS.md body for prefix measurement. Production reads the live
+ * file (capped at MAX_AGENTS_MD_BYTES); the fixture pins a short body so
+ * sizes move only when framing or assembly changes, not when the checkout's
+ * AGENTS.md is edited.
+ */
+export const CANONICAL_AGENTS_MD = "Follow the repository conventions.\n";
+
 /**
  * Pre-filter mount names in run.ts install order: posix base (TOOL_NAMES,
  * shared with createPosixTools) + delete_file / lsp plugin tools
@@ -156,6 +168,19 @@ export function assembleDirectorPrompt(
   );
 }
 
+/**
+ * Skywalker primary infer envelope: the chat system prompt plus the
+ * AGENTS.md extension. Family-agnostic — Grok does not substitute the
+ * trimmed director prompt. Live AGENTS.md is capped at MAX_AGENTS_MD_BYTES;
+ * the fixture uses CANONICAL_AGENTS_MD so the number is checkout-stable.
+ */
+export function assembleSkywalkerInferEnvelope(): string {
+  return buildChatSystemPrompt(
+    [formatAgentsMdExtension(CANONICAL_AGENTS_MD)],
+    CANONICAL_PROMPT_ENV,
+  );
+}
+
 export interface DirectorPromptSize {
   directorId: DirectorId;
   family: PromptSizeFamily;
@@ -176,6 +201,26 @@ export function measureDirectorPrompt(
   };
 }
 
+export interface SkywalkerPrefixSize {
+  inferEnvelopeChars: number;
+  inferEnvelopeBytes: number;
+  trimmedDirectorChars: number;
+  trimmedDirectorBytes: number;
+  agentsMdCap: number;
+}
+
+export function measureSkywalkerPrefix(): SkywalkerPrefixSize {
+  const infer = assembleSkywalkerInferEnvelope();
+  const trimmed = assembleDirectorPrompt("skywalker", "grok");
+  return {
+    inferEnvelopeChars: infer.length,
+    inferEnvelopeBytes: Buffer.byteLength(infer, "utf8"),
+    trimmedDirectorChars: trimmed.length,
+    trimmedDirectorBytes: Buffer.byteLength(trimmed, "utf8"),
+    agentsMdCap: MAX_AGENTS_MD_BYTES,
+  };
+}
+
 /** Full per-director x per-family size table. */
 export function directorPromptSizeTable(): DirectorPromptSize[] {
   const rows: DirectorPromptSize[] = [];
@@ -206,3 +251,13 @@ export function formatPromptSizeTable(rows: DirectorPromptSize[]): string {
   }
   return lines.join("\n");
 }
+
+export function formatSkywalkerPrefixTable(size: SkywalkerPrefixSize): string {
+  return [
+    "| prefix | chars (bytes) |",
+    "| --- | --- |",
+    `| skywalker infer envelope (canonical AGENTS.md) | ${size.inferEnvelopeChars} (${size.inferEnvelopeBytes}) |`,
+    `| skywalker trimmed director (grok) | ${size.trimmedDirectorChars} (${size.trimmedDirectorBytes}) |`,
+    `| live AGENTS.md cap | ${size.agentsMdCap} |`,
+  ].join("\n");
+}

tests/unit/agent-context-extensions.test.ts

@@ -2,7 +2,10 @@ import { test, expect, beforeEach, afterEach } from "bun:test";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { loadAgentContextExtensions } from "../../src/agent/context-extensions.js";
+import {
+  loadAgentContextExtensions,
+  MAX_AGENTS_MD_BYTES,
+} from "../../src/agent/context-extensions.js";
 import { defined } from "../helpers/defined.js";
 
 let dir: string;
@@ -31,14 +34,13 @@ test("AGENTS.md absent returns empty array without throwing", async () => {
   expect(result).toHaveLength(0);
 });
 
-test("AGENTS.md exceeds 32000 bytes is truncated to 32000 bytes", async () => {
-  const MAX = 32_000;
-  const content = "x".repeat(MAX + 500);
+test("AGENTS.md exceeds MAX_AGENTS_MD_BYTES is truncated", async () => {
+  const content = "x".repeat(MAX_AGENTS_MD_BYTES + 500);
   await writeFile(join(dir, "AGENTS.md"), content);
   const result = await loadAgentContextExtensions(dir);
   expect(result).toHaveLength(1);
-  expect(result[0]).toContain("x".repeat(MAX));
-  expect(result[0]).not.toContain("x".repeat(MAX + 1));
+  expect(result[0]).toContain("x".repeat(MAX_AGENTS_MD_BYTES));
+  expect(result[0]).not.toContain("x".repeat(MAX_AGENTS_MD_BYTES + 1));
 });
 
 test("AGENTS.md empty (whitespace only) returns empty array", async () => {