pi-condense 2.0.1 → 2.1.1

package/CHANGELOG.md

@@ -9,6 +9,14 @@ publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
 ## [Unreleased]
 
+## [2.1.1] - 2026-07-04
+
+- **`release.yml` posts GitHub Release notes.** A new `release-notes` job (`needs: publish`, `contents: write`) extracts the CHANGELOG section matching the pushed tag with `awk` (skipping `## [Unreleased]`) and publishes it as the GitHub Release body via `gh release create` (falling back to `gh release edit`). No LLM or API key; only `github.token`.
+
+## [2.1.0] - 2026-07-04
+
+- **Per-bullet recovery refs in prune summaries** (closes #2). Each per-tool block in a summary now carries its own inline `` `tN` `` ref, so the model recovers a specific tool's raw output in one hop instead of guessing which flat-footer ref maps to which bullet. The serializer labels each tool block `[[N:toolname]]` (`src/batch-capture.ts`), the summarizer prompt tells the model to copy that label onto its first bullet (`src/summarizer.ts`), and `substituteInlineRefs` (`src/summary-refs.ts`) validates the echoed tool name against the tool at position N before rewriting to `` `tN` ``. The flat footer is retained unchanged as the always-correct fallback. Deterministic number->shortId map over the shared post-dedup `batch.toolCalls` order; the tool-name tag downgrades a confident wrong-ref (skip-induced renumber) to footer-only, and mismatched / out-of-range / wrapped / mid-line labels are stripped (fence-aware leak guard) so no raw `[[N:name]]` token ever leaks into context. No new tool, config key, or index.
+
 ## [2.0.1] - 2026-07-03
 
 - **Prune summaries are now hidden from Pi's main window** (`display: false` at both injection sites in `index.ts`). They stay in LLM context and session history (recoverable via `context_tree_query`) but no longer print the full markdown block into the TUI. Mirrors upstream `pi-context-prune` `2fd6127`.

package/PRUNING.md

@@ -181,7 +181,7 @@ graph TB
 **Key points:**
 
 - The `AssistantMessage` tool-call blocks are **kept** (they carry the `toolCallId`s the model uses to reference originals via `context_tree_query`).
-- `ToolResultMessage` entries for summarized tool calls are **replaced with a small stub** (`[Summarized in pruner summary, ref \`tN\`. Use context_tree_query to retrieve full output.]`) carrying `role: "toolResult"`, the original `toolCallId`/`toolName`/`timestamp`, and `isError: false`. The stub preserves role alternation, so pi-ai's `transformMessages.insertSyntheticToolResults` no longer injects a synthetic `{ isError: true, "No result provided" }` for the (no-longer-)orphaned tool call. See [Stub-replace instead of delete](#stub-replace-instead-of-delete).
+- `ToolResultMessage` entries for summarized tool calls are **replaced with a small stub** (`[Summarized in pruner summary, ref \`tN\`. Use context_tree_query to retrieve full output.]`) carrying`role: "toolResult"`, the original`toolCallId`/`toolName`/`timestamp`, and`isError: false`. The stub preserves role alternation, so pi-ai's`transformMessages.insertSyntheticToolResults` no longer injects a synthetic `{ isError: true, "No result provided" }` for the (no-longer-)orphaned tool call. See [Stub-replace instead of delete](#stub-replace-instead-of-delete).
 - Every pruned tool call is also copied into the pruner's runtime/session index with its `toolCallId`, tool name, args, status, turn index, timestamp, and full `resultText`.
 - A summary message is injected as a `"steer"` (`pi.sendMessage` runtime path) or appended directly via `sessionManager.appendCustomMessageEntry` (session path, used when Pi may already be shutting down). Both deliver before the next LLM call.
 - The session JSONL file retains the original tool-result entries unchanged — pruning only affects what the *next* request sees in active context.
@@ -210,6 +210,7 @@ That distinction is the core idea:
 ├─────────────────────────────────────────────────────────────────────────┤
 │                                                                         │
 │  [summary]  ... build failed: circular dependency ...                   │
+│             - `t1` read config.ts -> 3 exports                          │
 │             Summarized tool refs: `t1`                                  │
 │             Use `context_tree_query` with these refs                    │
 │                                                                         │
@@ -286,7 +287,7 @@ So after pruning, the model is working with a **two-layer memory**:
 The intended recovery flow is:
 
 1. The model reads a summary message.
-2. The summary lists the short refs (`t1`, `t2`, …) that were summarized.
+2. The summary lists the short refs (`t1`, `t2`, …) that were summarized. Each per-tool bullet also carries its own inline `` `tN` `` ref (copied from a `[[N:toolname]]` label the summarizer emits, validated against the tool at that position), so the model can jump from a bullet straight to its ref; the flat footer still lists every ref as a fallback.
 3. The model decides the summary is not enough and wants exact raw output.
 4. The model calls `context_tree_query({ toolCallIds: ["t1", ...] })`. The tool accepts short refs and full `toolCallId`s interchangeably (`indexer.resolveToolCallId`).
 5. The tool looks up those IDs in the pruner index.
@@ -598,6 +599,7 @@ The pruner now keeps the toolResult message but replaces its content with a smal
 ```
 
 Properties:
+
 - `role: "toolResult"` and the original `toolCallId` / `toolName` / `timestamp` are preserved — role alternation is intact; no synthetic-result injection.
 - `isError: false`, so the model does not interpret the stub as a tool failure.
 - The stub references the **short ref** (`t1`, `t2`, …) the indexer assigned at summary time. Legacy entries from before short-refs landed fall back to the raw `toolCallId`.
@@ -652,6 +654,7 @@ Set `minBatchChars: 0` to disable. The default `1000` skips obvious trivial batc
 `dedupByContentHash: boolean` (default `true`) catches re-reads of already-pruned tool outputs at zero LLM cost.
 
 Mechanism:
+
 1. When a batch enters `flushPending`, each tool call is hashed by `SHA-1(toolName + "\0" + normalize(resultText))`.
 2. The indexer's `contentHashToOriginal` map (populated by every earlier `addBatch` / `reconstructFromSession`) is consulted.
 3. A hit means an earlier prune already covered identical content. The duplicate is registered as an alias of the original via `indexer.registerDuplicate(newId, originalId, appendEntry)`:
@@ -702,12 +705,14 @@ Summarizing tool-call history is not just a hack — it is an active research ar
 SUPO integrates summarization directly into the RL training pipeline for tool-using agents. Instead of treating context compression as an afterthought, the policy gradient is derived to optimize **both** tool-use behavior **and** summarization strategy end-to-end.
 
 **Method:**
+
 - Periodically compresses tool-using history via LLM-generated summaries
 - Retains task-relevant information in compact form
 - Derives a policy gradient that lets standard LLM RL infrastructure optimize both behaviors simultaneously
 - Enables training beyond fixed context limits
 
 **Key results:**
+
 - Significantly improved success rate on interactive function calling and search tasks
 - **Same or lower working context length** compared to baselines that don't summarize
 - Test-time scaling: increasing the maximum summarization rounds during evaluation further improves performance
@@ -726,12 +731,14 @@ SUPO proves that summarization is not just about saving tokens — it actively *
 ReSum addresses the fundamental conflict between **exploration** (needing many tool calls) and **context limits** (fixed window size). Current agents append every thought/action/observation to history until they crash into the context ceiling.
 
 **Method:**
+
 - Periodically invokes an external **summary tool** to condense interaction history
 - The agent restarts reasoning from the compressed summary
 - Introduces **ReSum-GRPO**: adapts Group Relative Policy Optimization with **advantage broadcasting** — propagates final trajectory rewards across all segments so early exploration steps get proper credit
 - Trained a specialized **ReSumTool-30B** to extract key evidence and propose next steps
 
 **Key results:**
+
 - **4.5% improvement** over ReAct in training-free settings
 - **Further 8.2% gain** with ReSum-GRPO training
 - A 30B ReSum-enhanced agent with only 1K training samples achieves competitive performance with leading open-source models
@@ -751,6 +758,7 @@ ReSum validates the exact architecture `pi-condense` uses: an external summarize
 ACON is a unified framework that compresses **both** environment observations and interaction histories into "concise yet informative condensations." It treats compression as an optimization problem: maximize task reward while minimizing context cost.
 
 **Method:**
+
 - **Gradient-free** — uses natural language space optimization (no model fine-tuning)
 - **Failure-driven guideline optimization:** runs the agent with and without compression, collects cases where compression caused failure, and uses an optimizer LLM to refine compression guidelines
 - Two-step alternation:
@@ -759,6 +767,7 @@ ACON is a unified framework that compresses **both** environment observations an
 - **Distillation:** optimized compressor can be distilled into smaller models (e.g., Qwen-14B) with >95% accuracy retention
 
 **Key results:**
+
 - **26–54% reduction in peak tokens** across AppWorld, OfficeBench, and Multi-objective QA
 - Preserves task performance with large models
 - **Smaller LMs improve 20–46%** as agents when context compression removes distracting noise
@@ -782,6 +791,7 @@ Lineage: simplified take on DCP's `maxContextLimit` nudging — a single thresho
 Use case: a single enormous tool result can jump context usage by 20–30 percentage points in one turn; `autoBudgetThreshold` misses this until the next turn. `budgetTurnDelta` catches the spike immediately.
 
 **`previousFraction` tracking:**
+
 - Reset to `null` on `session_start` and `session_tree` (session reload).
 - Left unchanged on a null-tokens turn immediately following a provider-side compaction (treating a post-compaction null as `0` would produce a spurious spike on the next real turn).
 - The post-restart first turn cannot fire a delta trigger (no prior fraction to compare) and falls back to `autoBudgetThreshold` alone.
@@ -838,6 +848,7 @@ raw messages from session
 ### Identification model
 
 Pi-ai's `Message` union (`UserMessage | AssistantMessage | ToolResultMessage`) has no `.id` field. Chain compression uses:
+
 - `timestamp: number` to identify user / final-assistant boundary messages
 - `toolCallId` sets to identify middle assistant turns and their tool results
 
@@ -920,11 +931,13 @@ Error purge replaces those arg bodies with compact stubs after the error has coo
 ```
 
 **What triggers a purge:**
+
 - The matching `ToolResultMessage` has `isError: true`.
 - The error occurred at least `purgeErrors.cooldownTurns` assistant turns ago (default 2). The cooldown gives the model 1–2 turns to retry before context is mutated.
 - The JSON-stringified argument body is at least `purgeErrors.minArgChars` characters long (default 500). Small args are not worth the substitution.
 
 **What error purge does NOT touch:**
+
 - The `ToolResultMessage` content — the error message stays visible so the model can see what went wrong.
 - Non-errored `toolCall` argument bodies.
 - Argument bodies below `minArgChars`.
@@ -959,6 +972,7 @@ Thinking strip is a deterministic, zero-LLM transform (Phase 4) that keeps `thin
 ### Provider safety
 
 Anthropic's extended-thinking contract during tool use:
+
 - Only the **last assistant turn's** thinking is required; "you can omit thinking blocks from prior assistant role turns" and the API auto-filters them.
 - A message's thinking blocks must be dropped **all-or-nothing** ("the entire sequence of consecutive thinking blocks must match the outputs … you can't rearrange or modify the sequence"). The strip reuses `withoutThinkingBlocks`, which removes every thinking block (and its signature) from a message.
 

package/README.md

@@ -192,7 +192,7 @@ Set it from the slash command (saves immediately):
 
 ## Tools surfaced to the LLM
 
-**`context_tree_query`** — always available when the extension is loaded. Pruned summaries end with short refs like `Summarized tool refs: \`t1\`, \`t2\`. Use \`context_tree_query\` with these refs to retrieve the original full outputs.` The model passes those refs (or full `toolCallId`s) and gets back the original tool result text from the session index. Content-hash-deduped duplicates resolve to the original's record automatically.
+**`context_tree_query`** — always available when the extension is loaded. Pruned summaries end with short refs like `Summarized tool refs: \`t1\`, \`t2\`. Use \`context_tree_query\` with these refs to retrieve the original full outputs.` The model passes those refs (or full `toolCallId`s) and gets back the original tool result text from the session index. Each per-tool bullet in the summary also carries its own inline `` `tN` `` ref, so recovering a specific tool is a single hop; the footer still lists every ref as a fallback. Content-hash-deduped duplicates resolve to the original's record automatically.
 
 ## Footer status widget
 
@@ -224,6 +224,7 @@ interface ExternalCostUpdate {
 ```
 
 Semantics:
+
 - **Cumulative per session**, not all-time. Re-emitted on every update; aggregators key by `source` and replace the previous value.
 - **Live only.** Not persisted; not re-emitted on `session_start`. An aggregator that restarts mid-session sees cost from zero until the next summarizer call.
 - Designed for aggregators like pi-cohort that show a unified Σ$ total across extensions.

package/index.ts

@@ -22,7 +22,7 @@ import { pruneMessages } from "./src/pruner.js";
 import { isProtected } from "./src/protected.js";
 import { registerQueryTool } from "./src/query-tool.js";
 import { registerCommands, setPruneStatusWidget } from "./src/commands.js";
-import { formatSummaryToolCallRefs, makeSummaryDetails } from "./src/summary-refs.js";
+import { formatSummaryToolCallRefs, makeSummaryDetails, substituteInlineRefs } from "./src/summary-refs.js";
 import type { ContextPruneConfig, CapturedBatch, PruneFrontier, FlushOptions } from "./src/types.js";
 import {
   DEFAULT_CONFIG,
@@ -166,7 +166,7 @@ export default function (pi: ExtensionAPI) {
 
     // Use pre-captured batches if provided (avoids double-capture when the
     // caller previewed the queue before opening the progress overlay).
-    let batches: CapturedBatch[] = options.previewedBatches ?? capturePendingBatches(ctx);
+    const batches: CapturedBatch[] = options.previewedBatches ?? capturePendingBatches(ctx);
 
     if (batches.length === 0) return { ok: false, reason: "empty" };
 
@@ -387,7 +387,9 @@ export default function (pi: ExtensionAPI) {
         }
 
         const summaryRefs = indexer.allocateSummaryRefs(batch);
-        const summaryText = result.summaryText + formatSummaryToolCallRefs(summaryRefs);
+        const toolNames = batch.toolCalls.map((tc) => tc.toolName);
+        const decorated = substituteInlineRefs(result.summaryText, summaryRefs, toolNames);
+        const summaryText = decorated + formatSummaryToolCallRefs(summaryRefs);
         const shouldSkipOversized = summaryText.length > batchRawCharCount;
 
         statsAccum.add(result.usage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Pi extension that summarizes completed tool-call batches, replaces raw outputs with short stubs in future context, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",
@@ -34,6 +34,7 @@
     "PRUNING.md"
   ],
   "scripts": {
+    "check:agents-core": "node scripts/check-agents-core.mjs",
     "test": "bun test src/"
   },
   "pi": {

package/src/batch-capture.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { serializeBatchForSummarizer } from "./batch-capture.js";
+import type { CapturedBatch, CapturedToolCall } from "./types.js";
+
+function toolCall(overrides: Partial<CapturedToolCall> = {}): CapturedToolCall {
+  return {
+    toolCallId: "id",
+    toolName: "read",
+    args: {},
+    resultText: "ok",
+    isError: false,
+    ...overrides,
+  };
+}
+
+function batch(toolCalls: CapturedToolCall[]): CapturedBatch {
+  return {
+    turnIndex: 0,
+    timestamp: 0,
+    assistantText: "",
+    toolCalls,
+  };
+}
+
+describe("serializeBatchForSummarizer", () => {
+  test("prefixes each tool block with [[N:toolname]] in order", () => {
+    const b = batch([
+      toolCall({ toolCallId: "a", toolName: "read" }),
+      toolCall({ toolCallId: "b", toolName: "bash" }),
+    ]);
+
+    const result = serializeBatchForSummarizer(b);
+
+    expect(result).toContain("[[1:read]] Tool: read(");
+    expect(result).toContain("[[2:bash]] Tool: bash(");
+  });
+
+  test("numbering is contiguous 1..N regardless of toolCallId values", () => {
+    const b = batch([
+      toolCall({ toolCallId: "zzz", toolName: "read" }),
+      toolCall({ toolCallId: "aaa", toolName: "read" }),
+      toolCall({ toolCallId: "mmm", toolName: "write" }),
+    ]);
+
+    const result = serializeBatchForSummarizer(b);
+
+    expect(result).toContain("[[1:read]] Tool:");
+    expect(result).toContain("[[2:read]] Tool:");
+    expect(result).toContain("[[3:write]] Tool:");
+  });
+});

package/src/batch-capture.ts

@@ -151,7 +151,7 @@ export function serializeBatchForSummarizer(batch: CapturedBatch): string {
     parts.push(`Assistant said: ${batch.assistantText}\n`);
   }
 
-  const toolParts = batch.toolCalls.map((tc) => {
+  const toolParts = batch.toolCalls.map((tc, index) => {
     const status = tc.isError ? "ERROR" : "OK";
     const argsJson = JSON.stringify(tc.args, null, 2);
 
@@ -162,7 +162,7 @@ export function serializeBatchForSummarizer(batch: CapturedBatch): string {
       resultText = resultText.slice(0, MAX_CHARS) + ` ...[${remaining} chars truncated]`;
     }
 
-    return `Tool: ${tc.toolName}(${argsJson})\nResult (${status}): ${resultText}`;
+    return `[[${index + 1}:${tc.toolName}]] Tool: ${tc.toolName}(${argsJson})\nResult (${status}): ${resultText}`;
   });
 
   parts.push(toolParts.join("\n---\n"));

package/src/summarizer.ts

@@ -17,7 +17,9 @@ For each tool call provide:
 - Key outcome, plus any file paths, identifiers, signatures, or error strings copied verbatim - never reword these
 - Any findings the future conversation needs to remember
 
-Keep each tool call to 1-3 bullet points. Skip calls that succeeded with nothing reusable to record. Be concise.`;
+Keep each tool call to 1-3 bullet points. Skip calls that succeeded with nothing reusable to record. Be concise.
+
+Begin the first bullet of each tool call with that tool's [[N:toolname]] label, copied verbatim (both the number and the name) from its line in the input, as the plain, first thing on the line - no bold, backticks, or list numbering around it. Do not renumber, rename, or invent labels; if you skip a tool, skip its label too.`;
 
 const RANGE_SYSTEM_PROMPT = `You are fusing several per-step summaries of one CLOSED sub-task from an AI coding assistant's history into a SINGLE cohesive summary.
 - Merge overlapping or repeated information; do not restate each step separately.

package/src/summary-refs.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import { substituteInlineRefs, formatSummaryToolCallRefs, type SummaryToolCallRef } from "./summary-refs.js";
+
+describe("substituteInlineRefs", () => {
+  const refs: SummaryToolCallRef[] = [
+    { shortId: "t1", toolCallId: "a" },
+    { shortId: "t2", toolCallId: "b" },
+  ];
+  const names = ["read", "bash"];
+
+  test("in-range and matching name rewrites to inline ref", () => {
+    expect(substituteInlineRefs("- [[1:read]] Read a.ts", refs, names)).toBe("- `t1` Read a.ts");
+    expect(substituteInlineRefs("- [[2:bash]] ran ls", refs, names)).toBe("- `t2` ran ls");
+  });
+
+  test("does not add extra t prefix", () => {
+    const out = substituteInlineRefs("[[1:read]] x", refs, names);
+    expect(out).toBe("`t1` x");
+    expect(out).not.toContain("tt1");
+  });
+
+  test("name match is trimmed and case-insensitive", () => {
+    expect(substituteInlineRefs("- [[1:Read]] x", refs, names)).toBe("- `t1` x");
+  });
+
+  test("name mismatch strips label", () => {
+    expect(substituteInlineRefs("- [[2:read]] x", refs, names)).toBe("- x");
+  });
+
+  test("out of range strips label", () => {
+    expect(substituteInlineRefs("- [[9:read]] x", refs, names)).toBe("- x");
+  });
+
+  test("absent label leaves line unchanged", () => {
+    expect(substituteInlineRefs("- plain bullet", refs, names)).toBe("- plain bullet");
+  });
+
+  test("duplicate labels on separate lines both substituted", () => {
+    expect(substituteInlineRefs("- [[2:bash]] first\n- [[2:bash]] second", refs, names)).toBe(
+      "- `t2` first\n- `t2` second",
+    );
+  });
+
+  test("single-bracket lookalikes are untouched", () => {
+    const input = "used argv[1] and items[0] here";
+    expect(substituteInlineRefs(input, refs, names)).toBe(input);
+  });
+
+  test("mid-line well-formed label token is stripped (leak guard)", () => {
+    expect(substituteInlineRefs("used argv[1] and [[1:read]] mid", refs, names)).toBe(
+      "used argv[1] and mid",
+    );
+  });
+
+  test("label inside fenced code block is untouched", () => {
+    const input = "```\n[[1:read]] literal\n```";
+    expect(substituteInlineRefs(input, refs, names)).toBe(input);
+  });
+
+  test("wrapped label ([[1:read]] in **bold**) is stripped, no raw token leaked", () => {
+    const input = "- **[[1:read]]** x";
+    expect(substituteInlineRefs(input, refs, names)).toBe("- **** x");
+  });
+
+  test("numbered-list label leak guard: token stripped, no anchored match", () => {
+    expect(substituteInlineRefs("1. [[1:read]] did x", refs, names)).toBe("1. did x");
+  });
+
+  test("blockquote label leak guard: token stripped, no anchored match", () => {
+    expect(substituteInlineRefs("> [[1:read]] did x", refs, names)).toBe("> did x");
+  });
+
+  test("fenced non-first-line label is still exempt from catch-all strip", () => {
+    const input = "```\nfoo [[1:read]] bar\n```";
+    expect(substituteInlineRefs(input, refs, names)).toBe(input);
+  });
+
+  test("range-fusion: inline ref survives fusion-input concatenation across batches", () => {
+    const body = substituteInlineRefs("- [[1:read]] did a thing", refs, names);
+    expect(body).toBe("- `t1` did a thing");
+    expect(body).toContain("`t1`");
+    const fusionInput = [body, body].join("\n---\n");
+    expect(fusionInput).toContain("`t1`");
+  });
+
+  test("N=0 is out of range and strips label", () => {
+    expect(substituteInlineRefs("- [[0:read]] x", refs, names)).toBe("- x");
+  });
+
+  test("empty input returns empty string", () => {
+    expect(substituteInlineRefs("", refs, names)).toBe("");
+  });
+
+  test("collapses multiple trailing spaces to one", () => {
+    expect(substituteInlineRefs("- [[1:read]]    x", refs, names)).toBe("- `t1` x");
+  });
+
+  test("label at end of line has single trailing space, no phantom double", () => {
+    expect(substituteInlineRefs("- [[1:read]]", refs, names)).toBe("- `t1` ");
+  });
+
+  test("dotted/namespaced tool name matches and validates", () => {
+    const nsRefs: SummaryToolCallRef[] = [{ shortId: "t1", toolCallId: "a" }];
+    const nsNames = ["server.tool"];
+    expect(substituteInlineRefs("- [[1:server.tool]] did x", nsRefs, nsNames)).toBe("- `t1` did x");
+  });
+
+  test("dotted/namespaced tool name mismatch strips label, does not leak", () => {
+    const nsRefs: SummaryToolCallRef[] = [{ shortId: "t1", toolCallId: "a" }];
+    const nsNames = ["server.tool"];
+    expect(substituteInlineRefs("- [[1:other.tool]] x", nsRefs, nsNames)).toBe("- x");
+  });
+
+  test("composition with formatSummaryToolCallRefs footer", () => {
+    const body = substituteInlineRefs("- [[1:read]] a\n- [[2:bash]] b", refs, names);
+    const footer = formatSummaryToolCallRefs(refs);
+    for (const ref of refs) {
+      expect(body).toContain(`\`${ref.shortId}\``);
+      expect(footer).toContain(`\`${ref.shortId}\``);
+    }
+  });
+});

package/src/summary-refs.ts

@@ -59,3 +59,39 @@ export function makeSummaryDetails(batch: CapturedBatch, refs: SummaryToolCallRe
     timestamp: batch.timestamp,
   };
 }
+
+/**
+ * Rewrites line-leading `[[N:name]]` labels emitted by the summarizer into
+ * inline `` `tN` `` refs. `refs` and `toolNames` are positionally aligned to
+ * the batch's tool-call order. The echoed name is validated against the tool
+ * at position N; a mismatch or out-of-range N strips the label (footer-only).
+ * A catch-all strip pass on non-fenced lines removes any surviving well-formed
+ * label token (wrapped, numbered, or blockquoted) so no raw `[[N:name]]` token
+ * ever leaks into context; fenced code blocks remain exempt.
+ */
+export function substituteInlineRefs(
+  text: string,
+  refs: SummaryToolCallRef[],
+  toolNames: string[],
+): string {
+  const LABEL = /^(\s*(?:[-*]\s+)?)\[\[(\d+):([^\]\n]+)\]\]\s*/;
+  const lines = text.split("\n");
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimStart().startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    lines[i] = lines[i].replace(LABEL, (_m, prefix: string, numStr: string, name: string) => {
+      const n = Number(numStr);
+      const ref = refs[n - 1];
+      const expected = toolNames[n - 1];
+      if (!ref || expected === undefined) return prefix;
+      if (name.trim().toLowerCase() !== expected.trim().toLowerCase()) return prefix;
+      return `${prefix}\`${ref.shortId}\` `;
+    });
+    lines[i] = lines[i].replace(/\[\[\d+:[^\]\n]+\]\]\s*/g, "");
+  }
+  return lines.join("\n");
+}