@sema-agent/core 7.16.0 → 7.17.1

package/dist/core/context-edit.d.ts

@@ -49,24 +49,14 @@ export declare const COMPACTION_TRIGGER_BUFFER_TOKENS = 13000;
  */
 export declare function contextEditFrontier(window: number): number;
 /**
- * design/374 — which CLEARING MACHINE `clearStaleToolResults` runs.
+ * The `RunnerDeps.microCompact.machine` vocabulary — ONE clearing machine, switchable:
  *
- *  - `"cc"` (default since the slice-3 flip): the CC 2.1.223 `yId` machine — keep 5, a
- *    ≥20000-token minimum-savings gate (below it the pass is a byte-identical no-op), ONE deep
- *    clear of everything beyond the keep window, the window base counts already-cleared/offloaded
- *    occurrences (they hold their keep slots), and CC's plain marker bytes.
- *  - `"legacy"`: the pre-374 sema machine, kept as the explicit compatibility opt-out — keep 3, no
- *    minimum-savings gate, incremental oldest-first clearing that STOPS once the budget is met,
- *    legacy marker bytes. In the request pipeline the opt-out also keeps the pre-374 BACKSTOP
- *    ORDER (guard trim as the ordinary second line) — see the guard-chain note in prepare-task's
- *    context hook.
- *
- * The pre-flip P-form warning (design/374 r2-B⑨/C-5: "cc" + the OLD message-dropping guard-trim
- * backstop = the 20k gate in front of the only reduction) is RESOLVED, not merely re-worded: the
- * slice-3 fallback re-ordering shipped in the same version as this default (blocking-point machine
- * re-run when the frontier pass is off → in-turn forced compaction behind the adopt seam → trim
- * demoted to the disaster-only last resort), so the default configuration never hands an
- * under-20k refusal straight to a message-dropping trim.
+ *  - `"cc"` (default): the CC 2.1.223 `yId` machine — keep 5, a ≥20000-token minimum-savings gate
+ *    (below it the pass is a byte-identical no-op), ONE deep clear of everything beyond the keep
+ *    window, the window base counts already-cleared/offloaded occurrences (they hold their keep
+ *    slots), and CC's plain marker bytes.
+ *  - `"off"`: no proactive frontier clearing; the machine gets its one shot at the blocking point
+ *    of the guard chain instead (trace trigger `"blocking"`).
  *
  * WHOLE-MACHINE CROSS-CHECK against the 2.1.250 corpus (design/374 slice 4 — the "the knob number
  * was copied, the machine was not" disease is checked by naming the machine's parts, not the one
@@ -93,39 +83,28 @@ export declare function contextEditFrontier(window: number): number;
  *      keeps a PROACTIVE frontier trigger CC's client does not have, anchored to Anthropic's
  *      platform context-management policy rather than to CC-CLI — registered divergence D-1, and
  *      re-stated at {@link clearStaleToolResults}'s ANCHOR paragraph.
+ *
+ * A closed set (`docs/CLOSED-SETS.md`): the knob door quotes it, so a word outside it is refused by
+ * name rather than folded to the default.
  */
-export type ContextEditMachine = "legacy" | "cc";
+export declare const MICRO_COMPACT_MACHINES: readonly ["off", "cc"];
+export type MicroCompactMachine = (typeof MICRO_COMPACT_MACHINES)[number];
 /**
- * How many most-recent CANDIDATE tool results keep their content when the stale-result pass runs —
- * per machine (design/374: the two values govern DIFFERENT machines, so they are separate
- * constants, not one adjudicated number):
- *
- *  - LEGACY machine (the explicit opt-out): 3. The measured objection to 5 stands FOR THIS MACHINE
- *    (probed on a 200k model, 140k usage anchor, five 36k-char Bash results: at 3 the pass clears
- *    two and lands under the 177k guard; at 5 nothing is clearable and the guard trim cannot
- *    recover the batch either) — on the legacy machine the keep window is the only lever between
- *    the frontier and the message-dropping trim, so widening it disables the whole defense in
- *    exactly the terminal-batch shape that needs it. This is why the slice-3 "keep default 3→5"
- *    flip rides the MACHINE default, not this constant: painting 5 onto the opt-out machine would
- *    recreate the probed failure inside the escape hatch.
- *  - CC machine (the default since slice 3): 5 (2.1.223 `uAp`; 2.1.250 `var k = 5` at the call site
- *    cli250.js:58375, and 2.1.245 carries the same value — zero drift across 245→250; same value
- *    again on CC 88's `timeBasedMCConfig`, i.e. stable across all three corpus generations, and it
- *    is a hard-coded constant upstream, not a setting). The #384 adjudication adopted 5
- *    CONDITIONAL on the whole machine coming with it (20k gate + deep clear + re-ordered
- *    backstops); the cc machine carries that condition, and slice 3's backstop re-ordering
- *    completed it — 5 is now the effective default keep, and the 200k probe above is answered by
- *    the machine (§3.5: the gate correctly refuses the no-win clear and the in-turn forced
- *    compaction owns the request instead of a message-dropping trim).
+ * How many most-recent CANDIDATE tool results keep their content when the stale-result pass runs:
+ * 5 (CC 2.1.223 `uAp`; 2.1.250 `var k = 5` at the call site cli250.js:58375, and 2.1.245 carries
+ * the same value — zero drift across 245→250; same value again on CC 88's `timeBasedMCConfig`, i.e.
+ * stable across all three corpus generations, and it is a hard-coded constant upstream, not a
+ * setting). The #384 adjudication adopted 5 CONDITIONAL on the whole machine coming with it (20k
+ * gate + deep clear + re-ordered backstops); the machine carries that condition (§3.5: the gate
+ * refuses a no-win clear and the in-turn forced compaction owns the request instead of a
+ * message-dropping trim).
  */
-export declare const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
 export declare const CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS = 5;
 /** design/374 §3.1 — CC's minimum-savings gate (`vUs` :397773; 2.1.250 `Mnn` cli250.js:41714, same
  *  value): the cc machine refuses to clear at
  *  all unless the structural estimate of what WOULD be cleared reaches this many tokens. Rationale
  *  (independent of "CC does it"): every clear breaks the provider prefix cache once, so a clear that
- *  saves less than the re-prefill it causes is a net loss; the gate prices that trade. The LEGACY
- *  machine has no such gate (1 token over budget clears) — that difference is machine-defining. */
+ *  saves less than the re-prefill it causes is a net loss; the gate prices that trade. */
 export declare const MIN_CLEAR_SAVINGS_TOKENS = 20000;
 /** Minimum kept results — CC `EUs` :397710 `Math.max(1, keepRecent)`. See
  *  {@link ContextEditOptions.keepRecentToolResults} for why both degenerate ends are unusable. */
@@ -133,26 +112,10 @@ export declare const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
 export interface ContextEditOptions {
     /** Start clearing once estimated context tokens exceed this. */
     budgetTokens: number;
-    /**
-     * design/374 — which clearing machine runs; see {@link ContextEditMachine}. Default `"cc"`
-     * (the slice-3 default flip); pass `"legacy"` explicitly for the pre-374 machine, byte-identical.
-     */
-    machine?: ContextEditMachine;
-    /**
-     * Mixed-configuration protection (design/374 r2-Md⑪ family): make the LEGACY machine recognize
-     * the CC marker forms as already-cleared, so a ledger-replayed CC marker is never re-cleared
-     * into a legacy marker (destroying its ref/media disclosure). Wired by the pipeline whenever a
-     * cc-minting knob is on (machine "cc" — where it is implied — or the rejection-recovery arm over
-     * a legacy frontier machine). Default false — which since the slice-3 flip is the posture of the
-     * explicit OPT-OUT machine with MC-R also off (C15; the shipped default machine is "cc", where
-     * this option is moot): in that pure opt-out, tool output that merely SPELLS the CC marker is
-     * untrusted bytes and stays clearable exactly as pre-374.
-     */
-    recognizeCcMarkers?: boolean;
     /**
      * Fired AT MOST ONCE per pass, only when the pass cleared at least one result: the cleared
-     * indexes (into the returned array) and the pass's savings estimate (cc machine: the structural
-     * minimum-savings estimate it gated on; legacy machine: the accounted structural delta). The
+     * indexes (into the returned array) and the pass's savings estimate (the structural
+     * minimum-savings estimate it gated on). The
      * request-projection ledger (design/374 §3.2.6) records cleared occurrences through this seat —
      * observation only, a throwing callback is swallowed and never fails the request build.
      */
@@ -164,9 +127,7 @@ export interface ContextEditOptions {
     }) => void;
     /**
      * Always keep the content of this many most-recent CANDIDATE tool results (candidates = results
-     * from {@link compactableTools}). Default: the selected machine's own default —
-     * {@link DEFAULT_KEEP_RECENT_TOOL_RESULTS} = 3 (legacy) / {@link CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS}
-     * = 5 (cc); see those constants for why the two machines carry different numbers.
+     * from {@link compactableTools}). Default {@link CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS} = 5.
      *
      * Floored at 1, which IS CC's rule (`EUs` `Math.max(1, keepRecent)`), whose own source note gives
      * the reason: 0 leaves the model with zero working tool context, and in CC's `slice(-0)` spelling
@@ -190,20 +151,16 @@ export interface ContextEditOptions {
         persist: (toolCallId: string, fullText: string) => string;
     };
     /**
-     * design/123 D3 (= fable-M5) — ANCHORED accounting start: `estimateContextTokens(messages,
-     * charsPerToken).tokens` for the SAME message array. When set, the trigger gate AND the internal
-     * bookkeeping start from this usage-anchored value instead of the pure structural sum (which
-     * underestimates code by ~25% and CJK by 60–75% — the defense would self-certify and pass
-     * over-window requests). Bookkeeping semantics (pinned): clearing a message AFTER the usage anchor
-     * decrements by its structural delta; clearing a message AT/BEFORE the anchor decrements ZERO —
-     * the anchor usage was billed with that content included and does not shrink on a request-view
-     * edit (the clear only pays off on the NEXT request, after a fresh anchor lands), so the defense
-     * keeps clearing deeper until the anchored total is met or nothing clearable remains.
-     * Absent ⇒ legacy structural gate + accounting (byte-identical behavior).
+     * design/123 D3 (= fable-M5) — ANCHORED trigger: `estimateContextTokens(messages,
+     * charsPerToken).tokens` for the SAME message array. When set, the trigger gate reads this
+     * usage-anchored value instead of the pure structural sum (which underestimates code by ~25% and
+     * CJK by 60–75% — the defense would self-certify and pass over-window requests). The minimum-
+     * savings gate stays CC's structural form either way (design/374 D-5). Absent ⇒ the structural
+     * sum triggers.
      */
     anchoredTotalTokens?: number;
     /** design/123 D2 — structural coefficient (`Model.charsPerToken`); default 3 (design/374 slice 4;
-     *  it was 4 before). Note this does NOT reach the cc machine's ≥20k gate, which is CC-exactly
+     *  it was 4 before). Note this does NOT reach the ≥20k gate, which is CC-exactly
      *  hard-coded to 4 — see {@link structuralClearSavings}. */
     charsPerToken?: number;
     /**
@@ -215,13 +172,11 @@ export interface ContextEditOptions {
     compactableTools?: ReadonlySet<string>;
     /**
      * design/374 (RB-212 durable half): the PRE-CAP counterpart array of `messages`, position-aligned
-     * (the pipeline's aggregate caps replace in place, never drop). When present, the CC machine
+     * (the pipeline's aggregate caps replace in place, never drop). When present, the machine
      * composes each clear's marker + offload text from `clearSource[idx]` — the same occurrence
      * bytes the cleared-projection ledger repaints the marker onto at the next session rebuild — so
      * the durable marker discloses the occurrence's REAL media and the page-back ref resolves to its
-     * real text rather than to a cap-stripped copy. Ignored by the legacy machine (its clears are
-     * request-local and correctly describe the projection they were handed — default bytes do not
-     * move). An entry that is not a tool result, or that carries a different `toolCallId` than the
+     * real text rather than to a cap-stripped copy. An entry that is not a tool result, or that carries a different `toolCallId` than the
      * target, is ignored per index (composition falls back to the projection copy — a misaligned
      * source must never mis-attribute content).
      */
@@ -240,28 +195,6 @@ export interface ContextEditOptions {
  * excluded one layer later, at `convertToLlm`, by its own three-key identity (`isSyntheticApiErrorMessage`).
  */
 export declare function dropEmptyFailureAssistants(messages: AgentMessage[]): AgentMessage[];
-/**
- * Context-editing — the lightest, safest reduction: when context exceeds the budget, replace the
- * CONTENT of older tool-result messages with a short marker, keeping the turn structure
- * (tool_call/tool_result pairing) intact; the most recent `keepRecentToolResults` CANDIDATE
- * results keep their content. Request-only and non-destructive: returns a new array, the durable
- * session keeps the full results (the request-projection ledger, not this function, is what makes
- * a clear DECISION durable across requests — see `replayClearedProjection`).
- *
- * ANCHOR (design/374 片4 re-anchoring): this proactive frontier hook is the client-side form of
- * Anthropic's PLATFORM context-management policy (`clear_tool_uses_20250919` — same
- * trigger/keep/clear-at-least construction), NOT a CC-CLI parity claim: CC 2.1.x's client
- * keep-recent clear lives exclusively on its `context_hint` REJECTION leg (default-gated off), a
- * machine whose sema form is the MC-R arm (`planRejectionClears` + the runner's recovery chain).
- * The per-mechanism CC anchors that DO hold (the COMPACTABLE_TOOLS set, the candidate-scoped keep
- * window, the floor, and the whole `machine: "cc"` clearing form) are cited at their sites.
- * (An earlier note here cited an unverified "~29% improvement" figure — removed: no first-party
- * source in the corpus; the machine's case rests on the measured mechanics, not that number.)
- *
- * Clear ORDER is machine-dependent: legacy clears oldest-first and stops at the budget; the cc
- * machine deep-clears everything beyond the keep window behind the ≥20k gate (see
- * {@link ContextEditMachine}).
- */
 export declare function clearStaleToolResults(messages: AgentMessage[], opts: ContextEditOptions): AgentMessage[];
 /** design/374 slice 1b (X5) — the resolved trigger-side window and whether the clamp repaired it. */
 export interface TriggerWindowResolution {
@@ -368,11 +301,10 @@ export type RejectionClearPlan = {
 };
 /**
  * design/374 §3.2 (slice 2) — plan the MC-R rejection clear over the REJECTED projection: the same
- * cc machine (keep 5 default, window base counts cleared occurrences, five-form exclusion, Sby
+ * machine (keep 5 default, window base counts cleared occurrences, five-form exclusion, Sby
  * savings, ≥20k gate) with the TRIGGER replaced by the rejection itself — the provider already said
- * the input does not fit, so there is no budget coordinate to compare against (which is also why an
- * enabled MC-R always runs the cc form regardless of the frontier machine knob: the legacy
- * incremental form is defined by "stop when the budget is met" and has no meaning here).
+ * the input does not fit, so there is no budget coordinate to compare against (an enabled MC-R runs
+ * even with the frontier machine `"off"`).
  * `keyOf` threads occurrence identity (the ledger is the ONLY way a rejection-arm clear survives
  * the session rebuild — §1.2's adoption chain discards the in-memory view); a candidate the index
  * cannot key is skipped from BOTH the clear set and the savings (never promise savings the ledger

package/dist/core/context-edit.js

@@ -1,11 +1,10 @@
 import { createHash } from "node:crypto";
-import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
+import { DEFAULT_CHARS_PER_TOKEN, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
 import { PERSISTED_OUTPUT_PREFIX, offloadPagebackHint } from "./tool-result-store.js";
+import { assertNoRetiredKeys } from "./retired-keys.js";
 import { compactableToolNames } from "./tool-registry.js";
-const CLEARED_MARKER = "[tool result cleared to save context]";
 const CC_CLEARED_MARKER = "[Old tool result content cleared]";
-const LEGACY_CLEARED_EXTENDED_PREFIX = "[tool result cleared to save context —";
 const CC_CLEARED_EXTENDED_PREFIX = "[Old tool result content cleared —";
 const refNote = (ref) => offloadPagebackHint(ref, "cleared");
 const mediaNote = (blocks) => {
@@ -22,10 +21,9 @@ const mediaNote = (blocks) => {
     const breakdown = [...byType].map(([t, c]) => `${c} ${t}`).join(", ");
     return `${n} attachments (${breakdown}) no longer visible after this clear`;
 };
-const clearedMarker = (notes, machine) => {
+const clearedMarker = (notes) => {
     const present = notes.filter((n) => n !== undefined);
-    const [plain, extendedPrefix] = machine === "cc" ? [CC_CLEARED_MARKER, CC_CLEARED_EXTENDED_PREFIX] : [CLEARED_MARKER, LEGACY_CLEARED_EXTENDED_PREFIX];
-    return present.length > 0 ? `${extendedPrefix} ${present.join("; ")}]` : plain;
+    return present.length > 0 ? `${CC_CLEARED_EXTENDED_PREFIX} ${present.join("; ")}]` : CC_CLEARED_MARKER;
 };
 export const EDIT_FRACTION = 0.7;
 export const CONTEXT_OUTPUT_RESERVE_TOKENS = 20000;
@@ -33,7 +31,7 @@ export const COMPACTION_TRIGGER_BUFFER_TOKENS = 13000;
 export function contextEditFrontier(window) {
     return Math.max(window - (CONTEXT_OUTPUT_RESERVE_TOKENS + COMPACTION_TRIGGER_BUFFER_TOKENS), Math.floor(window * EDIT_FRACTION));
 }
-export const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
+export const MICRO_COMPACT_MACHINES = ["off", "cc"];
 export const CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS = 5;
 export const MIN_CLEAR_SAVINGS_TOKENS = 20000;
 const MEDIA_BLOCK_SAVINGS_TOKENS = 2000;
@@ -55,16 +53,9 @@ function soleMarkerText(m) {
     const text = content[0].text;
     return typeof text === "string" ? text : undefined;
 }
-function isCleared(m, recognizeCcForms = false) {
+function isCleared(m) {
     const text = soleMarkerText(m);
-    if (text === undefined)
-        return false;
-    if (text === CLEARED_MARKER || text.startsWith(LEGACY_CLEARED_EXTENDED_PREFIX))
-        return true;
-    return recognizeCcForms && (text === CC_CLEARED_MARKER || text.startsWith(CC_CLEARED_EXTENDED_PREFIX));
-}
-function isCcCleared(m) {
-    if (isCleared(m, true))
+    if (text !== undefined && (text === CC_CLEARED_MARKER || text.startsWith(CC_CLEARED_EXTENDED_PREFIX)))
         return true;
     const content = m.content;
     if (!Array.isArray(content) || content.length === 0)
@@ -97,7 +88,7 @@ function structuralClearSavings(target) {
     }
     return saved;
 }
-function clearOneResult(target, offload, machine) {
+function clearOneResult(target, offload) {
     const rawContent = Array.isArray(target.content) ? target.content : [];
     let ref;
     if (offload) {
@@ -115,7 +106,7 @@ function clearOneResult(target, offload, machine) {
         }
     }
     const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
-    const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined], machine);
+    const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined]);
     return { ...target, content: [{ type: "text", text: marker }] };
 }
 function reportCleared(onCleared, clears, tokensSavedEstimate) {
@@ -127,18 +118,34 @@ function reportCleared(onCleared, clears, tokensSavedEstimate) {
     catch {
     }
 }
+const CONTEXT_EDIT_OPTION_KEYS = new Set([
+    "budgetTokens",
+    "onCleared",
+    "keepRecentToolResults",
+    "offload",
+    "anchoredTotalTokens",
+    "charsPerToken",
+    "compactableTools",
+    "clearSource",
+]);
+const RETIRED_CONTEXT_EDIT_OPTION_KEYS = {
+    machine: 'the pass runs one machine (the CC form); the frontier on/off switch is `RunnerDeps.microCompact.machine: "off" | "cc"`',
+    recognizeCcMarkers: "the cleared-marker forms are always recognized",
+};
 export function clearStaleToolResults(messages, opts) {
-    const cpt = opts.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
-    const machine = opts.machine ?? "cc";
-    if (machine !== "legacy" && machine !== "cc") {
-        throw new TypeError(`machine must be "legacy" | "cc" (got ${String(machine)}); omit it for the default "cc"`);
+    assertNoRetiredKeys(opts, RETIRED_CONTEXT_EDIT_OPTION_KEYS, "clearStaleToolResults option");
+    for (const key of Object.keys(opts)) {
+        if (CONTEXT_EDIT_OPTION_KEYS.has(key) || Reflect.get(opts, key) === undefined)
+            continue;
+        const replacement = RETIRED_CONTEXT_EDIT_OPTION_KEYS[key];
+        throw new TypeError(`clearStaleToolResults: option "${key}" is not one this pass reads` +
+            (replacement !== undefined ? ` — it is retired: ${replacement}` : "") +
+            `. Legal keys: ${[...CONTEXT_EDIT_OPTION_KEYS].join(", ")}. Refused rather than ignored: a silently dropped option reads to the caller as in force.`);
     }
-    const anchored = opts.anchoredTotalTokens !== undefined;
+    const cpt = opts.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
     let total;
-    let anchorIdx = -1;
-    if (anchored) {
+    if (opts.anchoredTotalTokens !== undefined) {
         total = opts.anchoredTotalTokens;
-        anchorIdx = estimateContextTokens(messages, cpt).lastUsageIndex ?? -1;
     }
     else {
         total = 0;
@@ -149,41 +156,11 @@ export function clearStaleToolResults(messages, opts) {
     if (total <= opts.budgetTokens) {
         return messages;
     }
-    if (machine === "cc") {
-        return clearStaleToolResultsCc(messages, opts);
-    }
-    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, DEFAULT_KEEP_RECENT_TOOL_RESULTS);
-    const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
-    const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m, opts.recognizeCcMarkers === true) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
-    const clearable = toolResultCandidates.slice(0, Math.max(0, toolResultCandidates.length - keep));
-    if (clearable.length === 0) {
-        return messages;
-    }
-    const out = messages.slice();
-    let current = total;
-    const clears = [];
-    let savedEstimate = 0;
-    for (const { idx, target } of clearable) {
-        if (current <= opts.budgetTokens) {
-            break;
-        }
-        const before = estimateTokens(target, cpt);
-        const cleared = clearOneResult(target, opts.offload, "legacy");
-        out[idx] = cleared;
-        clears.push({ index: idx });
-        const delta = before - estimateTokens(cleared, cpt);
-        savedEstimate += delta;
-        current -= idx > anchorIdx ? delta : 0;
-    }
-    reportCleared(opts.onCleared, clears, savedEstimate);
-    return out;
-}
-function clearStaleToolResultsCc(messages, opts) {
     const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS);
     const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
     const candidates = messages.flatMap((m, i) => isToolResult(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
     const beyondKeep = candidates.slice(0, Math.max(0, candidates.length - keep));
-    const clearable = beyondKeep.filter(({ target }) => !isCcCleared(target));
+    const clearable = beyondKeep.filter(({ target }) => !isCleared(target));
     if (clearable.length === 0) {
         return messages;
     }
@@ -196,7 +173,7 @@ function clearStaleToolResultsCc(messages, opts) {
     for (const { idx, target } of clearable) {
         const src = opts.clearSource?.[idx];
         const source = src !== undefined && isToolResult(src) && src.toolCallId === target.toolCallId ? src : target;
-        out[idx] = clearOneResult(source, opts.offload, "cc");
+        out[idx] = clearOneResult(source, opts.offload);
         clears.push({ index: idx });
     }
     reportCleared(opts.onCleared, clears, tokensSaved);
@@ -248,7 +225,7 @@ export function planRejectionClears(messages, opts) {
     const candidates = messages.flatMap((m) => (isToolResult(m) && compactable.has(m.toolName) ? [m] : []));
     const beyondKeep = candidates.slice(0, Math.max(0, candidates.length - keep));
     const clearable = beyondKeep.flatMap((m) => {
-        if (isCcCleared(m))
+        if (isCleared(m))
             return [];
         const at = opts.keyOf(m);
         return at === undefined ? [] : [{ m, at }];
@@ -260,7 +237,7 @@ export function planRejectionClears(messages, opts) {
         return { declined: "below_min_savings" };
     const cleared = clearable.map(({ m, at }) => {
         const source = at.occurrence !== undefined && isToolResult(at.occurrence) ? at.occurrence : m;
-        const clearedMsg = clearOneResult(source, opts.offload, "cc");
+        const clearedMsg = clearOneResult(source, opts.offload);
         return { key: at.key, groupCount: at.groupCount, marker: clearedMsg.content[0]?.text ?? CC_CLEARED_MARKER, fp: at.fp };
     });
     return { cleared, tokensSavedEstimate };

package/dist/core/effective-path-target.d.ts

@@ -1,7 +1,46 @@
+/**
+ * The ONE resolution of a call's EFFECTIVE PATH TARGET — the absolute path a path-targeting tool will
+ * actually open — derived from the tool's OWN declaration ({@link ToolCallPathTarget}'s `base` / `absent` /
+ * `patternParam`) rather than guessed, separately, by every fence.
+ *
+ * ## Why this module exists
+ *
+ * The permission-rule lanes resolved a call's path with one hard-coded rule (`liveCwd ?? root` for a
+ * relative spelling, "no verdict" for an absent slot) while each tool resolved its own target its own way.
+ * The three shapes that rule got wrong were all silent — a rule that names the very directory the tool
+ * reads simply never fires:
+ *
+ *  · Grep/Glob with NO `path` search the whole ROOT; the lanes read the absent slot as "no path", so a
+ *    deny on the root reached nothing;
+ *  · Glob with an ABSOLUTE `pattern` and no `path` searches the base the pattern carries
+ *    (`/proj/secret/**` ⇒ `/proj/secret`); the lanes never looked at `pattern`;
+ *  · Grep/Glob resolve a RELATIVE `path` against the ROOT (their describes say so, and both tools hand
+ *    `rootCanonical` to the resolver), while the lanes resolved it against the live `cd` — so after a
+ *    `cd` into a sibling directory the lane judged a path the tool would never open.
+ *
+ * The fix is not a fourth arm in the lanes: it is that "which base does this tool resolve against, and what
+ * does it target when the slot is empty" is a FACT OF THE TOOL, so the tool declares it once and both
+ * sides read the declaration. {@link pathTargetBaseOf} is the shared SELECTION (which base), and each side
+ * then applies its own identity to the selected base — lexical-normal here (the rule family's one path
+ * identity, zero IO), canonical (symlink-resolving, IO) inside the tool.
+ *
+ * ## What it does NOT decide
+ *
+ * Nothing here judges anything: it answers "which absolute path is this call about". Containment, the
+ * sensitive-path deny face and the rule precedence walk are unchanged and still run where they ran.
+ * `undefined` means "this call has no path this reading can locate" — the documented fail-toward-asking
+ * posture of both lanes (no refusal on the tightening side, no grant on the allow side).
+ *
+ * RepoMap shares the search tools' root-relative `path` semantics but declares NO path target at all (no
+ * rule family reaches it, and the rule grammar is derived from the catalog's path targets), so it has no
+ * declaration to read; the day it declares one, it reads the same selector as everything else.
+ */
+import { type PathFamily, type PathIdentity, type Win32NamespaceRefusal } from "../tools/fs/safety.js";
 import type { ToolCallPathTarget } from "./tool-face.js";
 import { type ToolCallLike } from "./tool-registry.js";
 /** The bases of ONE CALL a target resolves against: the task root, and the live tracked working directory
- *  (absent when no tracker moved or the caller keeps none). Facts of the call, never of the tool. */
+ *  (absent when no tracker moved or the caller keeps none). Facts of the call, never of the tool. The
+ *  tree's FAMILY is read from them once per call ({@link pathFamilyOf}). */
 export interface ToolPathBases {
     readonly root?: string | undefined;
     readonly cwd?: string | undefined;
@@ -17,22 +56,43 @@ export declare function pathTargetBaseOf(pt: Pick<ToolCallPathTarget, "base"> |
  * design/116 批④ #8 (CC 2.1.198 RWp, bundle :332987) — decompose an ABSOLUTE glob pattern into a base
  * directory + relative pattern: cut at the last separator before the first glob metachar (`* ? [ {`); a
  * pattern with no metachar splits dirname/basename. `undefined` for a relative pattern (the caller keeps it
- * as-is) or when no usable base can be derived.
+ * as-is) or when no usable base can be derived; a namespace refusal ({@link win32NamespaceScreen}, run
+ * BEFORE the metachar scan so `\\?\` is a prefix, never a `?` wildcard) is answered by its word.
+ * Absoluteness and the separator set are the FAMILY's: on a POSIX tree `C:\\x\\*` is a relative pattern.
  *
  * Lives HERE rather than beside the search engine because two readers need the identical cut: Glob's own
  * scope resolution and the path fences that must know which directory an absolute pattern really searches.
  */
-export declare function splitAbsoluteGlobPattern(pattern: string): {
+export declare function splitAbsoluteGlobPattern(pattern: string, family: PathFamily | undefined): {
     baseDir: string;
     relativePattern: string;
+} | {
+    refused: Win32NamespaceRefusal;
+} | undefined;
+/**
+ * The reading of a call's path slot under ONE declaration: `path` = the absolute target's identity; `unreadable`
+ * = the slot spells a target but the base it needs is not a usable base of this tree (fed to TIGHTENING rows
+ * only, as the ask a person clears — never to the allow arm); `refused` = a namespace refusal of the
+ * spelling itself (a rule speaks about no such spelling: no verdict, no ask — the fs throat delivers the
+ * refusal with the same word); `undefined` = no target in this reading.
+ */
+export type PathTargetReading = {
+    readonly kind: "path";
+    readonly identity: PathIdentity;
+} | {
+    readonly kind: "unreadable";
+    readonly reason: string;
+} | {
+    readonly kind: "refused";
+    readonly reason: Win32NamespaceRefusal;
 } | undefined;
 /**
- * The absolute, LEXICAL-NORMAL path this call is about under ONE reading of its path slot, or `undefined`
- * when that reading locates none. `pt` is the reading (design/388 B6/B17: the PROTECTIVE target for a
- * tightening fence, the DECLARED target for a grant) — this function never picks between the two.
+ * The absolute target this call is about under ONE reading of its path slot, as a {@link PathTargetReading}.
+ * `pt` is the reading (design/388 B6/B17: the PROTECTIVE target for a tightening fence, the DECLARED target
+ * for a grant) — this function never picks between the two.
  *
  * The order is the tool's own:
- *  ① a spelling in the slot wins — absolute as spelled, relative against {@link pathTargetBaseOf}'s base;
+ *  ① a spelling in the slot wins — fully qualified as spelled, otherwise against {@link pathTargetBaseOf}'s base;
  *  ② otherwise, when the declaration says an absent slot means `none`, the call is about no path;
  *  ③ otherwise a `patternParam`'s ABSOLUTE pattern supplies its own base directory;
  *  ④ otherwise the base itself (the tool searches all of it).
@@ -40,4 +100,4 @@ export declare function splitAbsoluteGlobPattern(pattern: string): {
  * A base the deployment did not supply yields `undefined`: a relative spelling with nothing to resolve
  * against names no file, and claiming it names `/<spelling>` was a fabrication no fence should judge.
  */
-export declare function effectivePathTargetOf(call: ToolCallLike, pt: ToolCallPathTarget | undefined, bases: ToolPathBases): string | undefined;
+export declare function effectivePathTargetOf(call: ToolCallLike, pt: ToolCallPathTarget | undefined, bases: ToolPathBases): PathTargetReading;

package/dist/core/effective-path-target.js

@@ -1,34 +1,26 @@
-import { isAbsolutePathForm } from "../tools/fs/safety.js";
-import { lexicalNormalAbsolutePathOf } from "./permission-rule-model.js";
+import { isAbsoluteForFamily, joinForFamily, pathFamilyOf, pathIdentityOf, win32NamespaceScreen } from "../tools/fs/safety.js";
 import { pathTargetValue } from "./tool-registry.js";
 export function pathTargetBaseOf(pt, bases) {
     return (pt?.base ?? "cwd") === "root" ? bases.root : (bases.cwd ?? bases.root);
 }
-export function splitAbsoluteGlobPattern(pattern) {
-    if (!isAbsolutePathForm(pattern))
+export function splitAbsoluteGlobPattern(pattern, family) {
+    const screened = win32NamespaceScreen(pattern, family);
+    if (!screened.ok)
+        return { refused: screened.refuse };
+    const spelled = screened.spelled;
+    if (!isAbsoluteForFamily(family, spelled))
         return undefined;
-    const m = /[*?[{]/.exec(pattern);
-    if (!m) {
-        const i = Math.max(pattern.lastIndexOf("/"), pattern.lastIndexOf("\\"));
-        if (i <= 0)
-            return undefined;
-        return { baseDir: pattern.slice(0, i), relativePattern: pattern.slice(i + 1) };
-    }
-    const prefix = pattern.slice(0, m.index);
-    const cut = Math.max(prefix.lastIndexOf("/"), prefix.lastIndexOf("\\"));
-    if (cut === -1)
+    const lastSep = (s) => (family === "win" ? Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\")) : s.lastIndexOf("/"));
+    const m = /[*?[{]/.exec(spelled);
+    const cut = m ? lastSep(spelled.slice(0, m.index)) : lastSep(spelled);
+    if (cut <= 0 && (m === null || cut === -1))
         return undefined;
-    let baseDir = pattern.slice(0, cut);
-    if (baseDir === "" && cut === 0)
+    let baseDir = spelled.slice(0, cut);
+    if (baseDir === "")
         baseDir = "/";
     if (/^[A-Za-z]:$/.test(baseDir))
-        baseDir = baseDir + pattern[cut];
-    if (!baseDir)
-        return undefined;
-    return { baseDir, relativePattern: pattern.slice(cut + 1) };
-}
-function under(base, rest) {
-    return `${base === "/" ? "" : base}/${rest}`;
+        baseDir = baseDir + spelled[cut];
+    return { baseDir, relativePattern: spelled.slice(cut + 1) };
 }
 export function effectivePathTargetOf(call, pt, bases) {
     if (pt === undefined)
@@ -41,16 +33,36 @@ export function effectivePathTargetOf(call, pt, bases) {
         return undefined;
     if (pt.patternParam !== undefined) {
         const pattern = pathTargetValue(call.args, { param: pt.patternParam });
-        const split = pattern === undefined ? undefined : splitAbsoluteGlobPattern(pattern);
+        const split = pattern === undefined ? undefined : splitAbsoluteGlobPattern(pattern, pathFamilyOf(bases));
+        if (split !== undefined && "refused" in split)
+            return { kind: "refused", reason: split.refused };
         if (split !== undefined)
             return resolveSpelling(split.baseDir, declaredBase, bases);
     }
-    return declaredBase === undefined ? undefined : lexicalNormalAbsolutePathOf(declaredBase);
+    if (declaredBase === undefined)
+        return undefined;
+    const family = pathFamilyOf(bases);
+    return isAbsoluteForFamily(family, declaredBase) ? readingOf(pathIdentityOf(declaredBase, family, bases.root ?? bases.cwd)) : unreadableBase(declaredBase);
 }
 function resolveSpelling(spelled, declaredBase, bases) {
-    if (spelled.startsWith("/"))
-        return lexicalNormalAbsolutePathOf(spelled);
-    const landsOn = isAbsolutePathForm(spelled) ? pathTargetBaseOf(undefined, bases) : declaredBase;
-    const normalBase = landsOn === undefined ? undefined : lexicalNormalAbsolutePathOf(landsOn);
-    return normalBase === undefined ? undefined : lexicalNormalAbsolutePathOf(under(normalBase, spelled));
+    const family = pathFamilyOf(bases);
+    const screened = win32NamespaceScreen(spelled, family);
+    if (!screened.ok)
+        return { kind: "refused", reason: screened.refuse };
+    const tree = bases.root ?? bases.cwd;
+    if (isAbsoluteForFamily(family, screened.spelled))
+        return readingOf(pathIdentityOf(screened.spelled, family, tree));
+    if (declaredBase === undefined || family === undefined)
+        return undefined;
+    if (!isAbsoluteForFamily(family, declaredBase))
+        return unreadableBase(declaredBase);
+    return readingOf(pathIdentityOf(joinForFamily(family, declaredBase, screened.spelled), family, tree));
+}
+function readingOf(r) {
+    if (r.ok)
+        return { kind: "path", identity: r.identity };
+    return r.reason === "relative" || r.reason === "unanchored" ? undefined : { kind: "refused", reason: r.reason };
+}
+function unreadableBase(base) {
+    return { kind: "unreadable", reason: `the base this call resolves against (${JSON.stringify(base)}) is not a fully-qualified path of this tree's family` };
 }