pi-condense 2.0.0

package/src/indexer.ts

@@ -0,0 +1,393 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  CapturedBatch,
+  ChainCompressionEntry,
+  DedupAliasEntryData,
+  IndexEntryData,
+  ToolCallRecord,
+} from "./types.js";
+import {
+  CUSTOM_TYPE_CHAIN,
+  CUSTOM_TYPE_DEDUP_ALIAS,
+  CUSTOM_TYPE_INDEX,
+  CUSTOM_TYPE_SUMMARY,
+} from "./types.js";
+import {
+  buildShortToolCallRefs,
+  normalizeSummaryToolCallRefs,
+  type SummaryToolCallRef,
+} from "./summary-refs.js";
+import { hashToolResult } from "./content-hash.js";
+
+export class ToolCallIndexer {
+  private index = new Map<string, ToolCallRecord>();
+  private aliasToToolCallId = new Map<string, string>();
+  private toolCallIdToAlias = new Map<string, string>();
+  private nextShortAliasNumber = 1;
+  /**
+   * hash → original toolCallId. Populated as records enter the indexer
+   * (`addBatch`) and on `reconstructFromSession`. Drives the pre-flush
+   * dedup pass via `lookupByContent`.
+   */
+  private contentHashToOriginal = new Map<string, string>();
+  /**
+   * Duplicate toolCallId → original toolCallId. Populated by
+   * `registerDuplicate` during the pre-flush dedup pass and rebuilt from
+   * CUSTOM_TYPE_DEDUP_ALIAS entries on reconstruction.
+   *
+   * Both `isSummarized` and `resolveToolCallId` consult this map so
+   * `pruneMessages` stub-replaces dup toolResults and `context_tree_query`
+   * resolves dup ids to the original record.
+   */
+  private dedupAliasToOriginal = new Map<string, string>();
+  /**
+   * Per-batch summary bodies for chain-compression summary text lookup.
+   * Each entry maps a set of toolCallIds to the summary's markdown body.
+   * Populated from CUSTOM_TYPE_SUMMARY entries at rebuild time and via
+   * `registerSummaryBody` after a successful flush.
+   */
+  private summaryBodies: Array<{ toolCallIds: string[]; text: string }> = [];
+  /** Compressed chains, keyed on startUserTimestamp for O(1) dedup checks. */
+  private chainRegistry = new Map<number, ChainCompressionEntry>();
+
+  /**
+   * Rebuilds the in-memory index from session history by scanning all
+   * custom entries with customType === CUSTOM_TYPE_INDEX.
+   */
+  reconstructFromSession(ctx: ExtensionContext): void {
+    this.index.clear();
+    this.aliasToToolCallId.clear();
+    this.toolCallIdToAlias.clear();
+    this.contentHashToOriginal.clear();
+    this.dedupAliasToOriginal.clear();
+    this.nextShortAliasNumber = 1;
+    this.summaryBodies = [];
+    this.chainRegistry.clear();
+
+    // Two passes so dedup aliases land AFTER the original short refs they
+    // need to reuse, regardless of the underlying append order.
+    const branch = ctx.sessionManager.getBranch();
+    const dedupAliasEntries: DedupAliasEntryData[] = [];
+
+    for (const entry of branch) {
+      if (entry.type === "custom" && (entry as any).customType === CUSTOM_TYPE_INDEX) {
+        const data = (entry as any).data as IndexEntryData;
+        if (data && Array.isArray(data.toolCalls)) {
+          for (const toolCall of data.toolCalls) {
+            this.index.set(toolCall.toolCallId, toolCall);
+            // First-seen wins so the contentHashToOriginal map matches what
+            // addBatch would have produced at append time.
+            const hash = toolCall.contentHash ?? hashToolResult(toolCall.toolName, toolCall.resultText);
+            if (!this.contentHashToOriginal.has(hash)) {
+              this.contentHashToOriginal.set(hash, toolCall.toolCallId);
+            }
+          }
+        }
+        continue;
+      }
+
+      if (entry.type === "custom_message" && (entry as any).customType === CUSTOM_TYPE_SUMMARY) {
+        const refs = normalizeSummaryToolCallRefs((entry as any).details);
+        this.registerSummaryRefs(refs);
+        const raw = (entry as any).content;
+        const text =
+          typeof raw === "string"
+            ? raw
+            : Array.isArray(raw)
+              ? raw
+                  .filter((c: any) => c.type === "text")
+                  .map((c: any) => c.text as string)
+                  .join("\n")
+              : "";
+        if (text) {
+          this.summaryBodies.push({ toolCallIds: refs.map((r) => r.toolCallId), text });
+        }
+        continue;
+      }
+
+      if (entry.type === "custom" && (entry as any).customType === CUSTOM_TYPE_CHAIN) {
+        const data = (entry as any).data as ChainCompressionEntry;
+        if (data?.blockId && typeof data.startUserTimestamp === "number") {
+          this.chainRegistry.set(data.startUserTimestamp, data);
+        }
+        continue;
+      }
+
+      if (entry.type === "custom" && (entry as any).customType === CUSTOM_TYPE_DEDUP_ALIAS) {
+        const data = (entry as any).data as DedupAliasEntryData;
+        if (data?.newToolCallId && data?.originalToolCallId) {
+          dedupAliasEntries.push(data);
+        }
+      }
+    }
+
+    for (const data of dedupAliasEntries) {
+      this.dedupAliasToOriginal.set(data.newToolCallId, data.originalToolCallId);
+      const originalShortRef = this.toolCallIdToAlias.get(data.originalToolCallId);
+      if (originalShortRef) {
+        // Keep `getShortRefForToolCallId(dupId)` returning the SAME short ref
+        // as the original so pruneMessages emits a consistent `tN` for both.
+        this.toolCallIdToAlias.set(data.newToolCallId, originalShortRef);
+      }
+    }
+  }
+
+  /**
+   * Returns true if the given toolCallId has been pruned — either because
+   * its full record is in the index, or because it has been registered as
+   * an alias of an already-indexed original via the content-hash dedup pass.
+   *
+   * `pruneMessages` uses this to decide whether to stub-replace a
+   * ToolResultMessage; both cases need the same treatment.
+   */
+  isSummarized(toolCallId: string): boolean {
+    return this.index.has(toolCallId) || this.dedupAliasToOriginal.has(toolCallId);
+  }
+
+  /**
+   * Returns the full runtime index map.
+   */
+  getIndex(): Map<string, ToolCallRecord> {
+    return this.index;
+  }
+
+  /**
+   * Register short aliases for a summary message so future recovery queries can
+   * resolve the short ids back to the persisted toolCallIds.
+   */
+  registerSummaryRefs(refs: SummaryToolCallRef[]): void {
+    for (const ref of refs) {
+      if (!ref.shortId || !ref.toolCallId) continue;
+      if (ref.shortId !== ref.toolCallId) {
+        this.aliasToToolCallId.set(ref.shortId, ref.toolCallId);
+        this.toolCallIdToAlias.set(ref.toolCallId, ref.shortId);
+      }
+      const match = /^t(\d+)$/.exec(ref.shortId);
+      if (match) {
+        this.nextShortAliasNumber = Math.max(this.nextShortAliasNumber, Number(match[1]) + 1);
+      }
+    }
+  }
+
+  /**
+   * Allocates short aliases for a batch's tool calls and registers them in the
+   * runtime alias map.
+   */
+  allocateSummaryRefs(batch: CapturedBatch): SummaryToolCallRef[] {
+    const toolCallIds = batch.toolCalls.map((tc) => tc.toolCallId);
+    const { refs, nextIndex } = buildShortToolCallRefs(toolCallIds, this.nextShortAliasNumber);
+    this.nextShortAliasNumber = nextIndex;
+    return refs;
+  }
+
+  /**
+   * Resolve a short alias, a duplicate's toolCallId, or a full toolCallId
+   * to the canonical toolCallId backing it.
+   *
+   * Order:
+   *   1. Direct hit in `this.index` (canonical id).
+   *   2. Dedup alias → underlying original toolCallId.
+   *   3. Short-ref (`t3`) → underlying toolCallId.
+   *
+   * Used by `getRecord`/`lookupToolCalls` so `context_tree_query` returns
+   * the original record for both short refs and dedup'd ids.
+   */
+  resolveToolCallId(toolCallIdOrAlias: string): string | undefined {
+    if (this.index.has(toolCallIdOrAlias)) return toolCallIdOrAlias;
+    const dedupTarget = this.dedupAliasToOriginal.get(toolCallIdOrAlias);
+    if (dedupTarget) return dedupTarget;
+    return this.aliasToToolCallId.get(toolCallIdOrAlias);
+  }
+
+  /**
+   * Returns the short alias (e.g. "t1") registered for the given
+   * toolCallId, or undefined if none was registered. Legacy summaries
+   * written before short-refs were introduced map shortId === toolCallId
+   * and intentionally return undefined here so callers (e.g. the
+   * pruner stub) can fall back to the toolCallId itself.
+   */
+  getShortRefForToolCallId(toolCallId: string): string | undefined {
+    return this.toolCallIdToAlias.get(toolCallId);
+  }
+
+  /**
+   * Look up a single record by toolCallId or short alias (used by query tool).
+   */
+  getRecord(toolCallIdOrAlias: string): ToolCallRecord | undefined {
+    const resolved = this.resolveToolCallId(toolCallIdOrAlias);
+    if (!resolved) return undefined;
+    return this.index.get(resolved);
+  }
+
+  /**
+   * Looks up multiple tool call records by ID. Skips any IDs not found.
+   */
+  lookupToolCalls(toolCallIds: string[]): ToolCallRecord[] {
+    const results: ToolCallRecord[] = [];
+    for (const id of toolCallIds) {
+      const record = this.getRecord(id);
+      if (record !== undefined) {
+        results.push(record);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Returns the toolCallId of an already-indexed record whose
+   * `(toolName, normalize(resultText))` matches the supplied input, or
+   * `undefined` if there is no match. Driven by the in-memory
+   * `contentHashToOriginal` map; only consults records that entered the
+   * indexer via `addBatch` (i.e. previous successful prunes) or were
+   * replayed at reconstruction time.
+   *
+   * Returns `undefined` for hash misses; consumers should treat that as
+   * "not a duplicate".
+   */
+  lookupByContent(toolName: string, resultText: string): string | undefined {
+    const hash = hashToolResult(toolName, resultText);
+    return this.contentHashToOriginal.get(hash);
+  }
+
+  /**
+   * Registers `newToolCallId` as a duplicate of `originalToolCallId`. The new
+   * id reuses the original's short alias (so `pruneMessages` emits the same
+   * `tN` ref for both) and is persisted via the supplied `appendEntry` so
+   * reconstruction can replay it later.
+   *
+   * No-op when `newToolCallId === originalToolCallId` (defensive).
+   */
+  registerDuplicate(
+    newToolCallId: string,
+    originalToolCallId: string,
+    appendEntry: (customType: string, data?: unknown) => void,
+  ): void {
+    if (newToolCallId === originalToolCallId) return;
+    this.dedupAliasToOriginal.set(newToolCallId, originalToolCallId);
+    const originalShortRef = this.toolCallIdToAlias.get(originalToolCallId);
+    if (originalShortRef) {
+      this.toolCallIdToAlias.set(newToolCallId, originalShortRef);
+    }
+    const payload: DedupAliasEntryData = { newToolCallId, originalToolCallId };
+    appendEntry(CUSTOM_TYPE_DEDUP_ALIAS, payload);
+  }
+
+  /**
+   * Stores summary body text keyed by the toolCallIds it covers.
+   * Called after a successful flush so `getPerBatchSummaryTextForToolCallIds`
+   * can serve chain summaries without re-scanning session entries.
+   */
+  registerSummaryBody(toolCallIds: string[], text: string): void {
+    if (text && toolCallIds.length > 0) {
+      this.summaryBodies.push({ toolCallIds, text });
+    }
+  }
+
+  /** Returns true if at least one stored summary covers any of the given toolCallIds. */
+  hasPerBatchSummaryCoveringAny(toolCallIds: string[]): boolean {
+    if (toolCallIds.length === 0) return false;
+    const idSet = new Set(toolCallIds);
+    return this.summaryBodies.some((s) => s.toolCallIds.some((id) => idSet.has(id)));
+  }
+
+  /**
+   * Returns the distinct per-batch summary texts whose toolCallIds overlap the
+   * given set (dedup'd by text). Used to build the synthetic chain body and as
+   * the fusion input for the range summarizer; the >= 2 count gates fusion.
+   */
+  getPerBatchSummariesForToolCallIds(toolCallIds: string[]): string[] {
+    if (toolCallIds.length === 0) return [];
+    const idSet = new Set(toolCallIds);
+    const texts: string[] = [];
+    const seen = new Set<string>();
+    for (const s of this.summaryBodies) {
+      if (s.toolCallIds.some((id) => idSet.has(id)) && !seen.has(s.text)) {
+        seen.add(s.text);
+        texts.push(s.text);
+      }
+    }
+    return texts;
+  }
+
+  /**
+   * Returns the concatenated summary text for all per-batch summaries whose
+   * toolCallIds overlap the given set, joined with "\n\n".
+   * Used by chain-range-prune to build the synthetic chain message body.
+   */
+  getPerBatchSummaryTextForToolCallIds(toolCallIds: string[]): string {
+    return this.getPerBatchSummariesForToolCallIds(toolCallIds).join("\n\n");
+  }
+
+  /**
+   * Returns the short t<N> refs for the given toolCallIds.
+   * Skips ids with no registered short ref (tool calls not yet summarized).
+   */
+  getToolRefsForToolCallIds(toolCallIds: string[]): string[] {
+    const refs: string[] = [];
+    for (const id of toolCallIds) {
+      const ref = this.toolCallIdToAlias.get(id);
+      if (ref) refs.push(ref);
+    }
+    return refs;
+  }
+
+  /** Registers a chain entry in the in-memory registry. Called by chain-compressor after persisting. */
+  registerChain(entry: ChainCompressionEntry): void {
+    this.chainRegistry.set(entry.startUserTimestamp, entry);
+  }
+
+  /** Returns all compressed chain entries sorted by startUserTimestamp ascending. */
+  getChainEntries(): ChainCompressionEntry[] {
+    return [...this.chainRegistry.values()].sort((a, b) => a.startUserTimestamp - b.startUserTimestamp);
+  }
+
+  /** O(n) scan over the chain registry by blockId. Registry is small (bounded by session chain count). */
+  findChainEntryByBlockId(blockId: string): ChainCompressionEntry | undefined {
+    for (const entry of this.chainRegistry.values()) {
+      if (entry.blockId === blockId) return entry;
+    }
+    return undefined;
+  }
+
+  /**
+   * Adds all tool calls from a captured batch to the runtime index and
+   * persists an IndexEntryData entry to the session via the supplied
+   * appendEntry callback. The callback exists so callers can route the
+   * append through either `pi.appendEntry` (runtime delivery) or
+   * `ctx.sessionManager.appendCustomEntry` (session delivery), without the
+   * indexer needing to know which one is active.
+   */
+  addBatch(
+    batch: CapturedBatch,
+    appendEntry: (customType: string, data?: unknown) => void,
+  ): void {
+    const records: ToolCallRecord[] = [];
+
+    for (const tc of batch.toolCalls) {
+      const record: ToolCallRecord = {
+        toolCallId: tc.toolCallId,
+        toolName: tc.toolName,
+        args: tc.args,
+        resultText: tc.resultText,
+        isError: tc.isError,
+        turnIndex: batch.turnIndex,
+        timestamp: batch.timestamp,
+        ...(tc.spillPath !== undefined ? { spillPath: tc.spillPath } : {}),
+        ...(tc.spillBytes !== undefined ? { spillBytes: tc.spillBytes } : {}),
+        ...(tc.resultPreview !== undefined ? { resultPreview: tc.resultPreview } : {}),
+        ...(tc.contentHash !== undefined ? { contentHash: tc.contentHash } : {}),
+      };
+      this.index.set(record.toolCallId, record);
+      records.push(record);
+      // Populate the dedup hash map AFTER the record is indexed so a future
+      // flush can dedup against this record. First-seen wins to keep the
+      // canonical id stable across multiple identical entries.
+      const hash = record.contentHash ?? hashToolResult(record.toolName, record.resultText);
+      if (!this.contentHashToOriginal.has(hash)) {
+        this.contentHashToOriginal.set(hash, record.toolCallId);
+      }
+    }
+
+    appendEntry(CUSTOM_TYPE_INDEX, { toolCalls: records } as IndexEntryData);
+  }
+}

package/src/nested-placeholders.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { substituteBlockRefs } from "./nested-placeholders.js";
+
+const lookup = (id: string): string | undefined => {
+  const map: Record<string, string> = {
+    b1: "summary of chain one",
+    b2: "summary of chain two",
+    b3: "chain three with {b2} inside",
+  };
+  return map[id];
+};
+
+describe("substituteBlockRefs", () => {
+  test("empty text returns empty string", () => {
+    expect(substituteBlockRefs("", lookup)).toBe("");
+  });
+
+  test("text with no placeholders is unchanged", () => {
+    const text = "no placeholders here, just prose";
+    expect(substituteBlockRefs(text, lookup)).toBe(text);
+  });
+
+  test("single {b1} is substituted", () => {
+    expect(substituteBlockRefs("{b1}", lookup)).toBe("summary of chain one");
+  });
+
+  test("multiple references in one text are all resolved", () => {
+    expect(substituteBlockRefs("{b1} and {b2}", lookup)).toBe(
+      "summary of chain one and summary of chain two",
+    );
+  });
+
+  test("missing blockId leaves the literal {bN} in place", () => {
+    expect(substituteBlockRefs("{b99}", lookup)).toBe("{b99}");
+  });
+
+  test("missing blockId among valid ones leaves only the unknown one", () => {
+    expect(substituteBlockRefs("{b1} and {b99}", lookup)).toBe("summary of chain one and {b99}");
+  });
+
+  test("self-reference is refused even when lookup has a value", () => {
+    // b3 is in the lookup, but selfBlockId=b3 means it must stay literal
+    expect(substituteBlockRefs("{b3} foo", lookup, { selfBlockId: "b3" })).toBe("{b3} foo");
+  });
+
+  test("self-reference refused, other refs still substituted", () => {
+    expect(substituteBlockRefs("{b3} and {b1}", lookup, { selfBlockId: "b3" })).toBe(
+      "{b3} and summary of chain one",
+    );
+  });
+
+  test("one-level only: substituted text containing {b2} is NOT re-expanded", () => {
+    // b3 → "chain three with {b2} inside"
+    // The {b2} inside that expansion must survive as a literal in the output.
+    const result = substituteBlockRefs("{b3}", lookup);
+    expect(result).toBe("chain three with {b2} inside");
+    // Explicitly: {b2} in the output is the literal string, not "summary of chain two"
+    expect(result).not.toContain("summary of chain two");
+  });
+
+  test("adjacent placeholders handled cleanly", () => {
+    expect(substituteBlockRefs("{b1}{b2}", lookup)).toBe(
+      "summary of chain onesummary of chain two",
+    );
+  });
+
+  test("placeholders embedded in surrounding prose", () => {
+    expect(substituteBlockRefs("Before {b1} middle {b2} after", lookup)).toBe(
+      "Before summary of chain one middle summary of chain two after",
+    );
+  });
+
+  test("lookup returning undefined leaves placeholder literal (null-safe contract)", () => {
+    // `resolved ?? match` only falls through to the literal when lookup returns undefined.
+    // pruner.ts collapses empty-string summary bodies to undefined before calling here
+    // (`|| undefined`), so this test pins the undefined-→-literal path that the
+    // pruner relies on to avoid silently erasing placeholders when summary bodies are missing.
+    const missingLookup = (_: string): string | undefined => undefined;
+    expect(substituteBlockRefs("{b1}", missingLookup)).toBe("{b1}");
+    expect(substituteBlockRefs("{b1} text", missingLookup)).toBe("{b1} text");
+  });
+});

package/src/nested-placeholders.ts

@@ -0,0 +1,20 @@
+// One-level substitution only: the replaced text is not re-scanned.
+// This is intentional — if summary B contains "{b1}", that placeholder
+// was already resolved (or left literal) when B was originally generated.
+// Re-scanning would require cycle detection across an arbitrary graph and
+// could silently expand stale content if the session is replayed later.
+const BLOCK_REF_RE = /\{b(\d+)\}/g;
+
+export function substituteBlockRefs(
+  text: string,
+  blockSummaryLookup: (blockId: string) => string | undefined,
+  options?: { selfBlockId?: string },
+): string {
+  const selfBlockId = options?.selfBlockId;
+  return text.replace(BLOCK_REF_RE, (match, digits) => {
+    const blockId = `b${digits}`;
+    if (blockId === selfBlockId) return match;
+    const resolved = blockSummaryLookup(blockId);
+    return resolved ?? match;
+  });
+}

package/src/oversized-spill.integration.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ToolCallIndexer } from "./indexer.js";
+import { spillOversizedBatch, blobPathFor } from "./spill.js";
+import { pruneMessages } from "./pruner.js";
+import type { CapturedBatch } from "./types.js";
+import { CUSTOM_TYPE_INDEX } from "./types.js";
+
+const cfg = { spillThreshold: 10, spillPreviewBytes: 16, dedupByContentHash: true };
+const batch = (tc: any): CapturedBatch => ({ turnIndex: 0, timestamp: 1, assistantText: "", toolCalls: [tc] });
+
+describe("oversized spill end-to-end", () => {
+  it("spills, stubs in context, keeps full body on disk, survives reconstruct", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spill-e2e-"));
+    try {
+      const indexer = new ToolCallIndexer();
+      const entries: any[] = [];
+      const appendEntry = (customType: string, data?: unknown) => {
+        entries.push({ type: "custom", customType, data });
+      };
+
+      const body = "BIG\n".repeat(1000);
+      await spillOversizedBatch({
+        batch: batch({ toolCallId: "tc1", toolName: "fetch", args: { url: "u" }, resultText: body, isError: false }),
+        indexer,
+        config: cfg,
+        sessionDir: dir,
+        sessionId: "sid",
+        appendEntry,
+      });
+
+      // (a) full body on disk
+      expect(await readFile(blobPathFor(dir, "sid", "tc1"), "utf-8")).toBe(body);
+
+      // (b) persisted index entry has spillPath + preview, NOT the full body
+      const idxEntry = entries.find((e) => e.customType === CUSTOM_TYPE_INDEX);
+      expect(idxEntry).toBeTruthy();
+      const persisted = idxEntry.data.toolCalls[0];
+      expect(persisted.spillPath).toBe(blobPathFor(dir, "sid", "tc1"));
+      expect(persisted.resultText).toBe("");
+      expect(persisted.resultPreview.length).toBeGreaterThan(0);
+      expect(persisted.contentHash).toBeTruthy();
+
+      // (c) pruneMessages emits the mechanical spill stub (no summary, no LLM)
+      const msgs = [
+        {
+          role: "toolResult",
+          toolCallId: "tc1",
+          toolName: "fetch",
+          content: [{ type: "text", text: body }],
+          isError: false,
+          timestamp: 1,
+        },
+      ];
+      const { messages: out, pruned } = pruneMessages(msgs as any, indexer);
+      expect(pruned).toBe(true);
+      expect((out[0] as any).content[0].text).toContain(blobPathFor(dir, "sid", "tc1"));
+      expect((out[0] as any).content[0].text).not.toContain("Summarized in pruner summary");
+
+      // (d) reconstruct from the persisted entries: record still resolves, hash intact
+      const indexer2 = new ToolCallIndexer();
+      const fakeCtx = { sessionManager: { getBranch: () => entries } } as any;
+      indexer2.reconstructFromSession(fakeCtx);
+      const rec = indexer2.getRecord("tc1");
+      expect(rec?.spillPath).toBe(blobPathFor(dir, "sid", "tc1"));
+      expect(indexer2.lookupByContent("fetch", body)).toBe("tc1");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/protected.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { globToRegExp, isProtected } from "./protected.js";
+
+describe("globToRegExp", () => {
+  test("** crosses path segments", () => {
+    expect(globToRegExp("**/skills/**/*.md").test("/Users/x/.agents/skills/release/SKILL.md")).toBe(true);
+    expect(globToRegExp("**/skills/**/*.md").test("a/skills/b/c/notes.md")).toBe(true);
+  });
+
+  test("**/ matches zero directories", () => {
+    expect(globToRegExp("**/SKILL.md").test("SKILL.md")).toBe(true);
+    expect(globToRegExp("**/skills/**/*.md").test("skills/foo.md")).toBe(true);
+  });
+
+  test("* and ? are segment-local", () => {
+    expect(globToRegExp("skills/*.md").test("skills/a/b.md")).toBe(false);
+    expect(globToRegExp("skills/?.md").test("skills/a.md")).toBe(true);
+    expect(globToRegExp("skills/?.md").test("skills//x.md")).toBe(false);
+  });
+
+  test("regex metacharacters in pattern are literals", () => {
+    expect(globToRegExp("a+b/(c).md").test("a+b/(c).md")).toBe(true);
+    expect(globToRegExp("a.md").test("aXmd")).toBe(false);
+  });
+
+  test("full-path anchored match", () => {
+    expect(globToRegExp("skills/a.md").test("xskills/a.md")).toBe(false);
+    expect(globToRegExp("skills/a.md").test("skills/a.md.bak")).toBe(false);
+  });
+
+  test("case-sensitive", () => {
+    expect(globToRegExp("**/SKILL.md").test("a/skill.md")).toBe(false);
+  });
+});
+
+describe("isProtected", () => {
+  const cfg = { protectedTools: ["todowrite"], protectedPaths: ["**/skills/**/*.md"] };
+
+  test("matches by tool name regardless of args", () => {
+    expect(isProtected("todowrite", undefined, cfg)).toBe(true);
+  });
+
+  test("matches by path glob", () => {
+    expect(isProtected("read", { path: "/h/skills/x/SKILL.md" }, cfg)).toBe(true);
+    expect(isProtected("read", { path: "/h/src/app.ts" }, cfg)).toBe(false);
+  });
+
+  test("backslashes normalized to forward slashes", () => {
+    expect(isProtected("read", { path: "h\\skills\\x\\SKILL.md" }, cfg)).toBe(true);
+  });
+
+  test("non-string / missing path is not protected", () => {
+    expect(isProtected("read", { path: 42 }, cfg)).toBe(false);
+    expect(isProtected("read", {}, cfg)).toBe(false);
+    expect(isProtected("read", undefined, cfg)).toBe(false);
+    expect(isProtected("read", null, cfg)).toBe(false);
+  });
+
+  test("empty config protects nothing", () => {
+    expect(isProtected("read", { path: "skills/a/SKILL.md" }, { protectedTools: [], protectedPaths: [] })).toBe(false);
+  });
+});

package/src/protected.ts

@@ -0,0 +1,51 @@
+/** Structural pick of ContextPruneConfig — keeps this module dependency-free. */
+export interface ProtectionConfig {
+  protectedTools: readonly string[];
+  protectedPaths: readonly string[];
+}
+
+// Compile-once: pattern -> RegExp is pure, so the cache never needs
+// invalidation. Patterns only come from config arrays, so growth is bounded.
+const patternCache = new Map<string, RegExp>();
+
+export function globToRegExp(pattern: string): RegExp {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+  let re = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        if (pattern[i + 2] === "/") {
+          re += "(?:[^/]*/)*"; // `**/` — zero or more whole directories
+          i += 3;
+        } else {
+          re += ".*"; // bare `**`
+          i += 2;
+        }
+      } else {
+        re += "[^/]*"; // `*` — segment-local
+        i += 1;
+      }
+    } else if (ch === "?") {
+      re += "[^/]";
+      i += 1;
+    } else {
+      re += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      i += 1;
+    }
+  }
+  const compiled = new RegExp(`^${re}$`);
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+
+export function isProtected(toolName: string, args: unknown, config: ProtectionConfig): boolean {
+  if (config.protectedTools.includes(toolName)) return true;
+  if (config.protectedPaths.length === 0) return false;
+  const path = (args as Record<string, unknown> | null | undefined)?.path;
+  if (typeof path !== "string") return false;
+  const normalized = path.replace(/\\/g, "/");
+  return config.protectedPaths.some((p) => globToRegExp(p).test(normalized));
+}