@iowarp/clio-coder 0.4.3 → 0.4.5

package/dist/{chunk-GI7YYQ3F.js → chunk-U2JOLB7O.js}

@@ -2,73 +2,56 @@ import { createRequire as __clioCreateRequire } from "node:module"; const requir
 import {
   resolveFdBinary,
   resolveRgBinary
-} from "./chunk-BMS5RKQY.js";
+} from "./chunk-JABWPKFY.js";
 import {
   webFetchToolSurface
-} from "./chunk-MCEPRMZW.js";
+} from "./chunk-BBV5TKE6.js";
 import {
-  gitTool,
   verifyToolSurface
-} from "./chunk-ZDN3Y73Y.js";
+} from "./chunk-GXCCHKN6.js";
 import {
   codeNavToolSurface
-} from "./chunk-64I3JVYM.js";
-import {
-  compileGlobRegex,
-  fallbackIgnoredDirs,
-  fdIgnoreArgs,
-  normalizeGlobInput,
-  rgIgnoreArgs
-} from "./chunk-VG7TBQIY.js";
+} from "./chunk-PWWSIB2A.js";
 import {
   contextToolSurface
-} from "./chunk-IUE3Y34X.js";
+} from "./chunk-KTFSFCVN.js";
 import {
   RESPONSE_SCHEMA_RUNTIME_ID,
   bashTool,
   builtin,
   createAskUserTool,
-  networkToolsDisabled,
   readMaxBytes,
   readTool,
   renderAgentLedger
-} from "./chunk-PAJQJ7BS.js";
-import {
-  createTaskBoardStore,
-  taskBoardCounts
-} from "./chunk-L47TF46W.js";
+} from "./chunk-TZ7MFRG4.js";
 import {
   hashToolCall
-} from "./chunk-RSJ25QSL.js";
+} from "./chunk-KF6GFW6O.js";
 import {
-  formatModelRejection
-} from "./chunk-XIVNBFZS.js";
+  createTaskBoardStore,
+  taskBoardCounts
+} from "./chunk-7HBHHVCK.js";
 import {
   describeCallAction
-} from "./chunk-NEDJ26B5.js";
+} from "./chunk-2GPGAE5W.js";
 import {
-  applyToolProfile
-} from "./chunk-42FMPA75.js";
+  networkToolsDisabled
+} from "./chunk-SL2RDHKO.js";
 import {
+  compileGlobRegex,
+  fallbackIgnoredDirs,
+  fdIgnoreArgs,
+  normalizeGlobInput,
   resolveReadPath,
   resolveToCwd,
+  rgIgnoreArgs,
   toPosixPath
-} from "./chunk-OQE5J4C6.js";
-import {
-  classify
-} from "./chunk-B4OAX3SI.js";
-import {
-  protectArtifact,
-  protectedArtifactMutationBlockReason
-} from "./chunk-I7ZPNEJM.js";
-import {
-  CLIO_ARTIFACT_DIR,
-  artifactDefaultPath
-} from "./chunk-GYV6VZOC.js";
+} from "./chunk-V552WL53.js";
 import {
   OBSERVATION_POLICY_SLACK_BYTES,
   OBSERVE_SELF_CAPS,
   commitObservationReservation,
+  createObservationPathFilter,
   finalizeObservation,
   isDispositionedToolResultError,
   observationBudgetExhausted,
@@ -76,36 +59,58 @@ import {
   reserveObservation,
   toolResultContextText,
   truncateHead
-} from "./chunk-JDAY6FIL.js";
+} from "./chunk-RLTT5GVY.js";
 import {
   GREP_MAX_LINE_LENGTH,
   truncateLine
-} from "./chunk-OZNBF4L3.js";
+} from "./chunk-KECNXMDE.js";
 import {
-  truncateUtf8
-} from "./chunk-6XLNIQDB.js";
+  formatModelRejection
+} from "./chunk-4SVIVOMC.js";
+import {
+  applyToolProfile
+} from "./chunk-CBSKDFWL.js";
+import {
+  classify
+} from "./chunk-LUL5Z66S.js";
+import {
+  protectArtifact,
+  protectedArtifactMutationBlockReason
+} from "./chunk-M6TAYK66.js";
+import {
+  gitTool
+} from "./chunk-WJIMKGD6.js";
+import {
+  CLIO_ARTIFACT_DIR,
+  artifactDefaultPath
+} from "./chunk-NTTS3O53.js";
 import {
   typebox_exports
-} from "./chunk-5B2AEOW5.js";
+} from "./chunk-GH5ZR6JP.js";
 import {
   parseAgentLedgerBody
-} from "./chunk-VAVR4IJY.js";
+} from "./chunk-VQD7NH7Z.js";
 import {
+  decisionRef,
   skillActivationFromToolDetails
-} from "./chunk-JGRC33J2.js";
+} from "./chunk-5ZMXGW7P.js";
+import {
+  byteLength,
+  truncateUtf8
+} from "./chunk-MYI32N4R.js";
 import {
   ToolNames,
   isBuiltinToolName
-} from "./chunk-K6BSR66V.js";
+} from "./chunk-EHOSNVVM.js";
+import {
+  assertSafeId
+} from "./chunk-UHW5V7HC.js";
 import {
   BusChannels
-} from "./chunk-F4EKGO4N.js";
+} from "./chunk-HL26ADLH.js";
 import {
   incompleteInstallationAdvice
-} from "./chunk-65DEGPJ6.js";
-import {
-  buildSafeToolEnv
-} from "./chunk-JSC3U7TI.js";
+} from "./chunk-3A3CUMKA.js";
 import {
   GUARDRAIL_DEFAULTS,
   resolveGuardrail,
@@ -113,14 +118,21 @@ import {
   workerSynthesisReserveDirective,
   workerToolCallCapExceededReason,
   workerToolCallCapSynthesisReason
-} from "./chunk-S66XZJOF.js";
+} from "./chunk-C27U2TYG.js";
+import {
+  buildSafeToolEnv
+} from "./chunk-GJ24ODAX.js";
 import {
   StringEnum,
   engineStreamSimple
-} from "./chunk-YPC6ZR5L.js";
+} from "./chunk-5CMARGPF.js";
+import {
+  clioDataDir,
+  clioStateDir
+} from "./chunk-CTTI7G3T.js";
 import {
   init_esm_shims
-} from "./chunk-3R73A4XB.js";
+} from "./chunk-ECBHH7LU.js";
 
 // src/domains/safety/protected-artifacts-registration.ts
 init_esm_shims();
@@ -385,8 +397,9 @@ function readOrchTurnToolCallBudget() {
 }
 function createLoopGuardRegistration(options) {
   const budget = options.turnBlockBudget ?? INTERACTIVE_LOOP_BLOCK_BUDGET;
-  const cap = options.toolCallCap;
-  let softLimit = options.toolCallSoftLimit !== void 0 && Number.isSafeInteger(options.toolCallSoftLimit) && options.toolCallSoftLimit > 0 && (cap === void 0 || options.toolCallSoftLimit <= cap) ? options.toolCallSoftLimit : void 0;
+  const cap = options.toolBudgetAdvisory ? void 0 : options.toolCallCap;
+  let advisoryEmitted = false;
+  let softLimit = !options.toolBudgetAdvisory && options.toolCallSoftLimit !== void 0 && Number.isSafeInteger(options.toolCallSoftLimit) && options.toolCallSoftLimit > 0 && (cap === void 0 || options.toolCallSoftLimit <= cap) ? options.toolCallSoftLimit : void 0;
   const synthesisLockout = options.turnSynthesisLockout === true;
   let softReadReserve = options.toolCallSoftReadReserve ?? 0;
   let softReadReserveThreshold = softLimit !== void 0 && softReadReserve > 0 && softLimit > softReadReserve ? softLimit - softReadReserve : null;
@@ -396,7 +409,7 @@ function createLoopGuardRegistration(options) {
   let softReadReserveEntered = false;
   let reserveDenials = { denials: 0 };
   let deniedAttempts = 0;
-  const denialBudget = cap === void 0 ? void 0 : Math.max(cap, WIDE_BATCH_DENIAL_FLOOR);
+  const denialBudget = options.toolCallCap === void 0 ? void 0 : Math.max(options.toolCallCap, WIDE_BATCH_DENIAL_FLOOR);
   const boundRunDenials = (effects, input) => {
     if (denialBudget === void 0 || !effects.some((effect) => effect.kind === "block_tool")) return effects;
     deniedAttempts += 1;
@@ -623,6 +636,14 @@ function createLoopGuardRegistration(options) {
         recordSuccessfulResult(input);
         recordResultForStagnation(input);
         const effects = [...crossArgumentResultEffects(input)];
+        if (options.toolBudgetAdvisory && !advisoryEmitted && count >= (options.toolCallSoftLimit ?? options.toolCallCap ?? Infinity)) {
+          advisoryEmitted = true;
+          effects.push({
+            kind: "annotate_tool_result",
+            message: `Advisory tool estimate reached (${count} calls). Reassess remaining work and finish the assignment; tools remain available. Explicit task requirements still apply.`,
+            severity: "warn"
+          });
+        }
         if (softReadReserveEntered && softLockout === null && deliveryTools.length === 0 && input.toolName === ToolNames.Read) {
           effects.push({ kind: "require_tool", toolName: ToolNames.Read });
         }
@@ -835,7 +856,7 @@ function projectToolResult(result) {
     return { content: [{ type: "text", text: toolResultContextText(result) }], details };
   }
   return {
-    content: [{ type: "text", text: toolResultContextText(result) }],
+    content: [{ type: "text", text: toolResultContextText(result) }, ...result.images ?? []],
     details,
     ...result.terminate === true ? { terminate: true } : {}
   };
@@ -905,7 +926,7 @@ async function runValidatedToolCall(input) {
   const toolDetails = isRecord(verdict.result.details) ? verdict.result.details : {};
   const skillActivation = spec.name === ToolNames.Context ? skillActivationFromToolDetails(toolDetails, input.invokeOptions?.turnId) : null;
   const result = {
-    content: [{ type: "text", text: toolResultContextText(verdict.result) }],
+    content: [{ type: "text", text: toolResultContextText(verdict.result) }, ...verdict.result.images ?? []],
     details: { ...toolDetails, kind: "ok" }
   };
   if (verdict.result.terminate === true) {
@@ -1023,7 +1044,10 @@ function effectiveToolNames(input) {
 function resolveSessionTools(runtime, toolRegistry, invokeOptions, telemetry) {
   if (!toolRegistry || runtime.runtimeResolution.capabilityDecisions.tools !== true) return [];
   const input = { registry: toolRegistry };
-  if (invokeOptions) input.invokeOptions = invokeOptions;
+  input.invokeOptions = () => ({
+    ...invokeOptions?.(),
+    supportsImages: runtime.runtimeResolution.capabilityDecisions.vision === true
+  });
   if (telemetry) input.telemetry = telemetry;
   return resolveAgentTools(input);
 }
@@ -1111,7 +1135,7 @@ function patchToolChoiceNamedPayload(payload, model, toolName) {
       if (Object.keys(outputConfig).length > 0) patched.output_config = outputConfig;
       else delete patched.output_config;
     }
-    return { ...patched, tools: tools2, tool_choice: { type: "tool", name: toolName } };
+    return { ...patched, tool_choice: { type: "tool", name: toolName } };
   }
   if (model.api === "google-generative-ai" || model.api === "google-vertex") {
     if (!isRecord2(payload.config) || payload.config.tools === void 0 || payload.config.tools === null)
@@ -1486,6 +1510,115 @@ var credentialPresentTool = {
   }
 };
 
+// src/tools/decide.ts
+init_esm_shims();
+var DECIDE_CAPS = Object.freeze({
+  keyBytes: 64,
+  valueBytes: 512,
+  alternatives: 6,
+  alternativeBytes: 256,
+  rationaleBytes: 1024,
+  labelBytes: 128
+});
+var KEBAB_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+function boundedText(value, field, cap) {
+  if (typeof value !== "string") return new Error(`decide: ${field} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return new Error(`decide: ${field} is required`);
+  if (byteLength(trimmed) > cap) return new Error(`decide: ${field} exceeds the ${cap}-byte cap`);
+  return trimmed;
+}
+function boundedAlternatives(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    return new Error("decide: alternatives must list at least one option you rejected");
+  }
+  if (value.length > DECIDE_CAPS.alternatives) {
+    return new Error(`decide: alternatives exceeds the ${DECIDE_CAPS.alternatives}-entry cap`);
+  }
+  const alternatives = [];
+  for (const [index, entry] of value.entries()) {
+    const text = boundedText(entry, `alternatives[${index}]`, DECIDE_CAPS.alternativeBytes);
+    if (text instanceof Error) return text;
+    alternatives.push(text);
+  }
+  return alternatives;
+}
+function createDecideTool(deps = {}) {
+  return {
+    name: ToolNames.Decide,
+    description: "Record a design decision between viable options, with rejected alternatives and rationale, before implementing. Verify implementation against the active choice before commit; decision trailers do not prove adherence. If policy changes, a call with the same key revises your earlier agent choice; operator choices require operator revision through ask_user. Record the revision before commit.",
+    parameters: typebox_exports.Object({
+      key: typebox_exports.String({
+        description: `Stable kebab-case name for the decision, e.g. "cache-key-shape" (at most ${DECIDE_CAPS.keyBytes} bytes).`
+      }),
+      value: typebox_exports.String({ description: `The option you chose (at most ${DECIDE_CAPS.valueBytes} bytes).` }),
+      alternatives: typebox_exports.Array(typebox_exports.String(), {
+        description: `Options you considered and rejected, 1 to ${DECIDE_CAPS.alternatives} entries.`
+      }),
+      rationale: typebox_exports.String({
+        description: `Why the chosen option won over the alternatives (at most ${DECIDE_CAPS.rationaleBytes} bytes).`
+      }),
+      label: typebox_exports.Optional(typebox_exports.String({ description: "Short human-readable title for the decision." }))
+    }),
+    // Read class on purpose: the only effect is one session-ledger append,
+    // so it must stay available at every autonomy level without a prompt.
+    baseActionClass: "read",
+    executionMode: "sequential",
+    async run(args) {
+      const key = boundedText(args.key, "key", DECIDE_CAPS.keyBytes);
+      if (key instanceof Error) return { kind: "error", message: key.message };
+      if (!KEBAB_KEY.test(key)) {
+        return { kind: "error", message: "decide: key must be kebab-case (lowercase letters, digits, single hyphens)" };
+      }
+      const value = boundedText(args.value, "value", DECIDE_CAPS.valueBytes);
+      if (value instanceof Error) return { kind: "error", message: value.message };
+      const alternatives = boundedAlternatives(args.alternatives);
+      if (alternatives instanceof Error) return { kind: "error", message: alternatives.message };
+      const rationale = boundedText(args.rationale, "rationale", DECIDE_CAPS.rationaleBytes);
+      if (rationale instanceof Error) return { kind: "error", message: rationale.message };
+      let label;
+      if (args.label !== void 0 && args.label !== null) {
+        const bounded = boundedText(args.label, "label", DECIDE_CAPS.labelBytes);
+        if (bounded instanceof Error) return { kind: "error", message: bounded.message };
+        label = bounded;
+      }
+      if (deps.decisionBoard === void 0) {
+        return { kind: "error", message: "decide: no session decision board is available in this context" };
+      }
+      let outcome;
+      try {
+        outcome = deps.decisionBoard.recordAgentDecision({
+          key,
+          value,
+          alternatives,
+          rationale,
+          ...label !== void 0 ? { label } : {}
+        });
+      } catch (error) {
+        return { kind: "error", message: error instanceof Error ? error.message : String(error) };
+      }
+      const ref = decisionRef(outcome.entry.interviewId, key);
+      const supersededNote = outcome.superseded === null ? "" : ` (supersedes ${decisionRef(outcome.superseded.interviewId, outcome.superseded.key)})`;
+      return {
+        kind: "ok",
+        output: `decision recorded: ${key} = ${value} [${ref}]${supersededNote}
+`,
+        details: {
+          decision: {
+            ref,
+            key,
+            value,
+            alternatives,
+            rationale,
+            ...label !== void 0 ? { label } : {},
+            ...outcome.superseded !== null ? { superseded: decisionRef(outcome.superseded.interviewId, outcome.superseded.key) } : {}
+          }
+        }
+      };
+    }
+  };
+}
+
 // src/tools/edit.ts
 init_esm_shims();
 import { readFileSync, writeFileSync as writeFileSync2 } from "node:fs";
@@ -1493,10 +1626,10 @@ import { readFileSync, writeFileSync as writeFileSync2 } from "node:fs";
 // src/tools/edit-diff.ts
 init_esm_shims();
 
-// node_modules/diff/libesm/index.js
+// node_modules/.pnpm/diff@9.0.0/node_modules/diff/libesm/index.js
 init_esm_shims();
 
-// node_modules/diff/libesm/diff/base.js
+// node_modules/.pnpm/diff@9.0.0/node_modules/diff/libesm/diff/base.js
 init_esm_shims();
 var Diff = class {
   diff(oldStr, newStr, options = {}) {
@@ -1699,10 +1832,10 @@ var Diff = class {
   }
 };
 
-// node_modules/diff/libesm/diff/word.js
+// node_modules/.pnpm/diff@9.0.0/node_modules/diff/libesm/diff/word.js
 init_esm_shims();
 
-// node_modules/diff/libesm/util/string.js
+// node_modules/.pnpm/diff@9.0.0/node_modules/diff/libesm/util/string.js
 init_esm_shims();
 function longestCommonPrefix(str1, str2) {
   let i;
@@ -1831,7 +1964,7 @@ function leadingAndTrailingWs(string, segmenter) {
   return [head, tail];
 }
 
-// node_modules/diff/libesm/diff/word.js
+// node_modules/.pnpm/diff@9.0.0/node_modules/diff/libesm/diff/word.js
 var extendedWordChars = "a-zA-Z0-9_\\u{AD}\\u{C0}-\\u{D6}\\u{D8}-\\u{F6}\\u{F8}-\\u{2C6}\\u{2C8}-\\u{2D7}\\u{2DE}-\\u{2FF}\\u{1E00}-\\u{1EFF}";
 var tokenizeIncludingWhitespace = new RegExp(`[${extendedWordChars}]+|\\s+|[^${extendedWordChars}]`, "ug");
 var WordDiff = class extends Diff {
@@ -1974,7 +2107,7 @@ function diffWordsWithSpace(oldStr, newStr, options) {
   return wordsWithSpaceDiff.diff(oldStr, newStr, options);
 }
 
-// node_modules/diff/libesm/diff/line.js
+// node_modules/.pnpm/diff@9.0.0/node_modules/diff/libesm/diff/line.js
 init_esm_shims();
 var LineDiff = class extends Diff {
   constructor() {
@@ -2515,6 +2648,88 @@ var editTool = {
   }
 };
 
+// src/tools/evidence.ts
+init_esm_shims();
+var EVIDENCE_TOOL_MAX_BYTES = 16384;
+function boundedResult(value) {
+  const serialized = JSON.stringify(value, null, 2);
+  if (Buffer.byteLength(serialized, "utf8") <= EVIDENCE_TOOL_MAX_BYTES) {
+    return { kind: "ok", output: serialized, details: { truncated: false } };
+  }
+  const hint = "Inspect one run to narrow the output; this preview is incomplete JSON text.";
+  let preview = truncateUtf8(serialized, EVIDENCE_TOOL_MAX_BYTES, "");
+  let output = JSON.stringify({ truncated: true, hint, preview });
+  while (Buffer.byteLength(output, "utf8") > EVIDENCE_TOOL_MAX_BYTES) {
+    const excess = Buffer.byteLength(output, "utf8") - EVIDENCE_TOOL_MAX_BYTES;
+    preview = truncateUtf8(preview, Math.max(0, Buffer.byteLength(preview, "utf8") - excess), "");
+    output = JSON.stringify({ truncated: true, hint, preview });
+  }
+  return { kind: "ok", output, details: { truncated: true } };
+}
+var evidenceTool = {
+  name: ToolNames.Evidence,
+  description: "Read canonical evidence as JSON. List recent bundles, inspect a bundle's overview, trust axes and tier, gate decisions, and findings, or build/read evidence for a run.",
+  parameters: typebox_exports.Object({
+    mode: StringEnum(["list", "inspect", "run"]),
+    id: typebox_exports.Optional(typebox_exports.String({ description: "Evidence bundle id for inspect." })),
+    runId: typebox_exports.Optional(typebox_exports.String({ description: "Run id for run." }))
+  }),
+  baseActionClass: "read",
+  // Run mode may materialize a derived bundle in Clio's data directory.
+  executionMode: "sequential",
+  async run(args) {
+    const mode = args.mode;
+    if (mode !== "list" && mode !== "inspect" && mode !== "run") {
+      return { kind: "error", message: "evidence: mode must be list, inspect, or run" };
+    }
+    try {
+      const dataDir = clioDataDir();
+      if (mode === "list") {
+        const { evidenceInventorySnapshot } = await import("./inventory-K2OZ36YJ.js");
+        return boundedResult(await evidenceInventorySnapshot(Date.now, dataDir));
+      }
+      const id = mode === "inspect" ? args.id : args.runId;
+      if (typeof id !== "string" || id.length === 0) {
+        return { kind: "error", message: `evidence: ${mode} requires ${mode === "inspect" ? "id" : "runId"}` };
+      }
+      assertSafeId(id, mode === "inspect" ? "evidence" : "run");
+      const { buildEvidence, EvidenceNotFoundError, inspectEvidence, loadEvidenceGateDecisions } = await import("./evidence-DTGEN456.js");
+      const { evidenceDetailSnapshot } = await import("./detail-5572VLBO.js");
+      let evidenceId = mode === "run" ? `run-${id}` : id;
+      let inspected;
+      try {
+        inspected = await inspectEvidence(dataDir, evidenceId);
+      } catch (error) {
+        if (mode !== "run" || !(error instanceof EvidenceNotFoundError)) throw error;
+        try {
+          evidenceId = (await buildEvidence({ dataDir, stateDir: clioStateDir(), runId: id })).evidenceId;
+        } catch (buildError) {
+          if (buildError instanceof Error && (buildError.message === "run ledger not found" || buildError.message === `run not found: ${id}`))
+            throw new EvidenceNotFoundError(evidenceId);
+          throw buildError;
+        }
+        inspected = await inspectEvidence(dataDir, evidenceId);
+      }
+      return boundedResult({
+        ...inspected,
+        ...await evidenceDetailSnapshot(evidenceId, Date.now, dataDir),
+        gateDecisions: await loadEvidenceGateDecisions(dataDir, evidenceId)
+      });
+    } catch (error) {
+      const absent = error instanceof Error && error.name === "EvidenceNotFoundError";
+      return {
+        kind: "error",
+        message: truncateUtf8(
+          `evidence: ${error instanceof Error ? error.message : String(error)}`,
+          EVIDENCE_TOOL_MAX_BYTES - 3,
+          "..."
+        ),
+        details: { code: absent ? "artifact_absent" : "evidence_error", artifactAbsent: absent }
+      };
+    }
+  }
+};
+
 // src/tools/find.ts
 init_esm_shims();
 import { existsSync, statSync } from "node:fs";
@@ -2729,11 +2944,13 @@ function renderFindResult(input) {
   if (ordered.paths.length === 0) {
     return finalizeObservation({
       tool: ToolNames.Find,
+      withheldPaths: input.withheldPaths,
       unit: "paths",
-      output: "No files found matching pattern",
+      output: "No visible files found matching pattern",
       shownCount: 0,
-      totalCount: 0,
-      truncated: false,
+      totalCount: collected >= collectLimit ? null : 0,
+      truncated: collected >= collectLimit,
+      ...collected >= collectLimit ? { next: `limit=${limit * 2}` } : {},
       reservation,
       ...options ? { options } : {}
     });
@@ -2758,6 +2975,7 @@ function renderFindResult(input) {
   }
   return finalizeObservation({
     tool: ToolNames.Find,
+    withheldPaths: input.withheldPaths,
     unit: "paths",
     output: truncation.content,
     // Offload only when the byte cap cut collected paths; a bare result
@@ -2827,10 +3045,14 @@ var findTool = {
           return { kind: "error", message: `find: ${message}` };
         }
       }
+      const collectedCount = collectedPaths.length;
+      const pathFilter = createObservationPathFilter(process.cwd(), options?.allowsObservationPath);
+      collectedPaths = collectedPaths.filter((entry) => pathFilter.allows(join(searchPath, entry)));
       const ordered = order === "mtime" ? orderByMtime(collectedPaths, searchPath, limit, collectLimit) : { paths: collectedPaths.slice(0, limit), candidateCapHit: false, candidateCap: null };
       return renderFindResult({
+        withheldPaths: pathFilter.withheldPaths,
         ordered,
-        collected: collectedPaths.length,
+        collected: collectedCount,
         collectLimit,
         limit,
         order,
@@ -2880,6 +3102,7 @@ function renderGrepResult(input) {
   if (lines.length === 0) {
     return finalizeObservation({
       tool: ToolNames.Grep,
+      withheldPaths: input.withheldPaths,
       unit: MODE_UNITS[mode],
       output: NO_MATCH_OUTPUT,
       shownCount: 0,
@@ -2910,6 +3133,7 @@ function renderGrepResult(input) {
   }
   return finalizeObservation({
     tool: ToolNames.Grep,
+    withheldPaths: input.withheldPaths,
     unit: MODE_UNITS[mode],
     output,
     // Offload only when the byte cap cut collected content; a bare match
@@ -2965,6 +3189,7 @@ async function runRipgrep(input) {
     const lineNumber = data?.line_number;
     const lineText = data?.lines?.text;
     if (typeof filePath !== "string" || typeof lineNumber !== "number" || typeof lineText !== "string") return;
+    if (!input.pathFilter.allows(filePath)) return;
     const { text, wasTruncated } = truncateLine(sanitizeMatchText(lineText));
     if (wasTruncated) linesTruncated = true;
     const isMatch = type === "match";
@@ -2983,6 +3208,8 @@ async function runRipgrep(input) {
   const onListLine = (line, stop) => {
     const trimmed = line.replace(/\r$/, "");
     if (trimmed.length === 0) return;
+    const filePath = input.mode === "count" ? trimmed.slice(0, trimmed.lastIndexOf(":")) : trimmed;
+    if (!input.pathFilter.allows(filePath)) return;
     let text;
     if (input.mode === "count") {
       const sep = trimmed.lastIndexOf(":");
@@ -3013,6 +3240,7 @@ async function runRipgrep(input) {
     return { kind: "error", message: `grep: ${result.stderr.trim() || `ripgrep exited with code ${result.exitCode}`}` };
   }
   return renderGrepResult({
+    withheldPaths: input.pathFilter.withheldPaths,
     mode: input.mode,
     lines: rendered,
     matchCount,
@@ -3065,7 +3293,7 @@ function fallbackGrep(input) {
     rendered.push({ text: truncatedLine.text, isMatch });
   };
   const searchFile = (filePath) => {
-    if (limitHit) return;
+    if (limitHit || !input.pathFilter.allows(filePath)) return;
     let buffer;
     try {
       const stat = statSync2(filePath);
@@ -3138,6 +3366,7 @@ function fallbackGrep(input) {
   else searchFile(input.searchPath);
   if (signal?.aborted) return { kind: "error", message: "grep: operation aborted" };
   return renderGrepResult({
+    withheldPaths: input.pathFilter.withheldPaths,
     mode: input.mode,
     lines: rendered,
     matchCount,
@@ -3195,6 +3424,7 @@ var grepTool = {
       });
     }
     const shared = {
+      pathFilter: createObservationPathFilter(process.cwd(), options?.allowsObservationPath),
       mode,
       pattern,
       searchPath,
@@ -3370,6 +3600,59 @@ ${output}`,
   };
 }
 
+// src/tools/limitation.ts
+init_esm_shims();
+var LIMITATION_REASONS = ["no-runner", "blocked", "out-of-scope", "environment", "other"];
+function isLimitationReason(value) {
+  return typeof value === "string" && LIMITATION_REASONS.includes(value);
+}
+function trimString2(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function normalizePaths(value) {
+  if (value === void 0 || value === null) return [];
+  if (!Array.isArray(value)) return null;
+  const paths = [];
+  for (const item of value) {
+    const path4 = trimString2(item);
+    if (path4 === null) return null;
+    if (!paths.includes(path4)) paths.push(path4);
+  }
+  return paths;
+}
+var limitationTool = {
+  name: ToolNames.Limitation,
+  description: "Record what this turn could not verify and why. Call it once, before your final reply, when you changed files but could not run validation; the receipt stands in for validation evidence at the finish gate.",
+  parameters: typebox_exports.Object({
+    scope: typebox_exports.String({ description: "What could not be verified, in one sentence." }),
+    reason: StringEnum(LIMITATION_REASONS, {
+      description: "no-runner: no test or build runner is available; blocked: a safety gate or denial stopped the check; out-of-scope: verification was excluded by the task; environment: the environment cannot run the check; other."
+    }),
+    paths: typebox_exports.Optional(typebox_exports.Array(typebox_exports.String(), { description: "Repository-relative paths left unverified." }))
+  }),
+  baseActionClass: "read",
+  executionMode: "parallel",
+  async run(args) {
+    const scope = trimString2(args.scope);
+    if (scope === null) return { kind: "error", message: "limitation: scope is required" };
+    if (!isLimitationReason(args.reason)) {
+      return { kind: "error", message: `limitation: reason must be one of ${LIMITATION_REASONS.join(", ")}` };
+    }
+    const paths = normalizePaths(args.paths);
+    if (paths === null) return { kind: "error", message: "limitation: paths must be an array of non-empty strings" };
+    const limitation = { scope, reason: args.reason, paths };
+    const pathSuffix = paths.length > 0 ? ` paths=${paths.join(",")}` : "";
+    return {
+      kind: "ok",
+      output: `limitation recorded: ${scope} (reason=${limitation.reason}${pathSuffix})
+`,
+      details: { limitation }
+    };
+  }
+};
+
 // src/tools/ls.ts
 init_esm_shims();
 import { readdirSync as readdirSync2, statSync as statSync3 } from "node:fs";
@@ -3411,7 +3694,8 @@ var lsTool = {
       });
     }
     try {
-      const entries = readdirSync2(root).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+      const pathFilter = createObservationPathFilter(process.cwd(), options?.allowsObservationPath);
+      const entries = readdirSync2(root).filter((entry) => pathFilter.allows(path3.join(root, entry))).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
       const outputEntries = [];
       let entryLimitReached = false;
       for (const entry of entries) {
@@ -3428,6 +3712,7 @@ var lsTool = {
       if (outputEntries.length === 0) {
         return finalizeObservation({
           tool: ToolNames.Ls,
+          withheldPaths: pathFilter.withheldPaths,
           unit: "entries",
           output: "(empty directory)",
           shownCount: 0,
@@ -3445,6 +3730,7 @@ var lsTool = {
       const truncated = entryLimitReached || truncation.truncated;
       return finalizeObservation({
         tool: ToolNames.Ls,
+        withheldPaths: pathFilter.withheldPaths,
         unit: "entries",
         output: truncation.content,
         // Offload only when the byte cap cut collected entries; a bare
@@ -3467,6 +3753,7 @@ var lsTool = {
 // src/tools/policy.ts
 init_esm_shims();
 var TOOL_PLANES = {
+  [ToolNames.Evidence]: { plane: "observe", actionClass: "read", executionMode: "sequential" },
   [ToolNames.Read]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
   [ToolNames.Grep]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
   [ToolNames.Find]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
@@ -3499,6 +3786,14 @@ var TOOL_PLANES = {
   // panes. It mutates no workspace, so it stays read class; sequential because
   // two pane operations in one batch would race the same pane registry.
   [ToolNames.Panes]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
+  // limitation records a typed receipt in the session ledger and nothing
+  // else: no filesystem, no shell. Read class so it never trips a safety
+  // gate; parallel because the call is pure and idempotent.
+  [ToolNames.Limitation]: { plane: "orchestrate", actionClass: "read", executionMode: "parallel" },
+  // decide appends one decision-board entry to the session ledger and
+  // nothing else. Read class so it never trips a safety gate; sequential so
+  // two decisions in one batch never race the supersede lookup.
+  [ToolNames.Decide]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
   [ToolNames.WebFetch]: { plane: "retrieve", actionClass: "read", executionMode: "parallel" },
   [ToolNames.AskUser]: { plane: "interact", actionClass: "read", executionMode: "sequential" },
   [ToolNames.Artifact]: { plane: "artifact", actionClass: "write", executionMode: "sequential" }
@@ -3593,7 +3888,7 @@ var STATUS_MARK = {
 };
 function waitingTrailer(tasks) {
   return tasks.filter((task) => task.status === "open" || task.status === "handed").map(
-    (task) => `operator tasks waiting: ${task.id} ${JSON.stringify(task.title)} \u2014 pick up with action="pick" id="${task.id}"`
+    (task) => `operator tasks waiting: ${task.id} ${JSON.stringify(task.title)} \u2014 durable status=${task.status}; not completed; pick only if this is the intended operator task, with action="pick" id="${task.id}" before work`
   );
 }
 function renderTaskBoardText(board, userTasks = []) {
@@ -3605,9 +3900,28 @@ function renderTaskBoardText(board, userTasks = []) {
     if (task.status === "blocked" && task.reason) line += ` \u2014 blocked: ${task.reason}`;
     if (task.status === "cancelled" && task.reason) line += ` \u2014 dropped: ${task.reason}`;
     lines.push(line);
+    const operatorTask = userTasks.find((item) => item.id === task.userTaskId);
+    if (task.userTaskId) {
+      lines.push(
+        `  operator task ${task.userTaskId}: durable status=${operatorTask?.status ?? "unavailable"}; session=${operatorTask?.handedSessionId ?? "unlinked"}; board task=${operatorTask?.boardTaskId ?? "unlinked"}`
+      );
+    }
+    const outputs = operatorTask?.acceptance?.expectedOutputs;
+    if (outputs?.length) lines.push(`  expected outputs: ${outputs.join(", ")}`);
+    for (const item of task.requiredValidationEvidence ?? []) {
+      if (item.status === "required") {
+        lines.push(
+          `  acceptance requirement: ${item.command} (${item.notes}; declaration only; execution status is in verification receipts)`
+        );
+      } else {
+        lines.push(`  acceptance: ${item.command} (${item.status}; ${item.notes})`);
+      }
+    }
   }
   if (counts.open > 0 && counts.active === 0) {
-    lines.push(`next: start a task with action="start" before working it`);
+    lines.push(
+      `next: start only an authorized task with action="start" before working it; block proposed implementation with a note naming the pending operator decision, or drop it, and wait`
+    );
   }
   lines.push(...waitingTrailer(userTasks));
   return lines.join("\n");
@@ -3672,7 +3986,7 @@ function createTasksTool(deps) {
   };
   return {
     name: ToolNames.Tasks,
-    description: "Session task board. plan declares a titled board (replaces any prior board); add appends tasks; pick moves one operator task uN onto the board; start marks one task active (the current focus); done completes a task (started or still pending) and requires note as the evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. Work that did not happen is blocked or dropped, never done.",
+    description: "Session task board. plan declares a titled board (replaces any prior board); add appends tasks; pick moves one operator task uN onto the board; start marks one task active (the current focus); done completes a task (started or still pending) and requires note as the evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. For an operator handoff, pick the intended uN before work and use its returned linked tN; CLI hand alone does not pick it. Never pick unrelated inbox tasks. Before claiming operator completion, list and confirm the linked board row is completed and the durable operator status is done with the same session/board link; report those IDs and actual states. Work that did not happen is blocked or dropped, never done. A self-created plan is not operator authorization. For proposal-only work, block deferred implementation with note naming the pending operator decision, or drop it; wait for an explicit operator go-ahead before start or implementation. A skill-install choice does not grant that go-ahead.",
     parameters: typebox_exports.Object({
       action: StringEnum(TASKS_ACTIONS, { description: "Board action." }),
       title: typebox_exports.Optional(typebox_exports.String({ description: "Board title (plan)." })),
@@ -3716,7 +4030,10 @@ function createTasksTool(deps) {
       if (typedAction === "list") {
         const board = deps.board.snapshot();
         if (!board) {
-          const output2 = ['no task board yet; declare one with action="plan"', ...waitingTrailer(userTasks)].join("\n");
+          const output2 = [
+            'no task board yet; for an operator handoff, pick the intended uN before work; otherwise declare one with action="plan"',
+            ...waitingTrailer(userTasks)
+          ].join("\n");
           return {
             kind: "ok",
             output: output2,
@@ -3738,7 +4055,12 @@ function createTasksTool(deps) {
         if (userTask.status !== "open" && userTask.status !== "handed") {
           return { kind: "error", message: `tasks: operator task ${id} is ${userTask.status}; it cannot be picked` };
         }
-        const result2 = deps.board.apply({ op: "pick", title: userTask.title, userTaskId: userTask.id });
+        const result2 = deps.board.apply({
+          op: "pick",
+          title: userTask.title,
+          userTaskId: userTask.id,
+          ...userTask.acceptance ? { verification: userTask.acceptance.verification } : {}
+        });
         if (!result2.ok) return { kind: "error", message: `tasks: ${result2.message}` };
         const picked = result2.board.tasks.find((task) => task.userTaskId === userTask.id && task.status === "pending");
         if (!picked) return { kind: "error", message: `tasks: durable pickup for ${id} did not produce a board row` };
@@ -3840,6 +4162,7 @@ note: ${pathArg} no longer ends with a newline; the previous content did`;
 // src/tools/core-bootstrap.ts
 function registerCoreTools(registry, deps = {}) {
   const includeNetworkTools = !networkToolsDisabled();
+  registry.register(builtin(evidenceTool, { path: "src/tools/evidence.ts", scope: "core" }));
   registry.register({
     ...builtin(readTool, { path: "src/tools/read.ts", scope: "core" })
   });
@@ -3864,7 +4187,7 @@ function registerCoreTools(registry, deps = {}) {
   if (includeNetworkTools) {
     registry.register({
       ...builtin(
-        lazyTool(webFetchToolSurface, async () => (await import("./web-fetch-MPARV2K7.js")).webFetchTool),
+        lazyTool(webFetchToolSurface, async () => (await import("./web-fetch-MQN4FH3X.js")).webFetchTool),
         { path: "src/tools/web-fetch.ts", scope: "core" }
       )
     });
@@ -3874,13 +4197,13 @@ function registerCoreTools(registry, deps = {}) {
   });
   registry.register({
     ...builtin(
-      lazyTool(verifyToolSurface, async () => (await import("./verify-RWE4PPEK.js")).verifyTool),
+      lazyTool(verifyToolSurface, async () => (await import("./verify-3AS3ULCY.js")).verifyTool),
       { path: "src/tools/verify/index.ts", scope: "core" }
     )
   });
   registry.register({
     ...builtin(
-      lazyTool(codeNavToolSurface, async () => (await import("./code-nav-MDZNQS33.js")).codeNavTool),
+      lazyTool(codeNavToolSurface, async () => (await import("./code-nav-YXIAEZVS.js")).codeNavTool),
       { path: "src/tools/codewiki/code-nav.ts", scope: "core" }
     )
   });
@@ -3900,14 +4223,23 @@ function registerCoreTools(registry, deps = {}) {
   registry.register({
     ...builtin(credentialPresentTool, { path: "src/tools/credential-present.ts", scope: "core" })
   });
+  registry.register({
+    ...builtin(limitationTool, { path: "src/tools/limitation.ts", scope: "core" })
+  });
+  registry.register({
+    ...builtin(createDecideTool(deps.decisionBoard ? { decisionBoard: deps.decisionBoard } : {}), {
+      path: "src/tools/decide.ts",
+      scope: "core"
+    })
+  });
   const session = deps.session;
   const readSessionEntries = deps.readSessionEntries;
   registry.register({
     ...builtin(
       lazyTool(contextToolSurface, async () => {
-        const { createContextTool } = await import("./context-VNCR7KAG.js");
+        const { createContextTool } = await import("./context-QQ53HSGJ.js");
         if (!session) return createContextTool(skillToolDeps);
-        const { probeWorkspace } = await import("./workspace-ZJ6BFM3Q.js");
+        const { probeWorkspace } = await import("./workspace-DZ7JADBG.js");
         return createContextTool({
           ...skillToolDeps,
           ...readSessionEntries ? {
@@ -4003,4 +4335,4 @@ export {
   registerCoreTools,
   assertRegisteredBuiltinTools
 };
-//# sourceMappingURL=chunk-GI7YYQ3F.js.map
+//# sourceMappingURL=chunk-U2JOLB7O.js.map