@cortexkit/pi-magic-context 0.34.2 → 0.35.0

package/dist/{index-fw42dv6t.js → index-xbk9epe8.js}

@@ -147885,6 +147885,521 @@ function readRawSessionTailFromDb(db, sessionId, baseOrdinal, anchorMessageId) {
   return { messages, absoluteMessageCount: Math.max(0, ord - 1) };
 }
 
+// ../plugin/src/shared/record-type-guard.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ../plugin/src/hooks/magic-context/read-session-true-raw-tokens.ts
+function completedToolArcCrossesBoundary(invOrdinal, resOrdinal, boundary) {
+  return invOrdinal < boundary && boundary <= resOrdinal;
+}
+var MAX_MESSAGE_CACHE_ENTRIES = 1e5;
+var MAX_MESSAGE_CACHE_KEY_BYTES = 64 * 1024 * 1024;
+var FNV1A_32_OFFSET = 2166136261;
+var FNV1A_32_PRIME = 16777619;
+var messageEstimateCache = new Map;
+var messageEstimateCacheBytes = 0;
+var EMPTY_BREAKDOWN = {
+  text: 0,
+  reasoning: 0,
+  toolInput: 0,
+  toolOutput: 0,
+  image: 0,
+  other: 0,
+  total: 0
+};
+function addBreakdown(target, kind, value) {
+  if (kind === "total")
+    return;
+  const safeValue = Number.isFinite(value) && value > 0 ? Math.round(value) : 0;
+  target[kind] += safeValue;
+  target.total += safeValue;
+}
+function estimateStructured(value) {
+  if (typeof value === "string")
+    return estimateTokens(value);
+  if (value === undefined || value === null)
+    return 0;
+  return estimateTokens(stableStringify(value));
+}
+function firstStringField(record, fields) {
+  for (const field of fields) {
+    const value = record[field];
+    if (typeof value === "string" && value.length > 0)
+      return value;
+  }
+  return null;
+}
+function stringValue(value) {
+  if (typeof value === "string")
+    return value;
+  if (value === undefined || value === null)
+    return "";
+  return stableStringify(value);
+}
+function textFromToolResultContent(content) {
+  if (typeof content === "string")
+    return content;
+  if (Array.isArray(content)) {
+    const pieces = [];
+    for (const entry of content) {
+      if (typeof entry === "string") {
+        pieces.push(entry);
+      } else if (isRecord(entry)) {
+        const text = firstStringField(entry, ["text", "content", "value"]);
+        pieces.push(text ?? stableStringify(entry));
+      } else if (entry !== null && entry !== undefined) {
+        pieces.push(String(entry));
+      }
+    }
+    return pieces.join(`
+`);
+  }
+  return stringValue(content);
+}
+function looksImageLike(part) {
+  const type = typeof part.type === "string" ? part.type.toLowerCase() : "";
+  const mime = typeof part.mime === "string" ? part.mime.toLowerCase() : "";
+  const mediaType = typeof part.mediaType === "string" ? part.mediaType.toLowerCase() : "";
+  return type.includes("image") || mime.startsWith("image/") || mediaType.startsWith("image/") || part.image_url !== undefined || part.imageUrl !== undefined || part.image !== undefined;
+}
+function defaultImageTokenHeuristic(part) {
+  if (isRecord(part)) {
+    const width = part.width;
+    const height = part.height;
+    if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
+      return Math.max(256, Math.min(4096, Math.ceil(width * height / 750)));
+    }
+  }
+  return 1024;
+}
+function partType(part) {
+  return typeof part.type === "string" ? part.type : "";
+}
+function hasOwn(record, key) {
+  return Object.hasOwn(record, key);
+}
+function recursiveByteLength(value) {
+  if (value === null || value === undefined)
+    return 0;
+  if (typeof value === "string")
+    return value.length;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value).length;
+  }
+  if (Array.isArray(value)) {
+    return value.reduce((sum, item) => sum + recursiveByteLength(item), value.length);
+  }
+  if (isRecord(value)) {
+    let total = Object.keys(value).length;
+    for (const [key, child] of Object.entries(value)) {
+      total += key.length + recursiveByteLength(child);
+    }
+    return total;
+  }
+  return String(value).length;
+}
+function updateFnv1a32(hash, text) {
+  let next = hash;
+  for (let index = 0;index < text.length; index += 1) {
+    next ^= text.charCodeAt(index);
+    next = Math.imul(next, FNV1A_32_PRIME) >>> 0;
+  }
+  return next;
+}
+function contentStringsHash(fields) {
+  let hash = FNV1A_32_OFFSET;
+  for (const field of fields) {
+    hash = updateFnv1a32(hash, `${field.length}:`);
+    hash = updateFnv1a32(hash, field);
+    hash = updateFnv1a32(hash, "\x00");
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+function rawPartVersion(part) {
+  return part.__magicContextPartUpdatedAt ?? part.updated_at ?? part.updatedAt ?? part.version ?? part.revision ?? "";
+}
+function callIdFromPart(part) {
+  const direct = firstStringField(part, ["callID", "callId", "toolCallId", "tool_call_id", "id"]);
+  if (direct)
+    return direct;
+  const state = isRecord(part.state) ? part.state : null;
+  return state ? firstStringField(state, ["callID", "callId", "toolCallId", "tool_call_id", "id"]) ?? "" : "";
+}
+function toolSignalFromPart(part) {
+  if (!isRecord(part))
+    return null;
+  const type = partType(part);
+  const state = isRecord(part.state) ? part.state : null;
+  const callId = callIdFromPart(part);
+  if (!callId && type !== "tool")
+    return null;
+  if (type === "tool") {
+    const hasInput = state !== null && hasOwn(state, "input");
+    const outputKey = state ? hasOwn(state, "output") ? "output" : hasOwn(state, "error") ? "error" : hasOwn(state, "result") ? "result" : null : null;
+    const hasOutput = outputKey !== null;
+    const outputValue = outputKey && state ? state[outputKey] : undefined;
+    const providerExecuted = part.providerExecuted === true;
+    const openInvocation = !providerExecuted && !hasOutput;
+    return {
+      callId,
+      hasInput: hasInput || openInvocation,
+      hasOutput,
+      inputText: hasInput && state ? stringValue(state.input) : "",
+      outputText: hasOutput ? stringValue(outputValue) : ""
+    };
+  }
+  if (type === "tool-invocation") {
+    const args = part.args ?? part.input;
+    return {
+      callId,
+      hasInput: args !== undefined,
+      hasOutput: false,
+      inputText: args !== undefined ? stringValue(args) : "",
+      outputText: ""
+    };
+  }
+  if (type === "tool_use") {
+    const input = part.input;
+    return {
+      callId,
+      hasInput: input !== undefined,
+      hasOutput: false,
+      inputText: input !== undefined ? stringValue(input) : "",
+      outputText: ""
+    };
+  }
+  if (type === "tool_result") {
+    const content = part.content ?? part.output ?? part.result;
+    return {
+      callId,
+      hasInput: false,
+      hasOutput: content !== undefined,
+      inputText: "",
+      outputText: content !== undefined ? textFromToolResultContent(content) : ""
+    };
+  }
+  return null;
+}
+function partCheapFingerprint(part) {
+  if (!isRecord(part))
+    return `${typeof part}:${recursiveByteLength(part)}`;
+  const version = rawPartVersion(part);
+  const type = typeof part.type === "string" ? part.type : "";
+  return `${type}:${String(version)}:${recursiveByteLength(part)}`;
+}
+function messageCacheKey(message, options) {
+  const namespace = "cacheNamespace" in options ? options.cacheNamespace : "estimate";
+  const cheapFingerprint = message.parts.map(partCheapFingerprint).join("|");
+  return [
+    namespace,
+    options.providerShapeVersion,
+    message.id || `ordinal:${message.ordinal}`,
+    message.role,
+    message.parts.length,
+    cheapFingerprint
+  ].join("\x00");
+}
+function setCachedEstimate(key, breakdown) {
+  const keyEstimateBytes = key.length * 2 + 64;
+  const existing = messageEstimateCache.get(key);
+  if (existing)
+    messageEstimateCacheBytes -= existing.keyEstimateBytes;
+  messageEstimateCache.set(key, { breakdown, keyEstimateBytes });
+  messageEstimateCacheBytes += keyEstimateBytes;
+  while (messageEstimateCache.size > MAX_MESSAGE_CACHE_ENTRIES || messageEstimateCacheBytes > MAX_MESSAGE_CACHE_KEY_BYTES) {
+    const first = messageEstimateCache.keys().next().value;
+    if (typeof first !== "string")
+      break;
+    const removed = messageEstimateCache.get(first);
+    if (removed)
+      messageEstimateCacheBytes -= removed.keyEstimateBytes;
+    messageEstimateCache.delete(first);
+  }
+}
+function cloneBreakdown(value) {
+  return { ...value };
+}
+function estimateNonToolPart(part, options, breakdown) {
+  if (!isRecord(part)) {
+    if (part !== null && part !== undefined)
+      addBreakdown(breakdown, "other", estimateStructured(part));
+    return true;
+  }
+  const type = partType(part);
+  if (type === "step-start" || type === "step-finish" || type === "meta" && Object.keys(part).length <= 1) {
+    return true;
+  }
+  if (type === "text") {
+    const text = firstStringField(part, ["text", "content"]);
+    if (text)
+      addBreakdown(breakdown, "text", estimateTokens(text));
+    return true;
+  }
+  if (type === "reasoning" || type === "thinking" || type === "redacted_thinking") {
+    const text = firstStringField(part, ["thinking", "text", "content", "reasoning"]);
+    if (text) {
+      addBreakdown(breakdown, "reasoning", estimateTokens(text));
+    } else {
+      addBreakdown(breakdown, "other", estimateStructured(part));
+    }
+    return true;
+  }
+  const reasoningText = firstStringField(part, ["thinking", "reasoning"]);
+  if (reasoningText && type.length === 0) {
+    addBreakdown(breakdown, "reasoning", estimateTokens(reasoningText));
+    return true;
+  }
+  if (looksImageLike(part)) {
+    addBreakdown(breakdown, "image", options.imageTokenHeuristic?.(part) ?? defaultImageTokenHeuristic(part));
+    const altText = firstStringField(part, ["alt", "text", "description"]);
+    if (altText)
+      addBreakdown(breakdown, "text", estimateTokens(altText));
+    return true;
+  }
+  if (type.includes("file") || type === "source") {
+    const content = firstStringField(part, ["content", "text", "source"]);
+    if (content)
+      addBreakdown(breakdown, "text", estimateTokens(content));
+    else
+      addBreakdown(breakdown, "other", estimateStructured(part));
+    return true;
+  }
+  return false;
+}
+function estimateTrueRawMessageTokens(message, options) {
+  const breakdown = cloneBreakdown(EMPTY_BREAKDOWN);
+  const countedInput = new Set;
+  const countedOutput = new Set;
+  let ordinalToolIndex = 0;
+  for (const part of message.parts) {
+    const signal = toolSignalFromPart(part);
+    if (signal) {
+      const localKey = `${signal.callId || "tool"}:${message.ordinal}:${ordinalToolIndex}`;
+      ordinalToolIndex += 1;
+      if (signal.hasInput) {
+        const key = `${signal.callId}:input:${message.ordinal}`;
+        if (!countedInput.has(key)) {
+          countedInput.add(key);
+          addBreakdown(breakdown, "toolInput", estimateTokens(signal.inputText));
+        }
+      }
+      if (signal.hasOutput) {
+        const key = `${signal.callId}:output:${message.ordinal}:${localKey}`;
+        if (!countedOutput.has(key)) {
+          countedOutput.add(key);
+          addBreakdown(breakdown, "toolOutput", estimateTokens(signal.outputText));
+        }
+      }
+      continue;
+    }
+    if (!estimateNonToolPart(part, options, breakdown)) {
+      addBreakdown(breakdown, "other", estimateStructured(part));
+    }
+  }
+  return breakdown;
+}
+function buildToolArcs(messages) {
+  const openQueues = new Map;
+  const arcs = [];
+  for (const message of messages) {
+    for (const part of message.parts) {
+      const signal = toolSignalFromPart(part);
+      if (!signal || signal.callId.length === 0)
+        continue;
+      if (signal.hasInput && signal.hasOutput) {
+        arcs.push({
+          callId: signal.callId,
+          invOrdinal: message.ordinal,
+          resOrdinal: message.ordinal
+        });
+        continue;
+      }
+      if (signal.hasInput) {
+        const queue = openQueues.get(signal.callId) ?? [];
+        queue.push(message.ordinal);
+        openQueues.set(signal.callId, queue);
+        continue;
+      }
+      if (signal.hasOutput) {
+        const queue = openQueues.get(signal.callId) ?? [];
+        const invOrdinal = queue.shift();
+        if (queue.length === 0)
+          openQueues.delete(signal.callId);
+        else
+          openQueues.set(signal.callId, queue);
+        if (invOrdinal !== undefined) {
+          arcs.push({ callId: signal.callId, invOrdinal, resOrdinal: message.ordinal });
+        }
+      }
+    }
+  }
+  for (const [callId, queue] of openQueues) {
+    for (const invOrdinal of queue) {
+      arcs.push({ callId, invOrdinal, resOrdinal: null });
+    }
+  }
+  return arcs.sort((a, b) => a.invOrdinal - b.invOrdinal || (a.resOrdinal ?? Number.MAX_SAFE_INTEGER) - (b.resOrdinal ?? Number.MAX_SAFE_INTEGER));
+}
+function fenceBoundaryForToolArcs(candidate, arcs, lastCompartmentEndOrdinal, recentOpenArcCutoff) {
+  let boundary = candidate;
+  for (const arc of arcs) {
+    if (arc.resOrdinal !== null) {
+      if (completedToolArcCrossesBoundary(arc.invOrdinal, arc.resOrdinal, boundary)) {
+        boundary = arc.resOrdinal + 1;
+      }
+      continue;
+    }
+    if (arc.invOrdinal < recentOpenArcCutoff)
+      continue;
+    if (arc.invOrdinal >= lastCompartmentEndOrdinal + 1 && arc.invOrdinal < boundary) {
+      return arc.invOrdinal;
+    }
+    if (arc.invOrdinal >= boundary) {
+      return arc.invOrdinal;
+    }
+  }
+  return boundary;
+}
+function tokenForMessage(message, options) {
+  const key = messageCacheKey(message, options);
+  const cached = messageEstimateCache.get(key);
+  if (cached)
+    return cloneBreakdown(cached.breakdown);
+  const breakdown = estimateTrueRawMessageTokens(message, options);
+  setCachedEstimate(key, breakdown);
+  return cloneBreakdown(breakdown);
+}
+function buildTrueRawTokenIndex(sessionId, messages, options) {
+  const ordered = [...messages].sort((a, b) => a.ordinal - b.ordinal);
+  const sliceCount = ordered.length;
+  const firstOrdinal = ordered.length > 0 ? ordered[0].ordinal : 1;
+  const terminalOrdinal = ordered.length > 0 ? ordered[ordered.length - 1].ordinal : 0;
+  const rawMessageCount = Math.max(sliceCount, terminalOrdinal, options.absoluteMessageCount ?? sliceCount);
+  const ordinalSpan = terminalOrdinal >= firstOrdinal ? terminalOrdinal - firstOrdinal + 1 : 0;
+  const tokensByOrdinal = new Map;
+  const idsByOrdinal = new Map;
+  const prefix = new Array(ordinalSpan + 1).fill(0);
+  for (const message of ordered) {
+    const stored = options.storedTotalForMessage?.(message);
+    const total = stored !== undefined && stored !== null ? stored : tokenForMessage(message, options).total;
+    tokensByOrdinal.set(message.ordinal, total);
+    idsByOrdinal.set(message.ordinal, message.id);
+    const relative = message.ordinal - firstOrdinal + 1;
+    if (relative >= 1 && relative <= ordinalSpan) {
+      prefix[relative] = total;
+    }
+  }
+  for (let k = 1;k <= ordinalSpan; k += 1) {
+    prefix[k] += prefix[k - 1];
+  }
+  const ordinalToIndex = (ordinal) => Math.max(0, Math.min(ordinalSpan, ordinal - firstOrdinal));
+  return {
+    sessionId,
+    providerShapeVersion: options.providerShapeVersion,
+    rawMessageCount,
+    tokenForOrdinal(ordinal) {
+      return tokensByOrdinal.get(ordinal) ?? 0;
+    },
+    messageIdAtOrdinal(ordinal) {
+      return idsByOrdinal.get(ordinal) ?? null;
+    },
+    suffixTokensFromOrdinal(ordinal) {
+      if (ordinal <= firstOrdinal)
+        return prefix[ordinalSpan];
+      if (ordinal > terminalOrdinal)
+        return 0;
+      return prefix[ordinalSpan] - prefix[ordinalToIndex(ordinal)];
+    },
+    rangeTokens(startInclusive, endExclusive) {
+      const start = Math.max(firstOrdinal, startInclusive);
+      const end = Math.max(start, Math.min(terminalOrdinal + 1, endExclusive));
+      return prefix[end - firstOrdinal] - prefix[start - firstOrdinal];
+    },
+    findSuffixStartForTokens(tokens) {
+      if (!Number.isFinite(tokens) || tokens <= 0)
+        return terminalOrdinal + 1;
+      const target = Math.max(0, Math.floor(tokens));
+      const total = prefix[ordinalSpan];
+      if (total < target)
+        return firstOrdinal;
+      const cut = total - target;
+      let lo = 0;
+      let hi = ordinalSpan;
+      let best = 0;
+      while (lo <= hi) {
+        const mid = lo + hi >> 1;
+        if (prefix[mid] <= cut) {
+          best = mid;
+          lo = mid + 1;
+        } else {
+          hi = mid - 1;
+        }
+      }
+      return firstOrdinal + best;
+    },
+    findHeadEndForCap(startInclusive, endExclusive, capTokens) {
+      const start = Math.max(firstOrdinal, Math.min(terminalOrdinal + 1, startInclusive));
+      const end = Math.max(start, Math.min(terminalOrdinal + 1, endExclusive));
+      if (!Number.isFinite(capTokens) || capTokens <= 0)
+        return start;
+      const startIndex = start - firstOrdinal;
+      const endIndex = end - firstOrdinal;
+      const cut = prefix[startIndex] + Math.floor(capTokens);
+      let lo = startIndex + 1;
+      let hi = endIndex;
+      let bestEndIndex = startIndex;
+      while (lo <= hi) {
+        const mid = lo + hi >> 1;
+        if (prefix[mid] <= cut) {
+          bestEndIndex = mid;
+          lo = mid + 1;
+        } else {
+          hi = mid - 1;
+        }
+      }
+      let bestEnd = firstOrdinal + bestEndIndex;
+      if (bestEnd === start && start < end)
+        bestEnd = start + 1;
+      return Math.min(bestEnd, end);
+    }
+  };
+}
+function partContentFingerprint(part) {
+  if (!isRecord(part))
+    return `${typeof part}:${recursiveByteLength(part)}`;
+  const tool = toolSignalFromPart(part);
+  if (tool) {
+    return contentStringsHash([tool.inputText, tool.outputText]);
+  }
+  const text = firstStringField(part, ["text", "thinking", "reasoning", "content", "url"]) ?? "";
+  return contentStringsHash([text]);
+}
+function computeRawRangeFingerprint(messages, startInclusive, endExclusive) {
+  const pieces = [];
+  for (const message of messages) {
+    if (message.ordinal < startInclusive || message.ordinal >= endExclusive)
+      continue;
+    const partFingerprint = message.parts.map(partContentFingerprint).join(",");
+    pieces.push(`${message.ordinal}:${message.id}:${message.parts.length}:${partFingerprint}`);
+  }
+  return pieces.join("|");
+}
+function invalidateTrueRawTokenCache(args) {
+  const sessionNeedle = args.sessionId ? `${args.sessionId}` : null;
+  const messageNeedle = args.messageId ? `\x00${args.messageId}\x00` : null;
+  for (const [key, value] of messageEstimateCache) {
+    const sessionMatches = sessionNeedle === null || key.includes(sessionNeedle);
+    const messageMatches = messageNeedle === null || key.includes(messageNeedle);
+    if (sessionMatches && messageMatches) {
+      messageEstimateCache.delete(key);
+      messageEstimateCacheBytes -= value.keyEstimateBytes;
+    }
+  }
+  args.reason;
+}
+
 // ../plugin/src/hooks/magic-context/tag-content-primitives.ts
 var encoder = new TextEncoder;
 var TAG_PREFIX_REGEX = /^(?:§\d+§\s*)+/;
@@ -147957,11 +148472,6 @@ function isFilePart(part) {
   return p.type === "file" && typeof p.url === "string";
 }
 
-// ../plugin/src/shared/record-type-guard.ts
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 // ../plugin/src/hooks/magic-context/edit-marker.ts
 var TRUNCATION_SENTINEL = "...[truncated]";
 var EDIT_REGION_HINT_LEN = 40;
@@ -148402,6 +148912,7 @@ function readSessionChunk(sessionId, tokenBudget, offset = 1, eligibleEndOrdinal
       toolOnlyRanges.push({ start: range.start, end: range.end });
     }
   }
+  const completedToolArcs = buildToolArcs(messages).flatMap((arc) => arc.resOrdinal === null ? [] : [{ start: arc.invOrdinal, end: arc.resOrdinal }]);
   return {
     startIndex: startOrdinal,
     endIndex: lastOrdinal,
@@ -148414,7 +148925,8 @@ function readSessionChunk(sessionId, tokenBudget, offset = 1, eligibleEndOrdinal
 `),
     lines: lineMeta,
     commitClusterCount: commitClusters,
-    toolOnlyRanges
+    toolOnlyRanges,
+    completedToolArcs
   };
 }
 
@@ -151064,6 +151576,275 @@ function isTodoItem(value) {
   return typeof todo.content === "string" && isTodoStatus(todo.status) && (todo.priority === undefined || isTodoPriority(todo.priority));
 }
 
+// ../plugin/src/shared/prompt-surface-runtime.ts
+import { existsSync as existsSync7, readFileSync as readFileSync6, statSync as statSync5 } from "node:fs";
+import { dirname as dirname3, isAbsolute as isAbsolute2, resolve } from "node:path";
+
+// ../plugin/src/tools/light-descriptions.ts
+var CTX_REDUCE_LIGHT_DESCRIPTION = `For ctx_reduce users, mark spent §N§ outputs discardable; release is QUEUED, not immediate, so content stays visible until space is needed. Newest tags stay protected until they age out. Released content becomes a placeholder; recover it only by rerunning the source or recovery tool, so mark only genuinely finished material. Mark analyzed, redundant, persisted, or merely confirmatory outputs; keep user messages, unresolved errors, unextracted evidence, and exact wording. NEVER blanket-mark a large range: review every tag first.`;
+var CTX_EXPAND_LIGHT_DESCRIPTION = `For ctx_expand users, recover compacted conversation by passing a session-history heading's inclusive start/end ordinals. Results are raw [N] U:/A: transcript capped near 15K tokens; oversized ranges return the head and a continuation. Use verbose=true to list each message ordinal, part previews, and tool-output sizes; use message=N for one complete stored message and its tool exchanges. NEVER expand ranges after the last compartment because that live tail is already visible.`;
+var CTX_NOTE_LIGHT_DESCRIPTION = `For ctx_note users, write saves, read lists, update changes, and dismiss retires future session notes; surface_condition creates a smart note. For smart notes, NEVER use a condition tied to this conversation or an unobservable future action because the background checker can inspect only external GitHub, disk, git, or web signals.`;
+var CTX_MEMORY_LIGHT_DESCRIPTION = `For ctx_memory users, write one standalone durable fact with category and content; update one ID, archive one or more IDs, merge two or more IDs, or get one to twenty numeric IDs. get reads memories in every status; list remains dreamer-only, so primary agents must NEVER assume bulk-list access.`;
+var CTX_SEARCH_LIGHT_DESCRIPTION = `For ctx_search users, retrieve only hidden recall: memories not already in <project-memory>, compacted messages outside the live tail, commits, and notes. Omit sources for broad search; select memory, message, git_commit, or note to target a source, or pass memory IDs to bypass text search. Message hits continue through ctx_expand.`;
+
+// ../plugin/src/shared/jsonc-parser.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "node:fs";
+function stripJsonComments(content) {
+  let result = "";
+  let inString = false;
+  let escaped = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+  for (let index = 0;index < content.length; index += 1) {
+    const char = content[index];
+    const next = content[index + 1];
+    if (inLineComment) {
+      if (char === `
+`) {
+        inLineComment = false;
+        result += char;
+      }
+      continue;
+    }
+    if (inBlockComment) {
+      if (char === "*" && next === "/") {
+        inBlockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (inString) {
+      result += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      result += char;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      inLineComment = true;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      inBlockComment = true;
+      index += 1;
+      continue;
+    }
+    result += char;
+  }
+  return result;
+}
+function detectConfigFile(basePath) {
+  const jsoncPath = `${basePath}.jsonc`;
+  const jsonPath = `${basePath}.json`;
+  if (existsSync6(jsoncPath)) {
+    return { format: "jsonc", path: jsoncPath };
+  }
+  if (existsSync6(jsonPath)) {
+    return { format: "json", path: jsonPath };
+  }
+  return { format: "none", path: jsoncPath };
+}
+
+// ../plugin/src/shared/prompt-surface.ts
+function isValidPromptSurfaceModelKey(key) {
+  if (key.length === 0 || key.trim() !== key)
+    return false;
+  const slash = key.indexOf("/");
+  if (slash <= 0 || slash === key.length - 1)
+    return false;
+  const provider = key.slice(0, slash);
+  const modelID = key.slice(slash + 1);
+  if (provider.trim() !== provider || modelID.trim() !== modelID || provider.includes("*") || modelID.includes("*") && modelID !== "*") {
+    return false;
+  }
+  if (modelID === "*")
+    return true;
+  return modelID.length > 0 && !modelID.startsWith("/") && !modelID.endsWith("/") && !modelID.includes("//");
+}
+function modelKeyLookupOrder(modelKey) {
+  if (!modelKey)
+    return [];
+  const slash = modelKey.indexOf("/");
+  if (slash <= 0 || slash === modelKey.length - 1)
+    return [];
+  const provider = modelKey.slice(0, slash);
+  let modelID = modelKey.slice(slash + 1);
+  const candidates = [];
+  while (modelID.length > 0) {
+    candidates.push({ key: `${provider}/${modelID}`, source: "exact" });
+    candidates.push({ key: modelID, source: "bare" });
+    const lastDash = modelID.lastIndexOf("-");
+    if (lastDash <= 0)
+      break;
+    modelID = modelID.slice(0, lastDash);
+  }
+  candidates.push({ key: `${provider}/*`, source: "wildcard" });
+  const seen = new Set;
+  return candidates.filter((candidate) => {
+    if (seen.has(candidate.key))
+      return false;
+    seen.add(candidate.key);
+    return true;
+  });
+}
+function resolveModelConfigValue(values, modelKey) {
+  if (!values)
+    return;
+  for (const candidate of modelKeyLookupOrder(modelKey)) {
+    const value = values[candidate.key];
+    if (value !== undefined) {
+      return { value, source: candidate.source };
+    }
+  }
+  return;
+}
+function resolvePromptSurface(config, modelKey) {
+  const fallback = config?.default ?? "full";
+  const match = resolveModelConfigValue(config?.models, modelKey);
+  if (match && match.source !== "bare") {
+    return { preset: match.value, source: match.source };
+  }
+  return { preset: fallback, source: "default" };
+}
+function resolveModelConfigOrDefault(values, modelKey, fallback) {
+  return resolveModelConfigValue(values, modelKey)?.value ?? fallback;
+}
+
+// ../plugin/src/shared/prompt-surface-runtime.ts
+var GUIDANCE_MARKER = "## Magic Context";
+var GUIDANCE_MARKER_LINE = /^## Magic Context[\t ]*\r?$/gm;
+var PROMPT_SURFACE_TOOL_IDS = [
+  "ctx_reduce",
+  "ctx_expand",
+  "ctx_note",
+  "ctx_memory",
+  "ctx_search"
+];
+var LIGHT_TOOL_DESCRIPTIONS = {
+  ctx_reduce: CTX_REDUCE_LIGHT_DESCRIPTION,
+  ctx_expand: CTX_EXPAND_LIGHT_DESCRIPTION,
+  ctx_note: CTX_NOTE_LIGHT_DESCRIPTION,
+  ctx_memory: CTX_MEMORY_LIGHT_DESCRIPTION,
+  ctx_search: CTX_SEARCH_LIGHT_DESCRIPTION
+};
+function promptSurfaceHashMaterial(systemContent, preset = "full") {
+  return preset === "full" ? systemContent : `${systemContent}
+\x00magic-context-prompt-surface:${preset}`;
+}
+var PROMPT_SURFACE_TOOL_ID_SET = new Set(PROMPT_SURFACE_TOOL_IDS);
+function resolveUserConfigDirectory(options) {
+  if (options.userConfigDirectory)
+    return resolve(options.userConfigDirectory);
+  const sharedBase = cortexKitUserConfigBasePath();
+  const shared = detectConfigFile(sharedBase);
+  if (shared.format !== "none")
+    return dirname3(shared.path);
+  if (options.harness) {
+    const legacy = resolveLegacyConfigSourcesForHarness(options.directory ?? process.cwd(), options.harness).user.find((source) => existsSync7(source.path));
+    if (legacy)
+      return dirname3(legacy.path);
+  }
+  return dirname3(sharedBase);
+}
+function markerCount(content) {
+  return content.match(GUIDANCE_MARKER_LINE)?.length ?? 0;
+}
+function createPromptSurfaceRuntime(options) {
+  const userConfigDirectory = resolveUserConfigDirectory(options);
+  const warned = new Set;
+  const warnOnce = (key, message) => {
+    if (warned.has(key))
+      return;
+    warned.add(key);
+    options.warn(message);
+  };
+  const readGuidanceOverride = (configuredPath) => {
+    if (!configuredPath)
+      return;
+    const path3 = isAbsolute2(configuredPath) ? configuredPath : resolve(userConfigDirectory, configuredPath);
+    let content;
+    try {
+      if (!statSync5(path3).isFile()) {
+        warnOnce(`guidance-not-file:${path3}`, `prompt_surface.guidance_override_path (${path3}) is not a file; using built-in guidance.`);
+        return;
+      }
+      content = readFileSync6(path3, "utf8");
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      warnOnce(`guidance-unreadable:${path3}:${reason}`, `prompt_surface.guidance_override_path (${path3}) could not be read (${reason}); using built-in guidance.`);
+      return;
+    }
+    if (content.trim().length === 0) {
+      warnOnce(`guidance-empty:${path3}`, `prompt_surface.guidance_override_path (${path3}) is empty; using built-in guidance.`);
+      return;
+    }
+    const markers = markerCount(content);
+    if (markers !== 1) {
+      warnOnce(`guidance-marker-count:${path3}:${markers}`, `prompt_surface.guidance_override_path (${path3}) must contain exactly one ${JSON.stringify(GUIDANCE_MARKER)} section marker; found ${markers}. Using built-in guidance.`);
+      return;
+    }
+    return content;
+  };
+  return {
+    resolveRegistration(config) {
+      const { preset } = resolvePromptSurface(config, undefined);
+      const overrides = config?.tool_descriptions ?? {};
+      for (const [toolId, description] of Object.entries(overrides)) {
+        if (!PROMPT_SURFACE_TOOL_ID_SET.has(toolId)) {
+          warnOnce(`unknown-tool:${toolId}`, `prompt_surface.tool_descriptions.${toolId} is not a known ctx_* tool ID; the override was ignored.`);
+        } else if (description.trim().length === 0) {
+          warnOnce(`empty-tool:${toolId}`, `prompt_surface.tool_descriptions.${toolId} is empty; the override was ignored.`);
+        }
+      }
+      return {
+        preset,
+        descriptionFor(toolId, fullDescription) {
+          if (!PROMPT_SURFACE_TOOL_ID_SET.has(toolId))
+            return fullDescription;
+          const override = overrides[toolId];
+          if (override !== undefined && override.trim().length > 0)
+            return override;
+          return preset === "light" ? LIGHT_TOOL_DESCRIPTIONS[toolId] : fullDescription;
+        }
+      };
+    },
+    resolveGuidance(config, modelKey) {
+      const { preset } = resolvePromptSurface(config, modelKey);
+      return {
+        preset,
+        primaryOverride: readGuidanceOverride(config?.guidance_override_path)
+      };
+    }
+  };
+}
+function createPromptSurfaceGuidanceEpochCache(runtime) {
+  const epochs = new Map;
+  return {
+    resolve(sessionId, config, modelKey) {
+      const cached = epochs.get(sessionId);
+      if (cached && cached.config === config && cached.modelKey === modelKey) {
+        return cached.selection;
+      }
+      const selection = runtime.resolveGuidance(config, modelKey);
+      epochs.set(sessionId, { config, modelKey, selection });
+      return selection;
+    },
+    clear(sessionId) {
+      epochs.delete(sessionId);
+    }
+  };
+}
+
 // src/read-session-pi.ts
 var SYNTH_USER_ID_PREFIX = "synth-user-";
 function resolvePiStableId(msg, index, entryIds, entryIdByRef) {
@@ -151414,7 +152195,7 @@ function pruneNestedConfigLeaf(block, relativePath) {
 }
 
 // src/config/index.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync9, readFileSync as readFileSync9 } from "node:fs";
 
 // ../plugin/src/config/migrate-dreamer-v2.ts
 var OLD_VERIFY_TASK = "verify";
@@ -166271,6 +167052,23 @@ var PiThinkingLevelSchema = exports_external.enum(["off", "minimal", "low", "med
 var PiConfigSchema = exports_external.object({
   subagent_extensions: exports_external.array(exports_external.string().trim().min(1)).optional().describe("User-only allowlist of Pi extensions for Magic Context subagent children. When set, children use --no-extensions and load only these entries (plus Magic Context's scoped child extension where applicable). Relative paths resolve from ~/.pi/agent, matching Pi's settings.json package location. Unset preserves normal Pi extension discovery.")
 }).optional();
+var PromptSurfacePresetSchema = exports_external.enum(["full", "light"]);
+var PromptSurfaceModelKeySchema = exports_external.string().refine(isValidPromptSurfaceModelKey, {
+  message: "Use a non-empty provider/model key or the literal provider/* wildcard; model IDs may contain additional slashes and matching is case-sensitive."
+});
+var PromptSurfaceToolKeySchema = exports_external.string().refine((value) => value.trim().length > 0, {
+  message: "tool description keys must not be empty or whitespace-only"
+});
+var PromptSurfaceConfigSchema = exports_external.object({
+  default: PromptSurfacePresetSchema.default("full").describe('Fallback prompt-surface preset ("full" or "light").'),
+  models: exports_external.record(PromptSurfaceModelKeySchema, PromptSurfacePresetSchema).optional().describe("Literal per-model routing. Keys are provider/model or provider/*; matching is case-sensitive and preserves additional slashes in model IDs."),
+  guidance_override_path: exports_external.string().refine((value) => value.trim().length > 0, {
+    message: "guidance_override_path must not be empty or whitespace-only"
+  }).optional().describe("USER-LEVEL ONLY path to a complete primary guidance section. Relative paths resolve from the user config file."),
+  tool_descriptions: exports_external.record(PromptSurfaceToolKeySchema, exports_external.string().refine((value) => value.trim().length > 0, {
+    message: "tool description values must not be empty or whitespace-only"
+  })).optional().describe("USER-LEVEL ONLY top-level description overrides keyed by ctx_* tool ID; parameter schemas and descriptions are unchanged.")
+}).describe("Prompt-surface preset routing. Project config may select default/models, while guidance_override_path and tool_descriptions are user-level only.");
 var CronScheduleSchema = exports_external.string().refine((s) => s.trim() === "" || isValidCron(s), {
   message: 'Invalid schedule: use a 5-field cron expression (e.g. "0 3 * * *" for 3am daily, "0 3 * * 0" for Sunday 3am, "0 */6 * * *" every 6h) or "" to disable.'
 }).describe('5-field cron schedule (e.g. "0 3 * * *"), or "" to disable this task.');
@@ -166453,6 +167251,7 @@ var MagicContextConfigSchema = exports_external.object({
   historian: HistorianConfigSchema.describe("Historian agent configuration (model, fallback_models, variant, temperature, maxTokens, permission, two_pass, etc.)"),
   dreamer: DreamerConfigSchema.optional().describe("Dreamer agent + scheduling configuration (model, fallback_models, disable, schedule, tasks, etc.)"),
   cache_ttl: exports_external.union([exports_external.string(), exports_external.object({ default: exports_external.string() }).catchall(exports_external.string())]).default("5m").describe('Cache TTL: string (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "model-id": "10m" }). Set to "never" for lanes kept warm by an external keepwarm proxy — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time.'),
+  prompt_surface: PromptSurfaceConfigSchema.default({ default: "full" }).describe("Prompt-surface presets: default is full; models use the literal provider/model or provider/* routing grammar. Guidance and tool-description overrides are user-level only. On OpenCode and Pi, per-model routing applies to the guidance block only: tool descriptions are registered once per process, so they follow the default preset (a v1 plugin-surface limitation; per-model tool descriptions are planned for the OpenCode v2 plugin API once the SDK stabilizes)."),
   output_reserve: exports_external.union([
     exports_external.number().min(0),
     exports_external.object({ default: exports_external.number().min(0) }).catchall(exports_external.number().min(0))
@@ -166501,7 +167300,7 @@ var MagicContextConfigSchema = exports_external.object({
   keep_subagents: exports_external.boolean().default(false).describe("Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, sidekick, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect."),
   fail_closed_blocking: exports_external.boolean().default(true).describe("When Magic Context cannot operate (schema fence mismatch, storage open/migration failure), block the primary-session prompt with a loud recovery error instead of silently degrading to native compaction. Default true. Set false only to restore the old degrade-silently behavior (not recommended). USER-LEVEL ONLY — ignored in project config for security. Requires a restart."),
   compaction: exports_external.object({
-    enabled: exports_external.boolean().default(true).describe("When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; ctx_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in magic-context.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /ctx-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory/docs injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. If transform_mode is rust, compaction-off resolves to the TypeScript transform and emits one frozen boot warning because there is no Rust reduced-mode contract. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /ctx-wrapup, /ctx-recomp, /ctx-flush, and /ctx-session-upgrade refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.")
+    enabled: exports_external.boolean().default(true).describe("When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; ctx_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in magic-context.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /ctx-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory/docs injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /ctx-wrapup, /ctx-recomp, /ctx-flush, and /ctx-session-upgrade refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.")
   }).default({ enabled: true }).describe("Compaction-off mode gate. Default true (MC manages the context window as today). Set compaction.enabled=false to keep the knowledge layer while letting native compaction (or nothing) own the window. Boot-resolved; requires a restart to change."),
   todowrite: exports_external.object({
     enabled: exports_external.boolean().default(true).describe("Pi only: register Magic Context's todowrite task-list tool. Disable if you use your own todo extension. OpenCode ships its own built-in todowrite; this setting has no effect there."),
@@ -166547,6 +167346,7 @@ var MagicContextConfigSchema = exports_external.object({
 // ../plugin/src/config/project-security.ts
 var HIDDEN_AGENT_KEYS = ["historian", "dreamer", "sidekick"];
 var HISTORIAN_USER_ONLY_FIELDS = ["model", "fallback_models"];
+var PROMPT_SURFACE_USER_ONLY_FIELDS = ["guidance_override_path", "tool_descriptions"];
 var AGENT_ESCALATION_FIELDS = ["prompt", "permission", "tools", "system_prompt"];
 var EMBEDDING_DESTINATION_FIELDS = ["endpoint", "provider", "fallback_provider"];
 var PERCENTAGE_THRESHOLD_REASON = "security: a repository may only raise compaction thresholds above the user's effective value; it cannot force earlier historian work or cloned-repo cost escalation.";
@@ -166682,6 +167482,19 @@ function stripUnsafeProjectConfigFields(projectRaw) {
     delete storage.enforce_private_permissions;
     warnings.push("Ignoring storage.enforce_private_permissions from project config (security: only user-level config may opt into externally managed shared storage permissions).");
   }
+  const promptSurface = projectRaw.prompt_surface;
+  if (isPlainObject3(promptSurface)) {
+    const removed = [];
+    for (const field of PROMPT_SURFACE_USER_ONLY_FIELDS) {
+      if (field in promptSurface) {
+        delete promptSurface[field];
+        removed.push(field);
+      }
+    }
+    if (removed.length > 0) {
+      warnings.push(`Ignoring prompt_surface.${removed.join("/")} from project config (security: repositories may select prompt presets but only user config may provide guidance or tool-description text).`);
+    }
+  }
   const pi = projectRaw.pi;
   if (isPlainObject3(pi) && "subagent_extensions" in pi) {
     delete pi.subagent_extensions;
@@ -166878,76 +167691,18 @@ function dropInheritedEmbeddingKeyOnRedirect(projectRaw, mergedRaw, userRaw) {
 }
 
 // ../plugin/src/config/variable.ts
-import { existsSync as existsSync6, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync7 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
-import { dirname as dirname3, isAbsolute as isAbsolute2, resolve } from "node:path";
-
-// ../plugin/src/shared/jsonc-parser.ts
-function stripJsonComments(content) {
-  let result = "";
-  let inString = false;
-  let escaped = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-  for (let index = 0;index < content.length; index += 1) {
-    const char = content[index];
-    const next = content[index + 1];
-    if (inLineComment) {
-      if (char === `
-`) {
-        inLineComment = false;
-        result += char;
-      }
-      continue;
-    }
-    if (inBlockComment) {
-      if (char === "*" && next === "/") {
-        inBlockComment = false;
-        index += 1;
-      }
-      continue;
-    }
-    if (inString) {
-      result += char;
-      if (escaped) {
-        escaped = false;
-      } else if (char === "\\") {
-        escaped = true;
-      } else if (char === '"') {
-        inString = false;
-      }
-      continue;
-    }
-    if (char === '"') {
-      inString = true;
-      result += char;
-      continue;
-    }
-    if (char === "/" && next === "/") {
-      inLineComment = true;
-      index += 1;
-      continue;
-    }
-    if (char === "/" && next === "*") {
-      inBlockComment = true;
-      index += 1;
-      continue;
-    }
-    result += char;
-  }
-  return result;
-}
-
-// ../plugin/src/config/variable.ts
+import { dirname as dirname4, isAbsolute as isAbsolute3, resolve as resolve2 } from "node:path";
 var ENV_PATTERN = /\{env:([^}]+)\}/g;
 var FILE_PATTERN = /\{file:([^}]+)\}/g;
 function sensitiveFilePathReason(resolvedPath) {
   const home = homedir4();
   const sensitiveDirs = [
-    { dir: resolve(home, ".ssh"), label: "SSH keys" },
-    { dir: resolve(home, ".aws"), label: "AWS credentials" },
-    { dir: resolve(home, ".gnupg"), label: "GnuPG keyring" },
-    { dir: resolve(home, ".config", "gh"), label: "GitHub CLI auth" }
+    { dir: resolve2(home, ".ssh"), label: "SSH keys" },
+    { dir: resolve2(home, ".aws"), label: "AWS credentials" },
+    { dir: resolve2(home, ".gnupg"), label: "GnuPG keyring" },
+    { dir: resolve2(home, ".config", "gh"), label: "GitHub CLI auth" }
   ];
   for (const { dir, label } of sensitiveDirs) {
     if (resolvedPath === dir || resolvedPath.startsWith(`${dir}/`)) {
@@ -166987,7 +167742,7 @@ function substituteConfigVariables(input) {
   if (fileMatches.length === 0) {
     return { text, warnings };
   }
-  const configDir = input.configPath ? dirname3(input.configPath) : process.cwd();
+  const configDir = input.configPath ? dirname4(input.configPath) : process.cwd();
   let output = "";
   let cursor = 0;
   for (const match of fileMatches) {
@@ -167005,21 +167760,21 @@ function substituteConfigVariables(input) {
     }
     let filePath = rawPath.trim();
     if (filePath.startsWith("~/")) {
-      filePath = resolve(homedir4(), filePath.slice(2));
-    } else if (!isAbsolute2(filePath)) {
-      filePath = resolve(configDir, filePath);
+      filePath = resolve2(homedir4(), filePath.slice(2));
+    } else if (!isAbsolute3(filePath)) {
+      filePath = resolve2(configDir, filePath);
     }
     const sensitiveReason = sensitiveFilePathReason(filePath);
     if (sensitiveReason) {
       warnings.push(`${token} resolves to a sensitive path (${sensitiveReason}: ${filePath}); ` + "inlining its contents into config — make sure this is intentional.");
     }
-    if (!existsSync6(filePath)) {
+    if (!existsSync8(filePath)) {
       warnings.push(`File not found for ${token} (resolved to ${filePath}); using empty string`);
       continue;
     }
     let contents;
     try {
-      contents = readFileSync5(filePath, "utf-8").trim();
+      contents = readFileSync7(filePath, "utf-8").trim();
     } catch (error51) {
       const message = error51 instanceof Error ? error51.message : String(error51);
       warnings.push(`Failed to read file for ${token} (${filePath}): ${message}; using empty string`);
@@ -167032,7 +167787,7 @@ function substituteConfigVariables(input) {
 }
 
 // ../plugin/src/shared/models-dev-cache.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync6, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync8, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join5 } from "node:path";
 
 // ../plugin/src/shared/harness-provider-map.ts
@@ -167082,7 +167837,7 @@ function loadPersistedApiCacheOnce() {
     return;
   persistSeedLoaded = true;
   try {
-    const raw = readFileSync6(persistFilePath(), "utf-8");
+    const raw = readFileSync8(persistFilePath(), "utf-8");
     const obj = JSON.parse(raw);
     const map2 = new Map;
     for (const [key, persisted] of Object.entries(obj)) {
@@ -167110,7 +167865,7 @@ function loadPersistedApiCacheOnce() {
 function isFinitePositive(value) {
   return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
-function modelKeyLookupOrder(providerID, modelID) {
+function modelKeyLookupOrder2(providerID, modelID) {
   const full = `${providerID}/${modelID}`;
   const canonicalFull = piModelRefToCanonical(full);
   const candidates = [full, canonicalFull, modelID];
@@ -167127,7 +167882,7 @@ function configuredOutputReserve(config2, providerID, modelID) {
     return Number.isFinite(config2) && config2 >= 0 ? config2 : undefined;
   if (!config2)
     return;
-  for (const candidate of modelKeyLookupOrder(providerID, modelID)) {
+  for (const candidate of modelKeyLookupOrder2(providerID, modelID)) {
     const value = config2[candidate];
     if (typeof value === "number" && Number.isFinite(value) && value >= 0)
       return value;
@@ -167224,14 +167979,14 @@ function getUserConfigPaths() {
   return [`${basePath}.jsonc`, `${basePath}.json`];
 }
 function resolveFirstExisting(paths) {
-  return paths.find((path3) => existsSync7(path3));
+  return paths.find((path3) => existsSync9(path3));
 }
 function resolvePiLegacyFallback(sources) {
-  return sources.find((source) => existsSync7(source.path)) ?? null;
+  return sources.find((source) => existsSync9(source.path)) ?? null;
 }
 function loadConfigFile(path3, scope) {
   try {
-    const rawText = readFileSync7(path3, "utf-8");
+    const rawText = readFileSync9(path3, "utf-8");
     const substituted = substituteConfigVariables({
       text: rawText,
       configPath: path3,
@@ -167364,7 +168119,7 @@ function loadPiConfig(opts = {}) {
     if (loaded)
       loadedFiles.push(loaded);
   }
-  const legacyProjectUnmigrated = !projectPath && !projectLegacyFallback && legacySources.project.some((source) => existsSync7(source.path));
+  const legacyProjectUnmigrated = !projectPath && !projectLegacyFallback && legacySources.project.some((source) => existsSync9(source.path));
   const userPath = resolveFirstExisting(getUserConfigPaths());
   const userLegacyFallback = userPath ? null : resolvePiLegacyFallback(harnessLegacy.user);
   const userReadPath = userPath ?? userLegacyFallback?.path;
@@ -167373,7 +168128,7 @@ function loadPiConfig(opts = {}) {
     if (loaded)
       loadedFiles.push(loaded);
   }
-  const legacyUserUnmigrated = !userPath && !userLegacyFallback && legacySources.user.some((source) => existsSync7(source.path));
+  const legacyUserUnmigrated = !userPath && !userLegacyFallback && legacySources.user.some((source) => existsSync9(source.path));
   if (userLegacyFallback) {
     warnings.push(`[user config] reading legacy config from ${userLegacyFallback.path} until migration completes; run \`npx @cortexkit/magic-context doctor\` to consolidate into the shared CortexKit location.`);
   } else if (legacyUserUnmigrated) {
@@ -167420,6 +168175,7 @@ function loadPiConfig(opts = {}) {
   warnings.push(...parsed.warnings.map((warning) => `[merged config] ${warning}`));
   return {
     config: parsed.config,
+    registrationPromptSurface: trustedBaseConfig.prompt_surface,
     warnings,
     loadedFromPaths: loadedFiles.map((loaded) => loaded.path)
   };
@@ -167483,7 +168239,7 @@ function loadPiConfigDetailed(opts = {}) {
     if (loaded)
       loadedFiles.push(loaded);
   }
-  const legacyProjectUnmigrated = !projectPath && !projectLegacyFallback && legacySources.project.some((source) => existsSync7(source.path));
+  const legacyProjectUnmigrated = !projectPath && !projectLegacyFallback && legacySources.project.some((source) => existsSync9(source.path));
   const userPath = resolveFirstExisting(getUserConfigPaths());
   const userLegacyFallback = userPath ? null : resolvePiLegacyFallback(harnessLegacy.user);
   const userReadPath = userPath ?? userLegacyFallback?.path;
@@ -167492,7 +168248,7 @@ function loadPiConfigDetailed(opts = {}) {
     if (loaded)
       loadedFiles.push(loaded);
   }
-  const legacyUserUnmigrated = !userPath && !userLegacyFallback && legacySources.user.some((source) => existsSync7(source.path));
+  const legacyUserUnmigrated = !userPath && !userLegacyFallback && legacySources.user.some((source) => existsSync9(source.path));
   if (userLegacyFallback) {
     warnings.push(`[user config] reading legacy config from ${userLegacyFallback.path} until migration completes; run \`npx @cortexkit/magic-context doctor\` to consolidate into the shared CortexKit location.`);
   } else if (legacyUserUnmigrated) {
@@ -167547,6 +168303,7 @@ function loadPiConfigDetailed(opts = {}) {
   };
   return {
     config: parsed.config,
+    registrationPromptSurface: trustedBaseConfig.prompt_surface,
     warnings,
     loadedFromPaths: loadedFiles.map((loaded) => loaded.path),
     loadOutcome: combinedOutcome({
@@ -167561,7 +168318,7 @@ function loadPiConfigDetailed(opts = {}) {
 }
 
 // src/embedding-bootstrap.ts
-import { statSync as statSync5 } from "node:fs";
+import { statSync as statSync6 } from "node:fs";
 
 // ../plugin/src/features/magic-context/compartment-chunk-embedding.ts
 import { createHash as createHash8 } from "node:crypto";
@@ -168631,7 +169388,7 @@ class SubcSocket {
     return this.sock.localPort ?? null;
   }
   static connect(host, port, deadlineMs) {
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const sock = net.connect({ host, port });
       sock.setNoDelay(true);
       const timer = setTimeout(() => {
@@ -168640,7 +169397,7 @@ class SubcSocket {
       }, Math.max(0, deadlineMs - Date.now()));
       sock.once("connect", () => {
         clearTimeout(timer);
-        resolve2(new SubcSocket(sock));
+        resolve3(new SubcSocket(sock));
       });
       sock.once("error", (err) => {
         clearTimeout(timer);
@@ -168672,7 +169429,7 @@ class SubcSocket {
     }
     if (n === 0)
       return Promise.resolve(new Uint8Array(0));
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       let timer = null;
       if (Number.isFinite(deadlineMs)) {
         const remaining = deadlineMs - Date.now();
@@ -168685,7 +169442,7 @@ class SubcSocket {
           reject(new SocketTimeoutError(`timed out waiting for ${n} bytes`));
         }, remaining);
       }
-      this.waiter = { need: n, resolve: resolve2, reject, timer };
+      this.waiter = { need: n, resolve: resolve3, reject, timer };
       this.tryServe();
     });
   }
@@ -168709,7 +169466,7 @@ class SubcSocket {
     let queued = false;
     let settled = false;
     let timer = null;
-    const completed = new Promise((resolve2, reject) => {
+    const completed = new Promise((resolve3, reject) => {
       const settle = (run) => {
         if (settled)
           return;
@@ -168733,7 +169490,7 @@ class SubcSocket {
             if (err) {
               reject(new SocketWriteQueuedError("subc socket reported a write error after bytes were handed to the socket", err instanceof Error ? err : new Error(String(err))));
             } else {
-              resolve2();
+              resolve3();
             }
           });
         });
@@ -168949,14 +169706,14 @@ class SubcClient {
     const admission = opts.admissionClass ?? AdmissionClass.Normal;
     const corr = this.allocateCorr();
     const key = pendingKey(handle, corr);
-    const closed = new Promise((resolve2, reject) => {
+    const closed = new Promise((resolve3, reject) => {
       if (this.closedErr) {
         reject(this.closedErr);
         return;
       }
       this.pending.set(key, {
         handle,
-        resolve: () => resolve2(),
+        resolve: () => resolve3(),
         reject,
         onProgress: onEvent,
         timer: null,
@@ -169041,11 +169798,11 @@ class SubcClient {
     const waiters = [];
     for (const pending of this.pending.values()) {
       if (pending.handle === handle && !pending.subscription) {
-        waiters.push(new Promise((resolve2) => {
+        waiters.push(new Promise((resolve3) => {
           const previous = pending.onSettle;
           pending.onSettle = () => {
             previous?.();
-            resolve2();
+            resolve3();
           };
         }));
       }
@@ -169101,11 +169858,11 @@ class SubcClient {
     const channel = handle?.channel ?? 0;
     const epoch = handle?.epoch ?? 0;
     const frame = buildFrame(FrameType.Request, buildFlags(false, priority, false, admission), channel, epoch, corr, body);
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const ms = timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
       const pending = {
         handle,
-        resolve: resolve2,
+        resolve: resolve3,
         reject,
         onProgress,
         timer: null,
@@ -169179,11 +169936,11 @@ class SubcClient {
       }
       return this.outcomeUnknownCallError("connection dropped before the managed call returned a response", error51);
     };
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const ms = timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
       const pending = {
         handle,
-        resolve: resolve2,
+        resolve: resolve3,
         reject,
         onProgress,
         timer: null,
@@ -169571,7 +170328,7 @@ function normalizeConnectOptions(opts) {
     identity: opts.identity,
     targetKind: opts.targetKind ?? DEFAULT_MANAGED_TARGET_KIND,
     reconnectBackoff: opts.reconnectBackoff ?? DEFAULT_RECONNECT_BACKOFF,
-    sleep: opts.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms))),
+    sleep: opts.sleep ?? ((ms) => new Promise((resolve3) => setTimeout(resolve3, ms))),
     timeoutArbitrationGraceMs: opts.timeoutArbitrationGraceMs ?? TIMEOUT_ARBITRATION_GRACE_MS
   };
 }
@@ -169628,8 +170385,8 @@ class AsyncPermitPool {
       this.available -= 1;
       return this.releaseOnce();
     }
-    await new Promise((resolve2) => {
-      this.waiters.push(resolve2);
+    await new Promise((resolve3) => {
+      this.waiters.push(resolve3);
     });
     return this.releaseOnce();
   }
@@ -169685,8 +170442,8 @@ class SubcProvider {
     this.currentConn = currentConn;
     this.opts = opts;
     this.storage = storage;
-    this.closed = new Promise((resolve2) => {
-      this.resolveClosed = resolve2;
+    this.closed = new Promise((resolve3) => {
+      this.resolveClosed = resolve3;
     });
     this.readLoop(sock, this.generation);
     this.enqueueConnectionState({ state: "connected", epoch: this.connectionEpoch });
@@ -169706,13 +170463,13 @@ class SubcProvider {
     const key = routeKey(handle, corr);
     const timeoutMs = opts.timeoutMs ?? WRITE_TIMEOUT_MS;
     const frame = buildFrame(FrameType.Request, buildFlags(false, opts.priority ?? Priority.Interactive, false, opts.admissionClass ?? AdmissionClass.Normal), handle.channel, handle.epoch, corr, body);
-    return await new Promise((resolve2, reject) => {
+    return await new Promise((resolve3, reject) => {
       const timer = setTimeout(() => {
         if (this.pending.delete(key))
           reject(new SubcProviderError("reverse request timed out", "request_timeout"));
       }, timeoutMs);
       this.pending.set(key, {
-        resolve: (response) => resolve2(response.body),
+        resolve: (response) => resolve3(response.body),
         reject,
         timer
       });
@@ -170184,7 +170941,7 @@ function normalizeProviderConnectOptions(opts) {
     onBound: opts.onBound,
     onRouteGone: opts.onRouteGone,
     reconnectBackoff: opts.reconnectBackoff ?? DEFAULT_RECONNECT_BACKOFF,
-    sleep: opts.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms))),
+    sleep: opts.sleep ?? ((ms) => new Promise((resolve3) => setTimeout(resolve3, ms))),
     restoredDebounceMs: opts.restoredDebounceMs ?? DEFAULT_RESTORED_DEBOUNCE_MS,
     onConnectionState: opts.onConnectionState,
     launchNonce: opts.launchNonce
@@ -170229,7 +170986,7 @@ function errorCode2(err) {
   return;
 }
 async function pauseBeforeStateRetry() {
-  await new Promise((resolve2) => setTimeout(resolve2, 0));
+  await new Promise((resolve3) => setTimeout(resolve3, 0));
 }
 function controlFlags() {
   return buildFlags(false, Priority.Passive, false);
@@ -170467,7 +171224,7 @@ function classifyError(value) {
   });
 }
 function wait(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function sha256(value) {
   return createHash9("sha256").update(value).digest("hex");
@@ -170946,7 +171703,7 @@ function getEmbeddingProviderIdentity(config2) {
 // ../plugin/src/features/magic-context/memory/embedding-local.ts
 import { chmodSync as chmodSync2, mkdirSync as mkdirSync4 } from "node:fs";
 import { open, stat, unlink, writeFile } from "node:fs/promises";
-import { dirname as dirname4, join as join6 } from "node:path";
+import { dirname as dirname5, join as join6 } from "node:path";
 import { pathToFileURL } from "node:url";
 var LOCK_POLL_MS = 150;
 var STALE_LOCK_MS = 3 * 60000;
@@ -170986,7 +171743,7 @@ async function acquireModelLoadLock(lockPath) {
       if (Date.now() - waitStart > MAX_LOCK_WAIT_MS) {
         throw new Error(`[magic-context] embedding-load lock wait exceeded ${MAX_LOCK_WAIT_MS}ms; another process is still loading the model. Skipping this init attempt to avoid an unsynchronized native load.`);
       }
-      await new Promise((resolve2) => setTimeout(resolve2, LOCK_POLL_MS));
+      await new Promise((resolve3) => setTimeout(resolve3, LOCK_POLL_MS));
     }
   }
 }
@@ -171010,7 +171767,7 @@ async function injectWasmOrtForElectron() {
       const { createRequire: createRequireFn } = await import("node:module");
       const requireFn = createRequireFn(import.meta.url);
       const mainEntry = requireFn.resolve("onnxruntime-web");
-      const distDir = dirname4(mainEntry);
+      const distDir = dirname5(mainEntry);
       const wasmPathsPrefix = `${pathToFileURL(distDir).href}/`;
       if (ortWeb.env?.wasm) {
         ortWeb.env.wasm.wasmPaths = wasmPathsPrefix;
@@ -171191,7 +171948,7 @@ class LocalEmbeddingProvider {
               }
               const delayMs = 300 * attempt + Math.floor(Math.random() * 200);
               log(`[magic-context] embedding model load attempt ${attempt}/${MAX_ATTEMPTS} failed transiently, retrying in ${delayMs}ms`);
-              await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+              await new Promise((resolve3) => setTimeout(resolve3, delayMs));
             }
           }
           if (this.pipeline) {
@@ -171224,8 +171981,8 @@ class LocalEmbeddingProvider {
     if (this.inFlight === 0) {
       return Promise.resolve();
     }
-    return new Promise((resolve2) => {
-      this.inFlightWaiters.push(resolve2);
+    return new Promise((resolve3) => {
+      this.inFlightWaiters.push(resolve3);
     });
   }
   finishInFlight() {
@@ -172923,7 +173680,7 @@ async function runShadowWorker() {
     }
     processed += item.ids.length;
     processedBytes += itemBytes;
-    await new Promise((resolve2) => setTimeout(resolve2, 0));
+    await new Promise((resolve3) => setTimeout(resolve3, 0));
   }
 }
 function registerProjectInObservationMode(db, projectIdentity, sourceDirectory, failedConfig, failureSummary) {
@@ -173284,7 +174041,7 @@ async function embedCandidateChunkBatch(db, projectIdentity, modelId, candidates
       if (Date.now() - attemptStart >= EMBED_SLOW_FAILURE_NO_RETRY_MS)
         break;
       if (attempt < EMBED_SLICE_RETRY_ATTEMPTS - 1) {
-        await new Promise((resolve2) => setTimeout(resolve2, EMBED_SLICE_RETRY_BASE_MS * 2 ** attempt));
+        await new Promise((resolve3) => setTimeout(resolve3, EMBED_SLICE_RETRY_BASE_MS * 2 ** attempt));
       }
     }
     embedded += persistedIds.size;
@@ -173369,7 +174126,7 @@ async function embedSessionCompartmentChunks(db, projectIdentity, sessionId, opt
       }
       embedded += n;
       options?.onProgress?.({ embedded: Math.min(embedded, total), total });
-      await new Promise((resolve2) => setTimeout(resolve2, 0));
+      await new Promise((resolve3) => setTimeout(resolve3, 0));
     }
   } finally {
     clearInterval(renewal);
@@ -173612,7 +174369,7 @@ function configCandidatePaths(directory, loadedPaths) {
 function configFingerprint(paths) {
   return paths.map((path3) => {
     try {
-      const stat2 = statSync5(path3);
+      const stat2 = statSync6(path3);
       return `${path3}:${stat2.size}:${stat2.mtimeMs}`;
     } catch {
       return `${path3}:missing`;
@@ -179730,7 +180487,7 @@ function getMemoryVerifications(db, memoryIds) {
 }
 // ../plugin/src/features/magic-context/memory/verification-paths.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync8, realpathSync as realpathSync2, statSync as statSync6 } from "node:fs";
+import { existsSync as existsSync10, realpathSync as realpathSync2, statSync as statSync7 } from "node:fs";
 import path3 from "node:path";
 import { promisify } from "node:util";
 var execFileAsync = promisify(execFile);
@@ -179837,7 +180594,7 @@ function verificationFileExists(baseRoot, filePath) {
     return false;
   const root = path3.resolve(baseRoot);
   const candidate = path3.resolve(root, filePath);
-  return isWithin(root, candidate) && existsSync8(candidate);
+  return isWithin(root, candidate) && existsSync10(candidate);
 }
 async function normalizeVerificationFiles(args) {
   const cwd = path3.resolve(args.cwd);
@@ -179870,9 +180627,9 @@ async function normalizeVerificationFiles(args) {
       warnings.push(`Skipped verification path "${value}" because it is the repo/project root.`);
       continue;
     }
-    if (existsSync8(candidate)) {
+    if (existsSync10(candidate)) {
       try {
-        if (statSync6(candidate).isDirectory()) {
+        if (statSync7(candidate).isDirectory()) {
           warnings.push(`Skipped verification path "${value}" because it is a directory.`);
           continue;
         }
@@ -179901,7 +180658,7 @@ async function normalizeVerificationFiles(args) {
       }
       normalized.push(tracked);
     } else {
-      if (!existsSync8(candidate)) {
+      if (!existsSync10(candidate)) {
         warnings.push(`Skipped verification path "${value}" because it does not exist.`);
         continue;
       }
@@ -183143,7 +183900,7 @@ class BoundedSessionMap {
 
 // ../plugin/src/features/magic-context/compaction-marker.ts
 import { createHash as createHash16 } from "node:crypto";
-import { existsSync as existsSync9 } from "node:fs";
+import { existsSync as existsSync11 } from "node:fs";
 import { join as join7 } from "node:path";
 var BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 var ID_PREFIX_HEX_LENGTH = 12;
@@ -183215,7 +183972,7 @@ function getWritableOpenCodeDb() {
       closeQuietly(cachedWriteDb.db);
     } catch {}
   }
-  if (!existsSync9(dbPath)) {
+  if (!existsSync11(dbPath)) {
     throw new Error(`OpenCode database not found at ${dbPath} (is OpenCode installed?)`);
   }
   const db = new Database(dbPath);
@@ -184277,32 +185034,41 @@ function createTodowriteTool() {
 // src/tools/index.ts
 function registerMagicContextTools(pi, opts) {
   const resolveProjectIdentity2 = opts.resolveProjectIdentity ? (directory) => opts.resolveProjectIdentity?.({ cwd: directory }) : undefined;
-  pi.registerTool(createCtxSearchTool({
+  const promptSurfaceRuntime = opts.promptSurfaceRuntime ?? createPromptSurfaceRuntime({
+    userConfigDirectory: process.cwd(),
+    warn: (message) => console.warn(`[magic-context][pi] config warning: ${message}`)
+  });
+  const registration = promptSurfaceRuntime.resolveRegistration(opts.promptSurface);
+  const surfaceTool = (definition) => ({
+    ...definition,
+    description: registration.descriptionFor(definition.name, definition.description)
+  });
+  pi.registerTool(surfaceTool(createCtxSearchTool({
     db: opts.db,
     ensureProjectRegistered: opts.ensureProjectRegistered,
     memoryEnabled: opts.memoryEnabled,
     embeddingEnabled: opts.embeddingEnabled,
     gitCommitsEnabled: opts.gitCommitsEnabled,
     resolveProjectIdentity: resolveProjectIdentity2
-  }));
+  })));
   if (opts.memoryToolEnabled !== false) {
-    pi.registerTool(createCtxMemoryTool({
+    pi.registerTool(surfaceTool(createCtxMemoryTool({
       db: opts.db,
       ensureProjectRegistered: opts.ensureProjectRegistered,
       memoryEnabled: opts.memoryEnabled,
       embeddingEnabled: opts.embeddingEnabled,
       allowDreamerActions: opts.allowDreamerActions ?? false,
       resolveProjectIdentity: resolveProjectIdentity2
-    }));
+    })));
   }
   if (!opts.sessionScopedToolsDisabled) {
-    pi.registerTool(createCtxNoteTool({
+    pi.registerTool(surfaceTool(createCtxNoteTool({
       db: opts.db,
       dreamerEnabled: opts.dreamerEnabled ?? false,
       resolveDreamerEnabled: opts.resolveDreamerEnabled,
       resolveProjectIdentity: resolveProjectIdentity2
-    }));
-    pi.registerTool(createCtxExpandTool({ db: opts.db }));
+    })));
+    pi.registerTool(surfaceTool(createCtxExpandTool({ db: opts.db })));
   }
   if (opts.todowriteEnabled !== false) {
     pi.registerTool(createTodowriteTool());
@@ -184311,12 +185077,12 @@ function registerMagicContextTools(pi, opts) {
     }
   }
   if (!opts.sessionScopedToolsDisabled && !opts.compactionOff) {
-    pi.registerTool(createCtxReduceTool({
+    pi.registerTool(surfaceTool(createCtxReduceTool({
       db: opts.db,
       protectedTags: opts.protectedTags ?? 20,
       resolveProtectedTags: opts.resolveProtectedTags
-    }));
+    })));
   }
 }
 
-export { COMPACTION_ENABLED_PATH, isDreamerRunnable, isCompactionEnabled, migrateMagicContextConfigLocations, ProjectIdentityError, resolveProjectIdentityStrict, resolveProjectIdentity, resolveProjectIdentityForSession, beginBootQuietPeriod, scheduleAfterBootQuiet, Database, closeQuietly, isMidTurn, textMentionsRecentCommit, hasMeaningfulUserText, extractTexts, extractToolCallSummaries, estimateTokens, normalizeText, stripPersistedAssistantText, byteSize, stripTagPrefix, peelLeadingMcTagNotation, prependTag, isRecord, isEditTool, applyEditMarkerToInput, setRawMessageProvider, withRawMessageProvider, cleanUserText, withRawSessionMessageCache, readRawSessionMessages, primeTailRawMessageCache, getCachedAbsoluteMessageCount, primeInMemoryTailRawMessageCache, getRawSessionMessageCount, getRawSessionTagKeysThrough, getLegacyProtectedTailStartOrdinal, readSessionChunk, clearCompressionDepth, clearCompressionDepthRange, getMessageIndexSourceIdentity, isMessageIndexSourceCurrent, getLastIndexedOrdinal, getMessageIndexReconciliationStartOrdinal, isMessageIndexReconciledThrough, indexSingleMessage, indexMessagesAfterOrdinal, sweepOrphanedOpenCodeMessageIndexes, recordSessionProjectIdentity, COMPARTMENT_LEASE_RENEWAL_MS, acquireCompartmentLease, renewCompartmentLease, releaseCompartmentLease, isCompartmentLeaseHeld, persistCachedM0, clearCachedM0M1, getCompartments, getLastCompartmentEndMessage, getLastCompartmentEndMessageId, getCompartmentsByEndMessageId, appendCompartments, saveRecompStagingPass, getRecompStaging, clearRecompStaging, getRecompPartialRange, setRecompPartialRange, escapeXmlAttr, escapeXmlContent, getModuleNoteEvaluationBridge, getContextStoreUuid, parseCompartmentOutput, resolveWorkspaceShareCategories, resolveWorkspaceIdentitySet, expandWorkspaceIdentitySetWithAliases, sourceNameForMemory, computeWorkspaceEpochFingerprint, bumpEpochsForWorkspaceMembers, readProjectDocsCanonical, copySessionStateForClone, getErrorMessage, describeError, setStoragePrivatePermissionEnforcement, stableStringify, getSchemaFenceRejection, getMigrationOnOpenRefusal, LATEST_SUPPORTED_VERSION, getDatabasePath, getPersistedSchemaVersion, setSqlitePragmaConfig, applySqliteTuningPragmas, runSqliteOptimize, openDatabase, openDatabaseAsync, queueM0Mutation, getMaxM0MutationId, queueMemoryMutation, getMemoryMutationsForRender, getMemoryMutationsForRenderByProjects, getMaxMemoryMutationId, getMaxMemoryMutationIdForProjects, MAX_EXECUTE_THRESHOLD, escalationBands, loadProtectedTailMeta, markProtectedTailPolicyV3Seeded, recordProtectedTailPublicationFloor, recordProtectedTailNoEligibleHead, getWrapupInProgressState, isWrapupInProgress, acquireWrapupInProgress, updateWrapupInProgress, releaseWrapupInProgress, resolveCompactionModeRecord, getCompactionModeRecord, setCompactionModeRecord, reserveProtectedTailDrainTokens, clearEmergencyDrainLatch, recordHistorianDrainFailure, clearHistorianDrainFailure, rollbackProtectedTailDrainReservation, clearPersistedReasoningWatermark, getEmergencyInputSample, setEmergencyDropSample, clearEmergencyDropSample, getLastNudgeUndropped, setLastNudgeUndropped, getLastNudgeLevel, setLastNudgeLevel, resetLastNudgeCycle, resetLastNudgeCycleIfTailShrank, getChannel2NudgeState, setChannel2NudgeState, casChannel2NudgeState, getPersistedNoteNudge, setPersistedNoteNudgeTrigger, setPersistedNoteNudgeTriggerMessageId, getNoteNudgeAnchors, getAutoSearchHintDecisions, deliverNoteNudgeAtomic, appendAutoSearchHintDecision, pruneNoteNudgeAnchors, pruneAutoSearchHintDecisions, getPersistedTodoSyntheticAnchor, setPersistedTodoSyntheticAnchor, clearPersistedTodoSyntheticAnchor, getNoteLastReadAt, getHistorianFailureState, incrementHistorianFailure, clearHistorianFailureState, getOverflowState, recordOverflowDetected, clearEmergencyRecovery, clearDetectedContextLimit, getStrippedPlaceholderIds, applyStrippedPlaceholderDelta, getProcessedImageStrippedIds, addProcessedImageStrippedIds, getPendingCompactionMarkerState, clearPendingCompactionMarkerStateIf, getPendingPiCompactionMarkerState, setPendingPiCompactionMarkerState, clearPendingPiCompactionMarkerStateIf, getSessionsWithPendingPiMarker, peekDeferredExecutePending, setDeferredExecutePendingIfAbsent, clearDeferredExecutePendingIfMatches, setSessionWorkMetrics, getSessionWorkMetrics, getOrCreateSessionMeta, updateSessionMeta, advanceToolReclaimWatermark, retryPendingSessionCleanups, getNotes, getSessionNotes, getPendingSmartNotes, getReadySmartNotes, markNoteReady, markNoteChecked, queuePendingOp, getPendingOps, clearPendingOps, removePendingOp, PRIMER_CANDIDATE_TTL_MS, PRIMER_CANDIDATE_MAX_AGE_MS, primerOccurrenceKey, primerOccurrenceUtcDay, insertPrimerCandidates, updatePrimerCandidateEmbedding, getPrimerCandidatesByIds, getPrimerCandidatesForPromotion, countPrimerCandidatesForProject, getActivePrimers, createPrimer, updatePrimerSupport, updatePrimerAnswer, GLOBAL_USER_PROFILE_PROJECT_PATH, getProjectState, bumpProjectUserProfileVersion, saveSourceContent, replaceSourceContent, getSourceContents, recordSubagentInvocation, getLatestHistorianInvocationId, updateTagByteSize, getActiveTagTokenAggregate, AGE_RECLAIM_MIN_TOKENS, getOldestActiveUnprotectedToolTags, getActiveToolTagsForAgeReclaim, getTriggerTagTokenUpperBound, updateTagInputByteSize, updateTagTokenCount, getPersistedToolTagAccounting, getAllStatusTagTokenTotalsFlat, updateTagInputTokenCount, tagTokenCountIsNull, backfillTagTokenCounts, insertTag, updateTagStatus, updateTagDropMode, updateCavemanDepth, hasPiFallbackMessageTags, findAdoptableFallbackTags, hasPiFallbackToolOwnerTags, findPiFallbackToolOwnerTags, adoptPiFallbackToolOwnerTag, adoptPiFallbackMessageTag, getMaxTagNumberBySession, getTagNumberByMessageId, deriveTagLoadFloor, getTagsBySession, getActiveTagsBySession, getTagsForPendingOperations, getTagsByNumbers, getMaxDroppedTagNumber, getToolTagNumberByOwner, getNullOwnerToolTag, adoptNullOwnerToolTag, BoundedSessionMap, piModelRefToCanonical, resolveModelRefForPi, isSaneLimit, resolveLimit, getSdkContextLimit, normalizeTodoStateJson, buildSyntheticTodoPart, SYNTH_USER_ID_PREFIX, resolvePiStableId, isMidTurnPi, readPiSessionMessages, findLastModelKeyFromBranch, convertEntriesToRawMessages, withContentLanguageDirective, withMigrationLanguageDirective, buildPrimaryLanguageDirective, computeCueContentHash, hasMuralCueColumns, getMuralCueState, memoryNeedsCue, setMuralCue, recordMuralCueRejection, invalidateMemory, computeNormalizedHash, hasMemoryShareableColumn, hasMemoryClassifiedAtColumn, getUnclassifiedMemoryIds, insertMemory, getMemoryByHash, getMemoriesByProject, getMemoriesByProjects, getMaxMemoryIdForProjects, readNewMemoriesForM1Union, getAllActiveMemoriesForMigration, getMemoryById, setMemoryClassification, archiveMemory, deleteMemory, getMemoryCount, getMemoryCountsByStatus, USER_MEMORY_CANDIDATE_TTL_MS, insertUserMemoryCandidates, getUserMemoryCandidates, deleteUserMemoryCandidates, pruneExpiredUserMemoryCandidates, insertUserMemory, getActiveUserMemories, updateUserMemoryContent, dismissUserMemory, getOpenCodeDbPath2 as getOpenCodeDbPath, parseCron, nextOccurrence, nextDueAtMs, DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE, DEFAULT_HISTORIAN_TIMEOUT_MS, buildCanonicalChunkTextFromFts, buildCompartmentSummaryFallbackText, canonicalizeInMemoryChunkTextForEmbedding, chunkCanonicalText, chunkEmbeddingWindowsAreCurrent, replaceCompartmentChunkEmbeddings, cosineSimilarity, GIT_SWEEP_LEASE_RENEWAL_MS, acquireGitSweepLease, renewGitSweepLease, markGitSweepSuccessAndRelease, parkGitSweepNonIndexable, releaseGitSweepLease, contentSha256, sweepStaleEmbeddingIdentitiesForProject, enqueueShadowEmbeddingItems, getProjectEmbeddingSnapshot, getProjectChunkEmbeddingModelId, getProjectEmbeddingMaxInputTokens, embedTextForProject, embedBatchForProject, embedItemsForProject, embedUnembeddedMemoriesForProject, drainCommitBacklogForProject, embedSessionCompartmentChunks, getEmbeddingCoverageStatus, promoteSessionFactsDurable, embedPromotedFacts, recordMemoryMapping, recordMemoryVerifications, getUnmappedMemoryIds, clearMemoryVerifications, getMemoryVerifications, resolveGitTopLevel, readGitHead, readGitChangedFilesSince, readGitFileChangeTimesSince, verificationFileExists, normalizeVerificationFiles, indexCommitsForProject, embedUnembeddedCommits, loadPiConfig, ensureProjectRegisteredFromPiDirectory, resolveMuralWire, updateCompactionMarkerAfterPublication, COMPARTMENT_RENDER_EPOCH, encodeCachedM0UpgradeIdentity, decodeCachedM0UpgradeIdentity, DEFAULT_HISTORY_BUDGET_TOKENS, renderCompartmentAtTier, renderDecayedCompartments, extractM0Block, TEMPORAL_MARKER_PATTERN, temporalMarkerPrefix, clearInjectionCache, getVisibleMemoryIds, renderMemoryBlock, DEFAULT_MEMORY_BUDGET_TOKENS, DEFAULT_USER_PROFILE_BUDGET_TOKENS, trimMemoriesToBudgetV2, trimWorkspaceMemoriesToBudgetV2, trimUserMemoriesToBudget, renderMemoryBlockV2, stripMemoryMuralBlock, unifiedSearch, rememberTodowriteToolCallTodos, parseTodos, setTodoSnapshot, registerTodoOverlay, registerTodoStateLifecycle, registerMagicContextTools };
+export { COMPACTION_ENABLED_PATH, isDreamerRunnable, isCompactionEnabled, migrateMagicContextConfigLocations, ProjectIdentityError, resolveProjectIdentityStrict, resolveProjectIdentity, resolveProjectIdentityForSession, beginBootQuietPeriod, scheduleAfterBootQuiet, Database, closeQuietly, isMidTurn, textMentionsRecentCommit, hasMeaningfulUserText, extractTexts, extractToolCallSummaries, estimateTokens, normalizeText, isRecord, completedToolArcCrossesBoundary, estimateTrueRawMessageTokens, buildToolArcs, fenceBoundaryForToolArcs, buildTrueRawTokenIndex, computeRawRangeFingerprint, invalidateTrueRawTokenCache, stripPersistedAssistantText, byteSize, stripTagPrefix, peelLeadingMcTagNotation, prependTag, isEditTool, applyEditMarkerToInput, setRawMessageProvider, withRawMessageProvider, cleanUserText, withRawSessionMessageCache, readRawSessionMessages, primeTailRawMessageCache, getCachedAbsoluteMessageCount, primeInMemoryTailRawMessageCache, getRawSessionMessageCount, getRawSessionTagKeysThrough, getLegacyProtectedTailStartOrdinal, readSessionChunk, clearCompressionDepth, clearCompressionDepthRange, getMessageIndexSourceIdentity, isMessageIndexSourceCurrent, getLastIndexedOrdinal, getMessageIndexReconciliationStartOrdinal, isMessageIndexReconciledThrough, indexSingleMessage, indexMessagesAfterOrdinal, sweepOrphanedOpenCodeMessageIndexes, recordSessionProjectIdentity, COMPARTMENT_LEASE_RENEWAL_MS, acquireCompartmentLease, renewCompartmentLease, releaseCompartmentLease, isCompartmentLeaseHeld, persistCachedM0, clearCachedM0M1, getCompartments, getLastCompartmentEndMessage, getLastCompartmentEndMessageId, getCompartmentsByEndMessageId, appendCompartments, saveRecompStagingPass, getRecompStaging, clearRecompStaging, getRecompPartialRange, setRecompPartialRange, escapeXmlAttr, escapeXmlContent, getModuleNoteEvaluationBridge, getContextStoreUuid, parseCompartmentOutput, resolveWorkspaceShareCategories, resolveWorkspaceIdentitySet, expandWorkspaceIdentitySetWithAliases, sourceNameForMemory, computeWorkspaceEpochFingerprint, bumpEpochsForWorkspaceMembers, readProjectDocsCanonical, copySessionStateForClone, getErrorMessage, describeError, setStoragePrivatePermissionEnforcement, getSchemaFenceRejection, getMigrationOnOpenRefusal, LATEST_SUPPORTED_VERSION, getDatabasePath, getPersistedSchemaVersion, setSqlitePragmaConfig, applySqliteTuningPragmas, runSqliteOptimize, openDatabase, openDatabaseAsync, queueM0Mutation, getMaxM0MutationId, queueMemoryMutation, getMemoryMutationsForRender, getMemoryMutationsForRenderByProjects, getMaxMemoryMutationId, getMaxMemoryMutationIdForProjects, MAX_EXECUTE_THRESHOLD, escalationBands, loadProtectedTailMeta, markProtectedTailPolicyV3Seeded, recordProtectedTailPublicationFloor, recordProtectedTailNoEligibleHead, getWrapupInProgressState, isWrapupInProgress, acquireWrapupInProgress, updateWrapupInProgress, releaseWrapupInProgress, resolveCompactionModeRecord, getCompactionModeRecord, setCompactionModeRecord, reserveProtectedTailDrainTokens, clearEmergencyDrainLatch, recordHistorianDrainFailure, clearHistorianDrainFailure, rollbackProtectedTailDrainReservation, clearPersistedReasoningWatermark, getEmergencyInputSample, setEmergencyDropSample, clearEmergencyDropSample, getLastNudgeUndropped, setLastNudgeUndropped, getLastNudgeLevel, setLastNudgeLevel, resetLastNudgeCycle, resetLastNudgeCycleIfTailShrank, getChannel2NudgeState, setChannel2NudgeState, casChannel2NudgeState, getPersistedNoteNudge, setPersistedNoteNudgeTrigger, setPersistedNoteNudgeTriggerMessageId, getNoteNudgeAnchors, getAutoSearchHintDecisions, deliverNoteNudgeAtomic, appendAutoSearchHintDecision, pruneNoteNudgeAnchors, pruneAutoSearchHintDecisions, getPersistedTodoSyntheticAnchor, setPersistedTodoSyntheticAnchor, clearPersistedTodoSyntheticAnchor, getNoteLastReadAt, getHistorianFailureState, incrementHistorianFailure, clearHistorianFailureState, getOverflowState, recordOverflowDetected, clearEmergencyRecovery, clearDetectedContextLimit, getStrippedPlaceholderIds, applyStrippedPlaceholderDelta, getProcessedImageStrippedIds, addProcessedImageStrippedIds, getPendingCompactionMarkerState, clearPendingCompactionMarkerStateIf, getPendingPiCompactionMarkerState, setPendingPiCompactionMarkerState, clearPendingPiCompactionMarkerStateIf, getSessionsWithPendingPiMarker, peekDeferredExecutePending, setDeferredExecutePendingIfAbsent, clearDeferredExecutePendingIfMatches, setSessionWorkMetrics, getSessionWorkMetrics, getOrCreateSessionMeta, updateSessionMeta, advanceToolReclaimWatermark, retryPendingSessionCleanups, getNotes, getSessionNotes, getPendingSmartNotes, getReadySmartNotes, markNoteReady, markNoteChecked, queuePendingOp, getPendingOps, clearPendingOps, removePendingOp, PRIMER_CANDIDATE_TTL_MS, PRIMER_CANDIDATE_MAX_AGE_MS, primerOccurrenceKey, primerOccurrenceUtcDay, insertPrimerCandidates, updatePrimerCandidateEmbedding, getPrimerCandidatesByIds, getPrimerCandidatesForPromotion, countPrimerCandidatesForProject, getActivePrimers, createPrimer, updatePrimerSupport, updatePrimerAnswer, GLOBAL_USER_PROFILE_PROJECT_PATH, getProjectState, bumpProjectUserProfileVersion, saveSourceContent, replaceSourceContent, getSourceContents, recordSubagentInvocation, getLatestHistorianInvocationId, updateTagByteSize, getActiveTagTokenAggregate, AGE_RECLAIM_MIN_TOKENS, getOldestActiveUnprotectedToolTags, getActiveToolTagsForAgeReclaim, getTriggerTagTokenUpperBound, updateTagInputByteSize, updateTagTokenCount, getPersistedToolTagAccounting, getAllStatusTagTokenTotalsFlat, updateTagInputTokenCount, tagTokenCountIsNull, backfillTagTokenCounts, insertTag, updateTagStatus, updateTagDropMode, updateCavemanDepth, hasPiFallbackMessageTags, findAdoptableFallbackTags, hasPiFallbackToolOwnerTags, findPiFallbackToolOwnerTags, adoptPiFallbackToolOwnerTag, adoptPiFallbackMessageTag, getMaxTagNumberBySession, getTagNumberByMessageId, deriveTagLoadFloor, getTagsBySession, getActiveTagsBySession, getTagsForPendingOperations, getTagsByNumbers, getMaxDroppedTagNumber, getToolTagNumberByOwner, getNullOwnerToolTag, adoptNullOwnerToolTag, BoundedSessionMap, piModelRefToCanonical, resolveModelRefForPi, isSaneLimit, resolveLimit, getSdkContextLimit, resolveModelConfigOrDefault, normalizeTodoStateJson, buildSyntheticTodoPart, promptSurfaceHashMaterial, createPromptSurfaceRuntime, createPromptSurfaceGuidanceEpochCache, SYNTH_USER_ID_PREFIX, resolvePiStableId, isMidTurnPi, readPiSessionMessages, findLastModelKeyFromBranch, convertEntriesToRawMessages, withContentLanguageDirective, withMigrationLanguageDirective, buildPrimaryLanguageDirective, computeCueContentHash, hasMuralCueColumns, getMuralCueState, memoryNeedsCue, setMuralCue, recordMuralCueRejection, invalidateMemory, computeNormalizedHash, hasMemoryShareableColumn, hasMemoryClassifiedAtColumn, getUnclassifiedMemoryIds, insertMemory, getMemoryByHash, getMemoriesByProject, getMemoriesByProjects, getMaxMemoryIdForProjects, readNewMemoriesForM1Union, getAllActiveMemoriesForMigration, getMemoryById, setMemoryClassification, archiveMemory, deleteMemory, getMemoryCount, getMemoryCountsByStatus, USER_MEMORY_CANDIDATE_TTL_MS, insertUserMemoryCandidates, getUserMemoryCandidates, deleteUserMemoryCandidates, pruneExpiredUserMemoryCandidates, insertUserMemory, getActiveUserMemories, updateUserMemoryContent, dismissUserMemory, getOpenCodeDbPath2 as getOpenCodeDbPath, parseCron, nextOccurrence, nextDueAtMs, DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE, DEFAULT_HISTORIAN_TIMEOUT_MS, buildCanonicalChunkTextFromFts, buildCompartmentSummaryFallbackText, canonicalizeInMemoryChunkTextForEmbedding, chunkCanonicalText, chunkEmbeddingWindowsAreCurrent, replaceCompartmentChunkEmbeddings, cosineSimilarity, GIT_SWEEP_LEASE_RENEWAL_MS, acquireGitSweepLease, renewGitSweepLease, markGitSweepSuccessAndRelease, parkGitSweepNonIndexable, releaseGitSweepLease, contentSha256, sweepStaleEmbeddingIdentitiesForProject, enqueueShadowEmbeddingItems, getProjectEmbeddingSnapshot, getProjectChunkEmbeddingModelId, getProjectEmbeddingMaxInputTokens, embedTextForProject, embedBatchForProject, embedItemsForProject, embedUnembeddedMemoriesForProject, drainCommitBacklogForProject, embedSessionCompartmentChunks, getEmbeddingCoverageStatus, promoteSessionFactsDurable, embedPromotedFacts, recordMemoryMapping, recordMemoryVerifications, getUnmappedMemoryIds, clearMemoryVerifications, getMemoryVerifications, resolveGitTopLevel, readGitHead, readGitChangedFilesSince, readGitFileChangeTimesSince, verificationFileExists, normalizeVerificationFiles, indexCommitsForProject, embedUnembeddedCommits, loadPiConfig, ensureProjectRegisteredFromPiDirectory, resolveMuralWire, updateCompactionMarkerAfterPublication, COMPARTMENT_RENDER_EPOCH, encodeCachedM0UpgradeIdentity, decodeCachedM0UpgradeIdentity, DEFAULT_HISTORY_BUDGET_TOKENS, renderCompartmentAtTier, renderDecayedCompartments, extractM0Block, TEMPORAL_MARKER_PATTERN, temporalMarkerPrefix, clearInjectionCache, getVisibleMemoryIds, renderMemoryBlock, DEFAULT_MEMORY_BUDGET_TOKENS, DEFAULT_USER_PROFILE_BUDGET_TOKENS, trimMemoriesToBudgetV2, trimWorkspaceMemoriesToBudgetV2, trimUserMemoriesToBudget, renderMemoryBlockV2, stripMemoryMuralBlock, unifiedSearch, rememberTodowriteToolCallTodos, parseTodos, setTodoSnapshot, registerTodoOverlay, registerTodoStateLifecycle, registerMagicContextTools };