Preserve AGENTS.md policy during bootstrap truncation (#82921)

galiniliev · web-flow · commit ad925bd43b1e · 2026-05-19T20:25:27.000-07:00
Fixes #82920
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -281,6 +281,7 @@ Docs: https://docs.openclaw.ai
 - ACP/Codex: honor terminal ACP turn results so failed Codex/acpx runs are not recorded as successful after only progress text. Fixes #79522. Thanks @dudaefj.
 - Telegram: warn when a media group drops photos that fail to download, including albums where every photo is skipped. Fixes #55216. (#82987) Thanks @eldar702.
 - Agents/diagnostics: treat repeated same-handle embedded-run cleanup as idempotent while preserving true replacement-handle mismatch diagnostics. Fixes #82959. (#82960) Thanks @galiniliev.
+- Agents/subagents: preserve high-priority `AGENTS.md` policy in bootstrap context when oversized files are trimmed, and warn agents to read the full policy file before relying on scoped rules. Fixes #82920. (#82921) Thanks @galiniliev.
 - Agents/skills: apply the full effective tool policy pipeline to inline `command-dispatch: tool` skill dispatch before owner-only filtering, preserving configured allow, deny, sandbox, sender, group, and subagent restrictions. (#78525)
 - Codex: avoid spawning native hook relay subprocesses for post-tool/finalize events with no registered hook handlers while preserving pre-tool safety and approval relays. Fixes #76552. (#78004) Thanks @evgyur.
 - Channel accounts: keep top-level default channel accounts visible when named accounts are added alongside default credential material, so mixed legacy/new account configs keep resolving `default` instead of silently dropping it.
diff --git a/src/agents/bootstrap-budget.test.ts b/src/agents/bootstrap-budget.test.ts
@@ -326,6 +326,28 @@ describe("bootstrap prompt warnings", () => {
     expect(lines).toContain("+1 more truncated file(s).");
   });
 
+  it("warns explicitly when AGENTS.md bootstrap policy is truncated", () => {
+    const analysis = analyzeBootstrapBudget({
+      files: [
+        {
+          name: "AGENTS.md",
+          path: "/tmp/AGENTS.md",
+          missing: false,
+          rawChars: 150,
+          injectedChars: 100,
+          truncated: true,
+        },
+      ],
+      bootstrapMaxChars: 120,
+      bootstrapTotalMaxChars: 200,
+    });
+    const lines = formatBootstrapTruncationWarningLines({ analysis });
+
+    expect(lines).toContain(
+      "AGENTS.md was truncated; read the full AGENTS.md before relying on scoped policy.",
+    );
+  });
+
   it("disambiguates duplicate file names in warning lines", () => {
     const analysis = analyzeBootstrapBudget({
       files: [
@@ -390,6 +412,7 @@ describe("bootstrap prompt warnings", () => {
     expect(always.warningShown).toBe(true);
     expect(always.lines).toStrictEqual([
       "AGENTS.md: 150 raw -> 100 injected (~33% removed; max/file).",
+      "AGENTS.md was truncated; read the full AGENTS.md before relying on scoped policy.",
       "If unintentional, raise agents.defaults.bootstrapMaxChars and/or agents.defaults.bootstrapTotalMaxChars.",
     ]);
   });
diff --git a/src/agents/bootstrap-budget.ts b/src/agents/bootstrap-budget.ts
@@ -68,6 +68,10 @@ function formatWarningCause(cause: BootstrapTruncationCause): string {
   return cause === "per-file-limit" ? "max/file" : "max/total";
 }
 
+function isAgentsBootstrapName(name: string): boolean {
+  return name.toLowerCase() === "agents.md";
+}
+
 function normalizeSeenSignatures(signatures?: string[]): string[] {
   if (!Array.isArray(signatures) || signatures.length === 0) {
     return [];
@@ -293,6 +297,9 @@ export function formatBootstrapTruncationWarningLines(params: {
       `+${params.analysis.truncatedFiles.length - topFiles.length} more truncated file(s).`,
     );
   }
+  if (params.analysis.truncatedFiles.some((file) => isAgentsBootstrapName(file.name))) {
+    lines.push("AGENTS.md was truncated; read the full AGENTS.md before relying on scoped policy.");
+  }
   lines.push(
     "If unintentional, raise agents.defaults.bootstrapMaxChars and/or agents.defaults.bootstrapTotalMaxChars.",
   );
diff --git a/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts b/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts
@@ -99,6 +99,26 @@ describe("buildBootstrapContextFiles", () => {
     expect(result?.content).toContain("[...truncated, read HEARTBEAT.md for full content...]");
     expect(result?.content.length).toBeLessThanOrEqual(maxChars);
   });
+  it("keeps policy digest lines from oversized AGENTS.md middle content", () => {
+    const requiredScopedInstruction =
+      "- Required scoped instruction: read scoped AGENTS.md before editing subtree work.";
+    const content = [
+      "# Root policy",
+      "A".repeat(900),
+      "## Scoped policy",
+      requiredScopedInstruction,
+      "B".repeat(700),
+      "tail marker",
+    ].join("\n");
+    const [result] = buildBootstrapContextFiles([makeFile({ content })], {
+      maxChars: 600,
+    });
+
+    expect(result?.content.length).toBeLessThanOrEqual(600);
+    expect(result?.content).toContain("[Policy digest from AGENTS.md]");
+    expect(result?.content).toContain(requiredScopedInstruction);
+    expect(result?.content).toContain("[...truncated, read AGENTS.md for full content...]");
+  });
   it("keeps bootstrap bytes in tiny per-file budgets when the marker is longer than the limit", () => {
     const maxChars = 64;
     const content = `HEAD-${"a".repeat(1_000)}-TAIL`;
diff --git a/src/agents/pi-embedded-helpers/bootstrap.ts b/src/agents/pi-embedded-helpers/bootstrap.ts
@@ -96,6 +96,11 @@ const MIN_BOOTSTRAP_FILE_BUDGET_CHARS = 64;
 const BOOTSTRAP_HEAD_RATIO = 0.75;
 const BOOTSTRAP_TAIL_RATIO = 0.25;
 const MIN_BOOTSTRAP_TRIMMED_CONTENT_CHARS = 16;
+const AGENTS_BOOTSTRAP_FILENAME = "AGENTS.md";
+const AGENTS_POLICY_DIGEST_RATIO = 0.35;
+const AGENTS_POLICY_HEAD_RATIO = 0.45;
+const AGENTS_POLICY_TAIL_RATIO = 0.15;
+const AGENTS_POLICY_DIGEST_MAX_LINE_CHARS = 240;
 
 type TrimBootstrapResult = {
   content: string;
@@ -104,6 +109,11 @@ type TrimBootstrapResult = {
   originalLength: number;
 };
 
+type PolicyDigest = {
+  text: string;
+  omittedLines: number;
+};
+
 export function resolveBootstrapMaxChars(cfg?: OpenClawConfig, agentId?: string | null): number {
   const raw =
     cfg && agentId
@@ -141,6 +151,120 @@ export function resolveBootstrapPromptTruncationWarningMode(
   return DEFAULT_BOOTSTRAP_PROMPT_TRUNCATION_WARNING_MODE;
 }
 
+function isAgentsBootstrapFile(fileName: string): boolean {
+  return fileName.toLowerCase() === AGENTS_BOOTSTRAP_FILENAME.toLowerCase();
+}
+
+function isPolicyDigestCandidate(line: string): boolean {
+  if (/^(?:#{1,6}|\s*[-*+]|\s*\d+[.)])\s+\S/u.test(line)) {
+    return true;
+  }
+  return /\b(?:AGENTS\.md|scoped|required|must|never|do not|before subtree|read scoped|owner|security|secret|credential|test|validation|command|commit|push|github|pr)\b/iu.test(
+    line,
+  );
+}
+
+function normalizePolicyDigestLine(line: string): string {
+  const normalized = line.trim().replace(/\s+/gu, " ");
+  if (normalized.length <= AGENTS_POLICY_DIGEST_MAX_LINE_CHARS) {
+    return normalized;
+  }
+  return `${truncateUtf16Safe(normalized, AGENTS_POLICY_DIGEST_MAX_LINE_CHARS - 1)}…`;
+}
+
+function buildAgentsPolicyDigest(content: string, budget: number): PolicyDigest {
+  if (budget <= 0) {
+    return { text: "", omittedLines: 0 };
+  }
+
+  const candidates = content
+    .split(/\r?\n/u)
+    .map((line, index) => ({ index, line: normalizePolicyDigestLine(line) }))
+    .filter(({ line }) => line.length > 0 && isPolicyDigestCandidate(line));
+  const highPriorityPattern =
+    /\b(?:AGENTS\.md|scoped|required|must|never|do not|before subtree|read scoped|security|secret|credential)\b/iu;
+  const selected = new Set<number>();
+  let used = 0;
+  const trySelect = (candidate: { index: number; line: string }) => {
+    const separatorChars = selected.size > 0 ? 1 : 0;
+    if (used + separatorChars + candidate.line.length > budget) {
+      return;
+    }
+    selected.add(candidate.index);
+    used += separatorChars + candidate.line.length;
+  };
+
+  for (const candidate of candidates) {
+    if (highPriorityPattern.test(candidate.line)) {
+      trySelect(candidate);
+    }
+  }
+  for (const candidate of candidates) {
+    if (!selected.has(candidate.index)) {
+      trySelect(candidate);
+    }
+  }
+
+  const lines = candidates
+    .filter((candidate) => selected.has(candidate.index))
+    .toSorted((a, b) => a.index - b.index)
+    .map((candidate) => candidate.line);
+  return {
+    text: lines.join("\n"),
+    omittedLines: Math.max(0, candidates.length - lines.length),
+  };
+}
+
+function trimAgentsBootstrapContent(content: string, maxChars: number): TrimBootstrapResult {
+  const trimmed = content.trimEnd();
+  if (trimmed.length <= maxChars) {
+    return {
+      content: trimmed,
+      truncated: false,
+      maxChars,
+      originalLength: trimmed.length,
+    };
+  }
+
+  let headChars = Math.floor(maxChars * AGENTS_POLICY_HEAD_RATIO);
+  let tailChars = Math.floor(maxChars * AGENTS_POLICY_TAIL_RATIO);
+  let digestBudget = Math.floor(maxChars * AGENTS_POLICY_DIGEST_RATIO);
+  let digest = buildAgentsPolicyDigest(trimmed, digestBudget);
+  const render = () =>
+    [
+      trimmed.slice(0, headChars),
+      `[...truncated, read ${AGENTS_BOOTSTRAP_FILENAME} for full content...]`,
+      digest.text ? "[Policy digest from AGENTS.md]" : "",
+      digest.text,
+      digest.omittedLines > 0 ? `[...${digest.omittedLines} more policy lines omitted...]` : "",
+      `…(truncated ${AGENTS_BOOTSTRAP_FILENAME}: kept ${headChars}+policy ${digest.text.length}+${tailChars} chars of ${trimmed.length})…`,
+      tailChars > 0 ? trimmed.slice(-tailChars) : "",
+    ]
+      .filter((part) => part.length > 0)
+      .join("\n");
+
+  let rendered = render();
+  while (rendered.length > maxChars && (tailChars > 0 || headChars > 1 || digestBudget > 0)) {
+    const overflow = rendered.length - maxChars;
+    if (tailChars > 0) {
+      tailChars = Math.max(0, tailChars - overflow);
+    } else if (headChars > 1) {
+      headChars = Math.max(1, headChars - overflow);
+    } else {
+      digestBudget = Math.max(0, digestBudget - overflow);
+      digest = buildAgentsPolicyDigest(trimmed, digestBudget);
+    }
+    rendered = render();
+  }
+
+  return {
+    content: rendered.length > maxChars ? truncateUtf16Safe(rendered, maxChars) : rendered,
+    truncated: true,
+    maxChars,
+    originalLength: trimmed.length,
+  };
+}
+
 function trimBootstrapContent(
   content: string,
   fileName: string,
@@ -155,6 +279,9 @@ function trimBootstrapContent(
       originalLength: trimmed.length,
     };
   }
+  if (isAgentsBootstrapFile(fileName)) {
+    return trimAgentsBootstrapContent(content, maxChars);
+  }
 
   const markerTemplate = (headChars: number, tailChars: number) =>
     [
