@iowarp/clio-coder 0.4.3 → 0.4.5

package/dist/{chunk-RSJ25QSL.js → chunk-KF6GFW6O.js}

@@ -4,33 +4,32 @@ import {
   extractCommandDeleteTargets,
   extractCommandWriteTargets,
   toolMutationPaths
-} from "./chunk-I7ZPNEJM.js";
+} from "./chunk-M6TAYK66.js";
+import {
+  PROJECT_VERIFIER_CATALOG_RELATIVE_PATH
+} from "./chunk-MDU3C27C.js";
+import {
+  asDirectoryPathBoundary,
+  pathBoundaryEntryCovers,
+  resolvePathBoundary
+} from "./chunk-R2P2U3ZS.js";
 import {
   isProjectVerifierCheckId,
   isVerificationScriptName
-} from "./chunk-UL3WSD3F.js";
+} from "./chunk-M4KFUXS7.js";
 import {
   ToolNames
-} from "./chunk-K6BSR66V.js";
+} from "./chunk-EHOSNVVM.js";
 import {
   init_esm_shims
-} from "./chunk-3R73A4XB.js";
+} from "./chunk-ECBHH7LU.js";
 
 // src/domains/safety/finish-contract.ts
 init_esm_shims();
-var FINISH_CONTRACT_ADVISORY_MESSAGE = "[Clio Coder] finish-contract advisory: you changed files this turn without recording validation evidence or an explicit limitation. Run a verification command or state what could not be verified.";
+import { resolve } from "node:path";
+var FINISH_CONTRACT_ADVISORY_MESSAGE = "[Clio Coder] finish-contract advisory: you changed files this turn without recording validation evidence or a limitation receipt. Run a verification command or call limitation with the scope and reason.";
 var DEFAULT_RECENT_ENTRY_LIMIT = 80;
-var LIMITATION_PATTERNS = [
-  /\b(?:blocked by|blocker|blockers|unable to|not able to|could not|couldn't|cannot|can't)\b/i,
-  /\b(?:did not|didn't|have not|haven't|has not|hasn't|was not able|wasn't able)\b/i,
-  /\b(?:not complete|incomplete)\b/i,
-  /\b(?:not|un)(?:\s|-)?(?:validated|verified|tested)\b/i,
-  /^\s*Tests\s*:\s*(?:not run|not executed|not available|failed|blocked|skipped)\b/im,
-  /^\s*Known gaps?\s*:\s*(?!\s*(?:none|no\b|n\/a|not applicable)\b).+/im,
-  /\bremaining(?:\s+\w+){0,3}\s+(?:work|issue|issues|gap|gaps|blocker|blockers)\b/i
-];
 function assessFinishContract(input) {
-  const assistantText = input.assistantText.trim();
   const sessionEntries = input.sessionEntries ?? [];
   const assistantTurnId = input.assistantTurnId ?? null;
   const window = recentEntries(sessionEntries, assistantTurnId, input.recentEntryLimit ?? DEFAULT_RECENT_ENTRY_LIMIT);
@@ -38,12 +37,38 @@ function assessFinishContract(input) {
   if (mutatedPaths.length === 0) {
     return { kind: "ok", reason: "no_mutation", evidence: [], mutatedPaths };
   }
-  const evidence = collectValidationEvidence(window);
+  const acceptanceChecks = new Set(input.activeAcceptance?.verification.map((item) => item.check) ?? []);
+  const evidence = collectValidationEvidence(window, acceptanceChecks, input.workspaceRoot);
+  const limitations = collectLimitationEvidence(window);
+  const required = input.rigor === "high" ? input.activeAcceptance?.verification ?? [] : [];
+  if (required.length > 0) {
+    const passes = new Set(
+      required.filter((check) => evidence.some((item) => acceptanceCheckPassed(item, check, input.workspaceRoot)))
+    );
+    const limited = new Set(limitations.flatMap((item) => item.paths ?? []));
+    const missing = [
+      ...new Set(required.filter((check) => !passes.has(check) && !limited.has(check.check)).map((item) => item.check))
+    ];
+    if (missing.length > 0)
+      return {
+        kind: "engage",
+        reason: "unvalidated_mutation",
+        message: `[Clio Coder] high-rigor finish gate: operator acceptance still requires passing validation for: ${missing.join(", ")}. Run each named check or include its exact id in limitation.paths.`,
+        evidence: [...evidence, ...limitations],
+        mutatedPaths
+      };
+    return {
+      kind: "ok",
+      reason: passes.size === required.length ? "validation_evidence" : "explicit_limitation",
+      evidence: [...evidence, ...limitations],
+      mutatedPaths
+    };
+  }
   if (evidence.length > 0) {
     return { kind: "ok", reason: "validation_evidence", evidence, mutatedPaths };
   }
-  if (hasExplicitLimitation(assistantText)) {
-    return { kind: "ok", reason: "explicit_limitation", evidence: [], mutatedPaths };
+  if (limitations.length > 0) {
+    return { kind: "ok", reason: "explicit_limitation", evidence: limitations, mutatedPaths };
   }
   return {
     kind: "engage",
@@ -53,10 +78,59 @@ function assessFinishContract(input) {
     mutatedPaths
   };
 }
-function hasExplicitLimitation(text) {
-  const normalized = text.trim();
-  if (normalized.length === 0) return false;
-  return LIMITATION_PATTERNS.some((pattern) => pattern.test(normalized));
+function acceptanceCheckPassed(evidence, required, workspaceRoot) {
+  if (evidence.kind !== "validation_command" || evidence.check !== required.check || !workspaceRoot || !evidence.source)
+    return false;
+  if (evidence.durationMs !== void 0 && evidence.durationMs > required.timeoutMs) return false;
+  const root = resolve(workspaceRoot);
+  if (evidence.source.kind === "project-catalog")
+    return evidence.source.path === resolve(root, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH);
+  return evidence.source.path === resolve(root, "package.json") && evidence.cwd === root && validationCheckId(evidence.argv?.join(" ") ?? "") === required.check;
+}
+function collectLimitationEvidence(recent) {
+  const evidence = [];
+  const calls = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of recent) {
+    const call = limitationToolCall(entry);
+    if (call !== null) {
+      calls.set(call.toolCallId, call);
+      continue;
+    }
+    const resultId = successfulToolResultId(entry);
+    if (resultId === null) continue;
+    const candidate = calls.get(resultId);
+    if (candidate === void 0) continue;
+    const item = {
+      kind: "limitation",
+      summary: candidate.command,
+      ...candidate.paths ? { paths: candidate.paths } : {}
+    };
+    if (candidate.turnId !== void 0) item.turnId = candidate.turnId;
+    pushEvidence(evidence, seen, item);
+  }
+  return evidence;
+}
+function limitationToolCall(entry) {
+  const record = asRecord(entry);
+  if (record?.kind !== "message" || record.role !== "tool_call") return null;
+  const payload = asRecord(record.payload);
+  if (payload === null) return null;
+  const toolName = stringFromFirst(payload, ["name", "toolName", "tool"]);
+  if (toolName !== ToolNames.Limitation) return null;
+  const toolCallId = stringFromFirst(payload, ["toolCallId", "tool_call_id", "id"]) ?? turnIdOf(entry);
+  if (toolCallId === null) return null;
+  const args = asRecord(payload.args ?? payload.arguments ?? payload.input);
+  const scope = typeof args?.scope === "string" ? args.scope.trim() : "";
+  const reason = typeof args?.reason === "string" ? args.reason.trim() : "";
+  const candidate = {
+    toolCallId,
+    paths: Array.isArray(args?.paths) ? args.paths.filter((item) => typeof item === "string").map((item) => item.trim()) : [],
+    command: `limitation recorded: ${scope.length > 0 ? scope : "unspecified"} (reason=${reason.length > 0 ? reason : "unspecified"})`
+  };
+  const turnId = turnIdOf(entry);
+  if (turnId !== null) candidate.turnId = turnId;
+  return candidate;
 }
 function mutatingReceipts(recent) {
   const mutationCalls = /* @__PURE__ */ new Map();
@@ -65,7 +139,7 @@ function mutatingReceipts(recent) {
   for (const entry of recent) {
     const bashMutation = bashExecutionMutationPaths(entry);
     if (bashMutation !== null) {
-      for (const path of bashMutation) pushPath(paths, seen, path);
+      for (const path2 of bashMutation) pushPath(paths, seen, path2);
       continue;
     }
     const call = mutatingToolCall(entry);
@@ -77,7 +151,7 @@ function mutatingReceipts(recent) {
     if (resultId !== null) {
       const candidate = mutationCalls.get(resultId);
       if (candidate !== void 0) {
-        for (const path of candidate.paths) pushPath(paths, seen, path);
+        for (const path2 of candidate.paths) pushPath(paths, seen, path2);
       }
     }
   }
@@ -112,12 +186,12 @@ function bashExecutionMutationPaths(entry) {
   if (record.cancelled === true || record.exitCode !== 0) return null;
   return [...extractCommandWriteTargets(record.command), ...extractCommandDeleteTargets(record.command)];
 }
-function pushPath(paths, seen, path) {
-  if (path.length === 0 || seen.has(path)) return;
-  seen.add(path);
-  paths.push(path);
+function pushPath(paths, seen, path2) {
+  if (path2.length === 0 || seen.has(path2)) return;
+  seen.add(path2);
+  paths.push(path2);
 }
-function collectValidationEvidence(recent) {
+function collectValidationEvidence(recent, acceptanceChecks, workspaceRoot) {
   const evidence = [];
   const toolCalls = /* @__PURE__ */ new Map();
   const dispatchCalls = /* @__PURE__ */ new Map();
@@ -128,7 +202,7 @@ function collectValidationEvidence(recent) {
       pushEvidence(evidence, seen, protectedArtifact);
       continue;
     }
-    const call = bashValidationCall(entry);
+    const call = bashValidationCall(entry, acceptanceChecks, workspaceRoot);
     if (call !== null) {
       toolCalls.set(call.toolCallId, call);
       continue;
@@ -153,11 +227,11 @@ function collectValidationEvidence(recent) {
       }
       const candidate = toolCalls.get(resultId);
       if (candidate !== void 0) {
-        pushEvidence(evidence, seen, validationEvidence(candidate));
+        pushEvidence(evidence, seen, validationEvidence(candidate, entry));
       }
       continue;
     }
-    const bashExecution = bashExecutionEvidence(entry);
+    const bashExecution = bashExecutionEvidence(entry, acceptanceChecks, workspaceRoot);
     if (bashExecution !== null) pushEvidence(evidence, seen, bashExecution);
   }
   return evidence;
@@ -175,7 +249,7 @@ function recentEntries(entries, assistantTurnId, recentEntryLimit) {
   }
   return entries.slice(startInclusive, endExclusive);
 }
-function bashValidationCall(entry) {
+function bashValidationCall(entry, acceptanceChecks, workspaceRoot) {
   const record = asRecord(entry);
   if (record?.kind !== "message" || record.role !== "tool_call") return null;
   const payload = asRecord(record.payload);
@@ -185,13 +259,15 @@ function bashValidationCall(entry) {
   const args = asRecord(payload.args ?? payload.arguments ?? payload.input);
   const command = typeof args?.command === "string" ? args.command : null;
   if (command === null) return null;
-  const detected = detectValidationCommand(command);
+  const detected = acceptanceValidationCommand(command, acceptanceChecks);
   if (detected.kind !== "validation") return null;
   const toolCallId = stringFromFirst(payload, ["toolCallId", "tool_call_id", "id"]) ?? turnIdOf(entry);
   if (toolCallId === null) return null;
   const candidate = {
     toolCallId,
-    command: detected.matched
+    command: detected.matched,
+    ...validationCheckFields(detected.matched),
+    execution: packageCommandExecution(command, args?.cwd, workspaceRoot)
   };
   const turnId = turnIdOf(entry);
   if (turnId !== null) candidate.turnId = turnId;
@@ -245,7 +321,8 @@ function validationToolCall(entry) {
   if (toolCallId === null) return null;
   const candidate = {
     toolCallId,
-    command: summary
+    command: summary,
+    ...validationCheckFields(summary)
   };
   const turnId = turnIdOf(entry);
   if (turnId !== null) candidate.turnId = turnId;
@@ -256,8 +333,8 @@ function typedValidationSummary(toolName, payload) {
   if (toolName === "verify") {
     const check = typeof args?.check === "string" ? args.check.trim() : "";
     if (check === "frontend") {
-      const path = typeof args?.path === "string" && args.path.trim().length > 0 ? args.path.trim() : "artifact";
-      return `verify frontend ${path}`;
+      const path2 = typeof args?.path === "string" && args.path.trim().length > 0 ? args.path.trim() : "artifact";
+      return `verify frontend ${path2}`;
     }
     if (isVerificationScriptName(check)) return `npm run ${check}`;
     if (isProjectVerifierCheckId(check)) return `verify ${check}`;
@@ -273,7 +350,8 @@ function successfulToolResultId(entry) {
   if (payload.isError === true || payload.error === true) return null;
   const result = asRecord(payload.result);
   const details = asRecord(result?.details);
-  if (details?.kind === "error") return null;
+  if (result?.kind === "error" || details?.kind === "error") return null;
+  if (typeof details?.exitCode === "number" && details.exitCode !== 0) return null;
   return stringFromFirst(payload, ["toolCallId", "tool_call_id", "id"]);
 }
 function dispatchReceiptEvidence(entry, candidate) {
@@ -318,18 +396,20 @@ function dispatchReceiptAgentId(receiptAgentId, candidate) {
   if (receiptAgentId !== void 0 && receiptAgentId.length > 0) return receiptAgentId;
   return candidate?.command.match(/^agent=([^\s]+)/)?.[1] ?? "unknown";
 }
-function bashExecutionEvidence(entry) {
+function bashExecutionEvidence(entry, acceptanceChecks, workspaceRoot) {
   const record = asRecord(entry);
   if (record?.kind !== "bashExecution") return null;
   if (typeof record.command !== "string") return null;
   if (record.cancelled === true) return null;
   if (record.exitCode !== 0) return null;
-  const detected = detectValidationCommand(record.command);
+  const detected = acceptanceValidationCommand(record.command, acceptanceChecks);
   if (detected.kind !== "validation") return null;
   const contextMarker = record.excludeFromContext === true ? " [not sent to model]" : "";
   const evidence = {
     kind: "validation_command",
-    summary: `validation command passed: ${detected.matched}${contextMarker}`
+    summary: `validation command passed: ${detected.matched}${contextMarker}`,
+    ...validationCheckFields(detected.matched),
+    ...packageCommandExecution(record.command, record.cwd, workspaceRoot)
   };
   const turnId = turnIdOf(entry);
   if (turnId !== null) evidence.turnId = turnId;
@@ -339,26 +419,56 @@ function protectedArtifactEvidence(entry) {
   const record = asRecord(entry);
   if (record?.kind !== "protectedArtifact" || record.action !== "protect") return null;
   const artifact = asRecord(record.artifact);
-  const path = typeof artifact?.path === "string" && artifact.path.trim().length > 0 ? artifact.path.trim() : null;
-  if (path === null) return null;
+  const path2 = typeof artifact?.path === "string" && artifact.path.trim().length > 0 ? artifact.path.trim() : null;
+  if (path2 === null) return null;
   const evidence = {
     kind: "protected_artifact",
-    summary: `protected artifact recorded: ${path}`
+    summary: `protected artifact recorded: ${path2}`
   };
   const turnId = turnIdOf(entry);
   if (turnId !== null) evidence.turnId = turnId;
   return evidence;
 }
-function validationEvidence(candidate) {
+function validationEvidence(candidate, entry) {
   const evidence = {
     kind: "validation_command",
-    summary: `validation command passed: ${candidate.command}`
+    summary: `validation command passed: ${candidate.command}`,
+    ...candidate.check ? { check: candidate.check } : {},
+    ...candidate.execution ?? declaredCheckExecution(entry, candidate.check)
   };
   if (candidate.turnId !== void 0) evidence.turnId = candidate.turnId;
   return evidence;
 }
+function declaredCheckExecution(entry, check) {
+  const payload = asRecord(asRecord(entry)?.payload);
+  const details = asRecord(asRecord(payload?.result)?.details);
+  const source = asRecord(details?.source);
+  if (!details || details.check !== check || details.exitCode !== 0 || details.aborted === true || details.timedOut === true || details.outputCapped === true || source?.kind !== "package.json" && source?.kind !== "project-catalog" || typeof source.path !== "string" || typeof details.cwd !== "string" || !Array.isArray(details.argv) || !details.argv.every((arg) => typeof arg === "string"))
+    return {};
+  if (source.kind === "project-catalog") {
+    const argv = details.argv;
+    if (!Array.isArray(details.declaredCommand) || details.declaredCommand.length !== details.argv.length || !details.declaredCommand.every((arg, index) => arg === argv[index]) || typeof details.declaredCwd !== "string" || typeof details.declaredTimeoutMs !== "number" || typeof details.durationMs !== "number" || details.durationMs > details.declaredTimeoutMs || resolve(source.path, "../..", details.declaredCwd) !== details.cwd)
+      return {};
+  }
+  return {
+    source: { kind: source.kind, path: source.path },
+    cwd: details.cwd,
+    argv: details.argv,
+    ...typeof details.durationMs === "number" ? { durationMs: details.durationMs } : {}
+  };
+}
+function packageCommandExecution(command, cwd, workspaceRoot) {
+  if (!workspaceRoot || !/^(?:npm|pnpm|yarn|bun) /u.test(command.trim()) || validationCheckId(command.trim()) === void 0)
+    return {};
+  const executionCwd = resolve(workspaceRoot, typeof cwd === "string" ? cwd : ".");
+  return {
+    source: { kind: "package.json", path: resolve(executionCwd, "package.json") },
+    cwd: executionCwd,
+    argv: command.trim().split(/\s+/u)
+  };
+}
 function pushEvidence(evidence, seen, item) {
-  const key = `${item.kind}\0${item.summary}\0${item.turnId ?? ""}`;
+  const key = JSON.stringify(item);
   if (seen.has(key)) return;
   seen.add(key);
   evidence.push(item);
@@ -383,6 +493,19 @@ function stringFromFirst(record, keys) {
 function asRecord(value) {
   return value !== null && typeof value === "object" ? value : null;
 }
+function validationCheckId(command) {
+  return /^(?:npm|pnpm|yarn|bun) (?:run )?([a-z0-9][a-z0-9._:-]*)$/.exec(command)?.[1] ?? /^verify ([a-z0-9][a-z0-9._:-]*)$/.exec(command)?.[1];
+}
+function validationCheckFields(command) {
+  const check = validationCheckId(command);
+  return check ? { check } : {};
+}
+function acceptanceValidationCommand(command, checks) {
+  const exact = command.trim();
+  const check = /^npm run ([a-z0-9][a-z0-9._:-]*)$/.exec(exact)?.[1];
+  if (check && checks.has(check)) return { kind: "validation", matched: exact };
+  return detectValidationCommand(command);
+}
 
 // src/domains/safety/loop-detector.ts
 init_esm_shims();
@@ -481,12 +604,56 @@ function observe(state, key, now) {
   return [newState, { looping, key, count }];
 }
 
+// src/domains/safety/scope.ts
+init_esm_shims();
+import path from "node:path";
+function normalizeRoot(root) {
+  return resolvePathBoundary(process.cwd(), root);
+}
+function isSubset(worker, orchestrator) {
+  for (const action of worker.allowedActions) {
+    if (!orchestrator.allowedActions.has(action)) return false;
+  }
+  for (const root of worker.allowedWriteRoots) {
+    const covered = orchestrator.allowedWriteRoots.some(
+      (outer) => pathBoundaryEntryCovers(normalizeRoot(outer), normalizeRoot(root))
+    );
+    if (!covered) return false;
+  }
+  if (worker.allowNetwork && !orchestrator.allowNetwork) return false;
+  if (worker.allowDispatch && !orchestrator.allowDispatch) return false;
+  return true;
+}
+var READONLY_SCOPE = {
+  allowedActions: /* @__PURE__ */ new Set(["read"]),
+  allowedWriteRoots: [],
+  allowNetwork: true,
+  allowDispatch: false
+};
+var WORKSPACE_SCOPE = {
+  allowedActions: /* @__PURE__ */ new Set(["read", "write", "execute", "dispatch"]),
+  allowedWriteRoots: [asDirectoryPathBoundary(path.resolve(process.cwd()))],
+  allowNetwork: true,
+  allowDispatch: true
+};
+var CONFIRMED_SCOPE = {
+  allowedActions: /* @__PURE__ */ new Set(["read", "write", "execute", "dispatch", "system_modify"]),
+  allowedWriteRoots: [asDirectoryPathBoundary(path.resolve(process.cwd()))],
+  allowNetwork: true,
+  allowDispatch: true
+};
+
 export {
   createLoopState,
   hashToolCall,
   observe,
   DEFAULT_RECENT_ENTRY_LIMIT,
   assessFinishContract,
-  typedValidationSummary
+  recentEntries,
+  typedValidationSummary,
+  isSubset,
+  READONLY_SCOPE,
+  WORKSPACE_SCOPE,
+  CONFIRMED_SCOPE
 };
-//# sourceMappingURL=chunk-RSJ25QSL.js.map
+//# sourceMappingURL=chunk-KF6GFW6O.js.map

package/dist/{chunk-BTK3SSSK.js → chunk-KMF54VH3.js}

@@ -1,7 +1,7 @@
 import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
 import {
   init_esm_shims
-} from "./chunk-3R73A4XB.js";
+} from "./chunk-ECBHH7LU.js";
 
 // src/core/naming-events.ts
 init_esm_shims();
@@ -64,4 +64,4 @@ export {
   normalizeClioCoderEventRecord,
   normalizeClioCoderEventTree
 };
-//# sourceMappingURL=chunk-BTK3SSSK.js.map
+//# sourceMappingURL=chunk-KMF54VH3.js.map

package/dist/chunk-KPRLAMP4.js

@@ -0,0 +1,32 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  init_esm_shims
+} from "./chunk-ECBHH7LU.js";
+
+// src/domains/context/codewiki/cooperative.ts
+init_esm_shims();
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
+var INDEX_SLICE_MS = 8;
+var settled = Promise.resolve();
+function createSlicer(sliceMs = INDEX_SLICE_MS) {
+  let deadline = performance.now() + sliceMs;
+  let yields = 0;
+  return {
+    tick() {
+      if (performance.now() < deadline) return settled;
+      yields += 1;
+      return yieldToEventLoop().then(() => {
+        deadline = performance.now() + sliceMs;
+      });
+    },
+    get yields() {
+      return yields;
+    }
+  };
+}
+
+export {
+  INDEX_SLICE_MS,
+  createSlicer
+};
+//# sourceMappingURL=chunk-KPRLAMP4.js.map

package/dist/{chunk-ECH6PKUQ.js → chunk-KQ6IDQIB.js}

@@ -1,7 +1,7 @@
 import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
 import {
   init_esm_shims
-} from "./chunk-3R73A4XB.js";
+} from "./chunk-ECBHH7LU.js";
 
 // src/core/path-canonical.ts
 init_esm_shims();
@@ -36,4 +36,4 @@ function canonicalizeExistingPath(absPath) {
 export {
   canonicalizeExistingPath
 };
-//# sourceMappingURL=chunk-ECH6PKUQ.js.map
+//# sourceMappingURL=chunk-KQ6IDQIB.js.map

package/dist/{chunk-IUE3Y34X.js → chunk-KTFSFCVN.js}

@@ -1,28 +1,39 @@
 import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
 import {
   typebox_exports
-} from "./chunk-5B2AEOW5.js";
+} from "./chunk-GH5ZR6JP.js";
 import {
   ToolNames
-} from "./chunk-K6BSR66V.js";
+} from "./chunk-EHOSNVVM.js";
 import {
   StringEnum
-} from "./chunk-YPC6ZR5L.js";
+} from "./chunk-5CMARGPF.js";
 import {
   init_esm_shims
-} from "./chunk-3R73A4XB.js";
+} from "./chunk-ECBHH7LU.js";
 
 // src/tools/context/surface.ts
 init_esm_shims();
 var contextToolSurface = {
   name: ToolNames.Context,
-  description: "Environment context: scope=workspace returns the git/project snapshot, scope=docs searches Clio's bundled documentation (omit query to list the corpus), scope=skills lists installed and marketplace skills or loads an installed one by name, scope=recall returns the exact body of an evicted tool result by ref (the turnId named in an [evicted ...] marker). For repository code and the repo's generated wiki use code_nav (mode=wiki).",
+  description: "Environment context: scope=workspace returns the git/project snapshot, scope=docs searches Clio's bundled documentation (omit query to list the corpus), scope=skills lists installed and marketplace skills or loads an installed one by name, scope=recall returns an exact persisted evicted or summarized tool result by ref; omit ref to discover historical results by query with bounded limit/offset pages. For repository code and the repo's generated wiki use code_nav (mode=wiki).",
   parameters: typebox_exports.Object({
     scope: StringEnum(["workspace", "docs", "skills", "recall"], { description: "Context source." }),
-    query: typebox_exports.Optional(typebox_exports.String({ description: "scope=docs: question or terms; omit to list the corpus." })),
+    query: typebox_exports.Optional(
+      typebox_exports.String({
+        description: "scope=docs: question or terms. scope=recall without ref: path, tool, or ref terms; omit to list."
+      })
+    ),
     name: typebox_exports.Optional(typebox_exports.String({ description: "scope=skills: skill name to load; omit to list." })),
-    limit: typebox_exports.Optional(typebox_exports.Number({ description: "scope=docs: max sections (default 5, max 12)." })),
-    ref: typebox_exports.Optional(typebox_exports.String({ description: "scope=recall: ref of the evicted item, as named in its marker." })),
+    limit: typebox_exports.Optional(
+      typebox_exports.Number({
+        description: "scope=docs: max sections (default 5, max 12). scope=recall: max refs (default 8, max 12)."
+      })
+    ),
+    ref: typebox_exports.Optional(typebox_exports.String({ description: "scope=recall: exact persisted result ref; omit for discovery." })),
+    offset: typebox_exports.Optional(
+      typebox_exports.Number({ description: "scope=recall discovery: zero-based offset; follow nextOffset (default 0)." })
+    ),
     include_tree: typebox_exports.Optional(typebox_exports.Boolean({ description: "scope=skills: list files under the skill base_dir." }))
   }),
   baseActionClass: "read",
@@ -32,4 +43,4 @@ var contextToolSurface = {
 export {
   contextToolSurface
 };
-//# sourceMappingURL=chunk-IUE3Y34X.js.map
+//# sourceMappingURL=chunk-KTFSFCVN.js.map