@vincemakes/kiso-tools-node 0.48.0 → 0.50.0

package/dist/index.d.ts

@@ -61,7 +61,8 @@ export declare function shellProgressPath(sessionId: string | undefined, command
 export declare function escapeResult(reason: string): ToolResult;
 /**
  * Resolve an input path strictly inside the workspace (Area 5):
- * - absolute inputs are refused (paths are workspace-relative);
+ * - an absolute input is taken as the workspace-relative path it names when
+ *   it lies inside the root, and refused otherwise;
  * - `..` components cannot escape because the joined path is re-checked
  *   against the canonical root;
  * - SYMLINKS cannot escape: the deepest existing ancestor is realpath'd
@@ -117,6 +118,12 @@ export interface WorkspaceToolsOptions {
      *  serves the session's task outputs. Absent: today's shell, its schema
      *  byte for byte. */
     readonly tasks?: (sessionId: string | undefined) => ShellTasks | undefined;
+    /** O1 — the hidden observed revision. When present, edit_file and
+     *  write_file take no expectedRevision (the model-facing schema drops
+     *  it): the host returns the revision the model last OBSERVED for the
+     *  file (undefined: never observed — the call is refused). Absent:
+     *  the explicit expectedRevision protocol, its schema byte for byte. */
+    readonly observedRevision?: (sessionId: string | undefined, full: string, kind?: "edit" | "write") => string | undefined;
     /**
      * DC-54 — the bounds that keep a tool call finite. Every field is
      * optional and defaults to the constant beside it; a host embedding
@@ -160,6 +167,11 @@ export interface WorkspaceToolsOptions {
          *  the default wait). A shorter `foregroundMs` is raised to it; 0
          *  keeps the model's value as asked (ADR-0058 Amendment 10). */
         readonly minForegroundMs?: number;
+        /** shell, with tasks wired: the longest foreground wait (default 5
+         *  min). A longer `foregroundMs` is lowered to it — the command is
+         *  promoted to a task, never killed; it never goes below the floor;
+         *  0 keeps the model's value as asked (ADR-0058 Amendment 15). */
+        readonly maxForegroundMs?: number;
     };
 }
 export declare function readFileTool(opts: WorkspaceToolsOptions): Tool<{
@@ -187,16 +199,23 @@ export declare function writeFileTool(opts: WorkspaceToolsOptions): Tool<{
     content: string;
     expectedRevision?: string;
 }>;
-export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<{
+/** One hunk as a caller may send it: the current vocabulary, or the
+ *  legacy `search`/`replace` a durable log or a host may still hold. */
+type EditHunkInput = {
+    readonly oldText?: string;
+    readonly newText?: string;
+    readonly search?: string;
+    readonly replace?: string;
+    readonly expectedRevision?: string;
+};
+type EditFileInput = {
     path: string;
+    edits?: readonly EditHunkInput[];
     search?: string;
     replace?: string;
-    edits?: readonly {
-        search: string;
-        replace: string;
-    }[];
     expectedRevision?: string;
-}>;
+};
+export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<EditFileInput>;
 export { SHELL_STRIP_EXACT, strippedShellEnv } from "./secret-env.js";
 export { PROTECTED_REFUSAL, diskPath, isProtectedPath, protectedIdentity, protectedRefusalText, readUnlessProtected, type ProtectedIdentity } from "./protected.js";
 /** The search corpus's credential rule, by name — exported so the CLI's

package/dist/index.js

@@ -82,6 +82,9 @@ const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
 /** ADR-0058 §3: with tasks, how long the shell waits before a command
  *  continues as a task (the model's own value wins). */
 const DEFAULT_FOREGROUND_MS = 60_000;
+/** ADR-0058 Amendment 15: with tasks, the longest foreground wait. A longer
+ *  `foregroundMs` still promotes here; the command is never killed. */
+const DEFAULT_MAX_FOREGROUND_MS = 300_000;
 /** A promoted task's output file rotates here, as a runner's does. */
 const TASK_OUTPUT_CAP = 64 * 1024 * 1024;
 /** A task's stop: SIGTERM, this long, then the confirmed sweep. */
@@ -164,7 +167,8 @@ function isWithin(root, target) {
 }
 /**
  * Resolve an input path strictly inside the workspace (Area 5):
- * - absolute inputs are refused (paths are workspace-relative);
+ * - an absolute input is taken as the workspace-relative path it names when
+ *   it lies inside the root, and refused otherwise;
  * - `..` components cannot escape because the joined path is re-checked
  *   against the canonical root;
  * - SYMLINKS cannot escape: the deepest existing ancestor is realpath'd
@@ -198,10 +202,18 @@ function resolveReadable(opts, input, sessionId) {
     return { full: resolveWithinRoot(opts.workspaceRoot, input), root: opts.workspaceRoot };
 }
 export function resolveWithinRoot(root, input) {
+    const rootReal = realpathSync(root);
     if (isAbsolute(input)) {
-        throw new PathEscapeError(`absolute paths are not allowed — use workspace-relative paths: ${input}`);
+        // an absolute path that names a place inside the workspace — as the
+        // root is written or as it resolves — is that workspace-relative
+        // path, and takes the same canonical checks below (symlinks, `..`)
+        for (const base of [root, rootReal]) {
+            const rel = relative(base, input);
+            if (!rel.startsWith("..") && !isAbsolute(rel))
+                return resolveWithinRoot(root, rel === "" ? "." : rel);
+        }
+        throw new PathEscapeError(`absolute path outside the workspace: ${input} — the workspace root is ${rootReal}; use a path inside it`);
     }
-    const rootReal = realpathSync(root);
     const candidate = resolve(root, input);
     // Walk up to the deepest EXISTING ancestor (files to be created have a
     // not-yet-existing tail), then canonicalize it.
@@ -369,7 +381,7 @@ export function readFileTool(opts) {
             properties: {
                 path: { type: "string", description: "Workspace-relative path of the file to read" },
                 offset: { type: "number", description: "1-based first line to read (default: 1)" },
-                limit: { type: "number", description: "Maximum number of lines to read (default: to the end of the file)" },
+                limit: { type: "number", description: "Maximum lines; omit for the default bounded window" },
             },
             required: ["path"],
             additionalProperties: false,
@@ -382,7 +394,7 @@ export function readFileTool(opts) {
         // safety claim: the kernel enforces both, and had this line been
         // omitted the tool would simply have been slower, never less correct.
         effects: { precommitSafe: true, concurrency: "shared" },
-        promptSnippet: "read_file — whole files or offset/limit ranges, workspace-relative paths",
+        promptSnippet: "read_file — read a file or a line range",
         promptGuidelines: ["read only the range you need — offset/limit beat whole-file reads"],
         execute: async ({ path, offset, limit }, ctx) => {
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
@@ -544,7 +556,7 @@ export function listDirTool(opts) {
         idempotent: true,
         // EC-1 ②: read-only, free, local — see read_file above.
         effects: { precommitSafe: true, concurrency: "shared" },
-        promptSnippet: "list_dir — directory entries (the workspace ls)",
+        promptSnippet: "list_dir — list a directory",
         promptGuidelines: ["narrow to a subdirectory when the listing caps at 200 entries"],
         execute: async ({ path, glob }, ctx) => {
             try {
@@ -761,7 +773,7 @@ export function searchTextTool(opts) {
         // commit-required and exclusive, which is what closes the same-path
         // write race without asking their authors to remember anything.
         effects: { precommitSafe: true, concurrency: "shared" },
-        promptSnippet: "search_text — regex search over workspace files",
+        promptSnippet: "search_text — regex search in files",
         promptGuidelines: ["narrow the pattern when the result caps — never re-run a broad search"],
         execute: async ({ pattern, path, caseSensitive }, ctx) => {
             let root;
@@ -854,27 +866,29 @@ export function searchTextTool(opts) {
 export function writeFileTool(opts) {
     return defineTool({
         name: "write_file",
-        description: "Create or replace a whole workspace file. expectedRevision is the file's latest revision token, or \"absent\" to create a new file.",
+        description: opts.observedRevision !== undefined
+            ? "Create or replace a whole workspace file. Replacing a file needs an earlier read of it."
+            : "Create or replace a whole workspace file. expectedRevision is the file's latest revision token, or \"absent\" to create a new file.",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Workspace-relative file to write" },
                 content: { type: "string", description: "Full new content" },
-                expectedRevision: {
-                    type: "string",
-                    description: 'The latest revision token, or "absent" to create',
-                },
+                ...(opts.observedRevision !== undefined ? {} : { expectedRevision: {
+                        type: "string",
+                        description: 'The latest revision token, or "absent" to create',
+                    } }),
             },
-            required: ["path", "content", "expectedRevision"],
+            required: opts.observedRevision !== undefined ? ["path", "content"] : ["path", "content", "expectedRevision"],
             additionalProperties: false,
         },
-        promptSnippet: "write_file — create or replace a whole file",
-        promptGuidelines: ["write/edit: cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
-        execute: async ({ path, content, expectedRevision: citedRevision }) => {
+        promptSnippet: "write_file — write a whole file",
+        ...(opts.observedRevision !== undefined ? {} : { promptGuidelines: ["cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"] }),
+        execute: async ({ path, content, expectedRevision: citedRevision }, ctx) => {
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             // WR-1-F2: normalize every plausible copy of the token FIRST —
             // tolerance in the reader, strictness in the comparison.
-            const expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
+            let expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
             let full;
             try {
                 full = resolveWithinRoot(opts.workspaceRoot, path);
@@ -887,6 +901,14 @@ export function writeFileTool(opts) {
             const guard = protectedIdentity(opts.protectedFiles);
             if (isProtectedPath(full, guard))
                 return precondition(protectedRefusalText("write_file", path));
+            // O1: bind the observed revision (never the disk's latest)
+            if (expectedRevision === undefined && opts.observedRevision !== undefined && existsSync(full)) {
+                expectedRevision = opts.observedRevision(ctx?.sessionId, full, "write");
+                // the trajectory audit: after ranged reads the model retried this
+                // in a loop — say that only a WHOLE read lets it replace the file
+                if (expectedRevision === undefined)
+                    return precondition(`write_file: ${path} already exists — to replace it, first read the whole file (read_file with no offset or limit; a ranged read is not enough), or change part of it with edit_file`);
+            }
             // WR-1 — the observed-revision stale-write guard. The decision
             // lattice runs BEFORE any bytes move; every refusal is a
             // precondition with one actionable sentence. What it proves:
@@ -928,7 +950,7 @@ export function writeFileTool(opts) {
                     return precondition(protectedRefusalText("write_file", path));
                 const current = contentRevision(held);
                 if (current !== expectedRevision) {
-                    return precondition(`write_file: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
+                    return precondition(opts.observedRevision !== undefined ? `write_file: ${path} changed since you last observed it — read it again, then re-apply the change` : `write_file: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
                 }
             }
             const tmp = `${full}.kiso-tmp-${process.pid}-${crypto.randomUUID()}`;
@@ -977,7 +999,14 @@ export function writeFileTool(opts) {
                 // WR-1: the result returns the NEW revision — the model just
                 // authored these bytes; a legal new world witness for chained
                 // edits without a wasted re-read.
-                return { content: `wrote ${path} (${content.length} chars)\n[${contentRevision(Buffer.from(content, "utf8"))}]`, isError: false };
+                // O1: with no "absent" in the input, the "created" tag tells
+                // the host's card a creation from a rewrite — a product tag,
+                // never sent to the model.
+                return {
+                    content: `wrote ${path} (${content.length} chars)\n[${contentRevision(Buffer.from(content, "utf8"))}]`,
+                    isError: false,
+                    ...(opts.observedRevision !== undefined && !exists ? { tags: ["created"] } : {}),
+                };
             }
             catch (err) {
                 // round 8: a failed write never leaves a temp file with the FULL
@@ -1086,58 +1115,87 @@ function staleReport(text, hunks, single) {
     }
     return out.join("\n");
 }
+/**
+ * ADR-0061 — compatibility belongs in the executor; vocabulary belongs in
+ * the schema. The model is shown one form (`edits` of `{oldText, newText}`):
+ * `search`/`replace` was written SWAPPED in 80 of 86 failed T6 edits (the
+ * 2026-10-08 replay), and old/new cannot be read backwards. Everything a
+ * caller that skips schema validation may send — an approved call persisted
+ * before the upgrade, a host, a test — is still taken here: legacy hunks,
+ * the legacy top-level pair, a hunk-level `expectedRevision` (ignored, the
+ * call's own governs). A hunk that MIXES the two vocabularies takes neither
+ * half. The schema stays in the small portable subset by choice (no
+ * `oneOf`), so the shape rules live here.
+ */
+function editHunksOf(input) {
+    const pair = input.search !== undefined || input.replace !== undefined;
+    if (pair && input.edits !== undefined)
+        return "edit_file: pass edits — never edits and a top-level search/replace together";
+    if (pair) {
+        if (input.search === undefined || input.replace === undefined)
+            return "edit_file: the legacy top-level form needs BOTH search and replace";
+        return { hunks: [{ search: input.search, replace: input.replace }], single: true };
+    }
+    if (input.edits === undefined)
+        return "edit_file: pass edits \u2014 1\u201332 {oldText, newText} replacements";
+    if (input.edits.length === 0 || input.edits.length > 32)
+        return `edit_file: edits must carry 1\u201332 replacements (got ${input.edits.length})`;
+    const hunks = [];
+    for (let i = 0; i < input.edits.length; i += 1) {
+        const h = input.edits[i];
+        const current = h.oldText !== undefined || h.newText !== undefined;
+        const legacy = h.search !== undefined || h.replace !== undefined;
+        if (current && legacy)
+            return `edit_file: hunk ${i + 1} mixes oldText/newText with search/replace \u2014 send oldText and newText`;
+        const oldText = current ? h.oldText : h.search;
+        const newText = current ? h.newText : h.replace;
+        if (typeof oldText !== "string" || typeof newText !== "string")
+            return `edit_file: hunk ${i + 1} needs both oldText and newText`;
+        hunks.push({ search: oldText, replace: newText });
+    }
+    return { hunks, single: false };
+}
 export function editFileTool(opts) {
     return defineTool({
         name: "edit_file",
-        description: "Edit a file at its latest revision (expectedRevision): search+replace (must match once) OR edits (1-32 hunks, applied in order, all or nothing). A refusal shows the current text and ends on its [rev:X].",
+        description: opts.observedRevision !== undefined
+            ? "Edit a file you have read: exact replacements, applied in order, all or nothing. Batch changes to this file that are already known into one call."
+            : "Edit a file at its latest revision (expectedRevision): exact replacements, applied in order, all or nothing. Batch changes to this file that are already known into one call. A refusal ends on its [rev:X].",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Workspace-relative file" },
-                search: { type: "string", description: "Exact literal text to find (single-hunk form)" },
-                replace: { type: "string", description: "Replacement text (single-hunk form)" },
                 edits: {
                     type: "array",
-                    description: "Batch form: 1-32 {search, replace} hunks, applied in order",
+                    description: "1-32 replacements",
                     items: {
                         type: "object",
-                        // ACI-3: `expectedRevision` inside a hunk is tolerated and ignored —
-                        // the call's own governs (5 refusals on the owner's disk, every
-                        // one with the top-level token present too).
-                        properties: { search: { type: "string" }, replace: { type: "string" }, expectedRevision: { type: "string" } },
-                        required: ["search", "replace"],
+                        properties: {
+                            oldText: { type: "string", description: "Exact text to replace at this step; must match exactly once after the earlier edits in this call" },
+                            newText: { type: "string", description: "Replacement text for oldText" },
+                        },
+                        required: ["oldText", "newText"],
                         additionalProperties: false,
                     },
                     minItems: 1,
                     maxItems: 32,
                 },
-                expectedRevision: { type: "string", description: "The file's latest revision token" },
+                ...(opts.observedRevision !== undefined ? {} : { expectedRevision: { type: "string", description: "The file's latest revision token" } }),
             },
-            required: ["path", "expectedRevision"],
+            required: opts.observedRevision !== undefined ? ["path", "edits"] : ["path", "edits", "expectedRevision"],
             additionalProperties: false,
         },
-        promptSnippet: "edit_file — replace an exact old_string block (never rewrite whole files)",
-        promptGuidelines: ["write/edit: cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"],
-        execute: async ({ path, search, replace, edits, expectedRevision: citedRevision }) => {
+        promptSnippet: "edit_file — replace oldText with newText",
+        ...(opts.observedRevision !== undefined ? {} : { promptGuidelines: ["cite the file's latest revision as expectedRevision; each successful mutation returns the next one; use \"absent\" only to create"] }),
+        execute: async (input, ctx) => {
+            const { path, expectedRevision: citedRevision } = input;
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             // WR-1-F2: normalize the citation (see write_file).
-            const expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
-            // WR-1E2 — the form XOR (the draft-07 subset has no oneOf; the
-            // SHAPE rule is enforced here): legacy single-hunk XOR batch.
-            const single = search !== undefined || replace !== undefined;
-            if (single && edits !== undefined) {
-                return { content: "edit_file: pass EITHER search+replace OR edits — never both", isError: true, errorKind: "invalid_input" };
-            }
-            if (!single && edits === undefined) {
-                return { content: "edit_file: pass search+replace, or edits (1\u201332 hunks)", isError: true, errorKind: "invalid_input" };
-            }
-            if (single && (search === undefined || replace === undefined)) {
-                return { content: "edit_file: the single-hunk form needs BOTH search and replace", isError: true, errorKind: "invalid_input" };
-            }
-            if (edits !== undefined && (edits.length === 0 || edits.length > 32)) {
-                return { content: `edit_file: edits must carry 1\u201332 hunks (got ${edits.length})`, isError: true, errorKind: "invalid_input" };
-            }
-            const hunks = edits ?? [{ search: search, replace: replace }];
+            let expectedRevision = citedRevision === undefined ? undefined : normalizeRevision(citedRevision);
+            const shape = editHunksOf(input);
+            if (typeof shape === "string")
+                return { content: shape, isError: true, errorKind: "invalid_input" };
+            const { hunks, single } = shape;
             let full;
             try {
                 full = resolveWithinRoot(opts.workspaceRoot, path);
@@ -1150,6 +1208,12 @@ export function editFileTool(opts) {
             const guard = protectedIdentity(opts.protectedFiles);
             if (isProtectedPath(full, guard))
                 return precondition(protectedRefusalText("edit_file", path));
+            // O1: bind the observed revision (never the disk's latest)
+            if (expectedRevision === undefined && opts.observedRevision !== undefined) {
+                expectedRevision = opts.observedRevision(ctx?.sessionId, full);
+                if (expectedRevision === undefined)
+                    return precondition(`edit_file: ${path} — read it first; there is no observation of it in this session`);
+            }
             // WR-1: edits always target an existing file — the revision is
             // not optional here, and the refusal teaches the protocol.
             if (expectedRevision === undefined) {
@@ -1191,16 +1255,20 @@ export function editFileTool(opts) {
                     // ACI-3: the refusal carries the file as it is where each hunk
                     // should land, and its current revision last — the retry needs
                     // no read. The headline is unchanged (bench parsers read it).
-                    return precondition(`edit_file: ${path} changed since ${expectedRevision} — the file as it is now is below; re-apply the change against it, citing the [rev:…] on the last line\n${staleReport(text, hunks, edits === undefined)}\n[${current}]`);
+                    return precondition(opts.observedRevision !== undefined
+                        ? `edit_file: ${path} changed since you last observed it — the file as it is now is below; re-apply the change against it\n${staleReport(text, hunks, single)}\n[${current}]`
+                        : `edit_file: ${path} changed since ${expectedRevision} — the file as it is now is below; re-apply the change against it, citing the [rev:…] on the last line\n${staleReport(text, hunks, single)}\n[${current}]`);
                 }
                 // ACI-3 (superseding WR-1E2's one-snapshot rule): the hunks apply
                 // IN ORDER, each against the result of the ones before it — the
-                // way a person writes a second change after the first, and the
-                // reference implementation's multi-edit. 57 refusals on the
+                // way a person writes a second change after the first. (The
+                // reference implementation does NOT do this: it matches every edit
+                // against the original and refuses overlaps.) 57 refusals on the
                 // owner's disk were "two hunks overlap": a second hunk written
-                // against the first one's output. Still all or nothing: nothing is
-                // written unless every hunk resolves, and each must match exactly
-                // once in the text it meets (ACI-2).
+                // against the first one's output. The 2026-10-08 replay found 0 of
+                // 86 failures caused by this rule (ADR-0061). Still all or nothing:
+                // nothing is written unless every hunk resolves, and each must
+                // match exactly once in the text it meets (ACI-2).
                 // Windows P3: a uniformly CRLF file is matched on its LF form and
                 // written back CRLF — the model's search text uses LF, and an edit
                 // never changes the file's endings. A file mixing the two keeps
@@ -1211,7 +1279,12 @@ export function editFileTool(opts) {
                 for (let i = 0; i < hunks.length; i += 1) {
                     const h = { search: lf(hunks[i].search), replace: lf(hunks[i].replace) };
                     const { count, offsets } = occurrencesOf(edited, h.search);
-                    const which = hunks.length === 1 && edits === undefined ? "" : i === 0 ? " (hunk 1)" : ` (hunk ${i + 1}, after ${i === 1 ? "hunk 1" : `hunks 1–${i}`} applied)`;
+                    // a batch's later hunk is matched against the text the earlier
+                    // ones made IN MEMORY; "after hunk 1 applied" read as written,
+                    // and the model repaired a hunk that never landed (the TB20
+                    // trajectory audit) — so a batch refusal says nothing changed
+                    const which = single ? "" : i === 0 ? " (hunk 1)" : ` (hunk ${i + 1}, matched after ${i === 1 ? "hunk 1" : `hunks 1–${i}`})`;
+                    const untouched = hunks.length > 1 ? ` — nothing was written, ${path} is unchanged` : "";
                     if (count === 0) {
                         // WR-1A ④: the WORLD lacks the pattern (the input is
                         // fine) and nothing ran — precondition; the note never
@@ -1222,7 +1295,13 @@ export function editFileTool(opts) {
                         const region = regionForSearch(edited, h.search);
                         const seen = i === 0 ? "the file now has" : `the text hunk ${i + 1} met`;
                         const block = region === null ? "" : `\n${seen}, lines ${region.from}–${region.to}:\n${region.body}`;
-                        return precondition(`edit_file: pattern not found in ${path}${which}${detail ? `\n${detail}` : ""}${block}\n[${current}]`);
+                        // ADR-0061: the replay's shape — oldText nowhere, newText exactly
+                        // once. Two readings fit it and the tool cannot tell them apart, so
+                        // it names both and applies nothing (ACI-2: never a guess).
+                        const swap = h.replace.length > 0 && occurrencesOf(edited, h.replace).count === 1
+                            ? "\n  newText is already in the file once and oldText is not: either this change is already applied, or oldText and newText are swapped"
+                            : "";
+                        return precondition(`edit_file: pattern not found in ${path}${which}${untouched}${detail ? `\n${detail}` : ""}${swap}${block}\n[${current}]`);
                     }
                     // ACI-2: more than one resolution is a QUESTION, not an edit.
                     // Taking the first one wrote the wrong place and reported
@@ -1232,7 +1311,7 @@ export function editFileTool(opts) {
                     if (count > 1) {
                         const lines = describeMatchLines(edited, offsets, count <= ACI2_OFFSETS_KEPT);
                         const where = which === "" ? lines : `${which.slice(2, -1)}, ${lines}`;
-                        return precondition(`edit_file: pattern matches ${count} places in ${path} (${where}) — include enough surrounding text to make it unique\n[${current}]`);
+                        return precondition(`edit_file: pattern matches ${count} places in ${path} (${where}) — include enough surrounding text to make it unique${untouched !== "" ? `; nothing was written, ${path} is unchanged` : ""}\n[${current}]`);
                     }
                     edited = edited.slice(0, offsets[0]) + h.replace + edited.slice(offsets[0] + h.search.length);
                 }
@@ -1348,7 +1427,10 @@ export function shellTool(opts) {
                         description: "Run independently as a task. Use for services/watchers or work whose exit result is not needed next. If you need the result, keep it foreground and raise foregroundMs. You are notified when it ends; do not sleep/poll.",
                     },
                     readyWhen: { type: "string", description: "For a continuing service, wait up to foregroundMs for this literal output before returning; the task keeps running afterward." },
-                    timeoutMs: { type: "number", description: "Deprecated: use foregroundMs" },
+                    // Plan B: timeoutMs (deprecated here since ADR-0058) leaves the
+                    // model-facing schema; the executor still reads it from a caller
+                    // that skips validation. The schema WITHOUT tasks keeps it — there
+                    // it is the shell's only timeout.
                 },
                 required: ["command"],
                 additionalProperties: false,
@@ -1362,6 +1444,7 @@ export function shellTool(opts) {
                 required: ["command"],
                 additionalProperties: false,
             },
+        // PR-1d row 3: this exact snippet is part of a MEASURED combination (weather 1/5 -> 5/5); Plan B leaves it as pinned
         promptSnippet: "shell — any command the task needs (builds, tests, git, curl, system queries)",
         promptGuidelines: ["commands run in the workspace root; on failure read the error and adjust — never repeat blindly"],
         execute: async ({ command, timeoutMs, foregroundMs, background, readyWhen }, ctx) => {
@@ -1370,11 +1453,14 @@ export function shellTool(opts) {
             // ADR-0058 Amendment 10: with tasks wired a wait shorter than the
             // floor only moves the command to the background sooner, so the
             // model may lengthen the wait, never shorten it. Without tasks the
-            // wait is a kill timeout and is kept as asked.
+            // wait is a kill timeout and is kept as asked. Amendment 15: a
+            // wait past the ceiling only holds the turn — the command is
+            // promoted there and the model is notified when it ends.
             const asked = [foregroundMs, timeoutMs].find((v) => typeof v === "number" && Number.isFinite(v));
-            const timeout = tasks !== undefined
-                ? Math.max(asked ?? DEFAULT_FOREGROUND_MS, opts.limits?.minForegroundMs ?? DEFAULT_FOREGROUND_MS)
-                : (asked ?? DEFAULT_SHELL_TIMEOUT_MS);
+            const floor = opts.limits?.minForegroundMs ?? DEFAULT_FOREGROUND_MS;
+            const ceiling = opts.limits?.maxForegroundMs ?? DEFAULT_MAX_FOREGROUND_MS;
+            const raised = Math.max(asked ?? DEFAULT_FOREGROUND_MS, floor);
+            const timeout = tasks !== undefined ? (ceiling > 0 ? Math.min(raised, Math.max(ceiling, floor)) : raised) : (asked ?? DEFAULT_SHELL_TIMEOUT_MS);
             // E group: a PRE-aborted signal never spawns the command.
             if (ctx.signal.aborted) {
                 return { content: "shell aborted before start", isError: true, errorKind: "fatal" };
@@ -1687,7 +1773,7 @@ export function taskStopTool(opts) {
             required: ["id"],
             additionalProperties: false,
         },
-        promptSnippet: "task_stop — stop a background task by id",
+        promptSnippet: "task_stop — stop a background task",
         execute: async ({ id }, ctx) => {
             const tasks = opts.tasks?.(ctx.sessionId);
             const info = tasks?.get(id);

package/dist/search-miss.js

@@ -83,13 +83,13 @@ export function describeSearchMiss(text, search) {
     if (endOfMatch >= text.length) {
         return [
             head,
-            `  the file ENDS there — your search continues for ${rest.length} more characters: "${fragment(rest)}"`,
+            `  the file ENDS there — your oldText continues for ${rest.length} more characters: "${fragment(rest)}"`,
         ].join("\n");
     }
     return [
         head,
         `  the file then has:  "${fragment(text.slice(endOfMatch))}"`,
-        `  your search wanted: "${fragment(rest)}"`,
+        `  your oldText wanted: "${fragment(rest)}"`,
     ].join("\n");
 }
 export function regionForSearch(text, search, context = 6, maxChars = 1500) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.48.0",
+	"version": "0.50.0",
 	"description": "kiso coding tools for Node hosts \u2014 read file, list directory, search text, write/edit file, shell command.",
 	"type": "module",
 	"license": "MIT",
@@ -25,7 +25,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.48.0",
+		"@vincemakes/kiso-core": "0.50.0",
 		"ignore": "^7.0.9"
 	},
 	"devDependencies": {