@sema-agent/core 7.16.0 → 7.17.1

package/dist/tools/fs/fs-bash.js

@@ -11,7 +11,7 @@ import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
-import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, refusedCommandMayRead, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
 const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
@@ -36,7 +36,7 @@ export function bashReversibilityProbe(allow, boundary) {
         if (backgrounded)
             return { reversible: false, ...boundaryGate(detailed) };
         if (detailed.reason === undefined) {
-            if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
+            if (boundaryUnread(detailed)) {
                 const cause = recursiveReadCause(detailed);
                 if (cause !== undefined)
                     return { reversible: false, ...boundaryGate(detailed), cause };
@@ -44,23 +44,19 @@ export function bashReversibilityProbe(allow, boundary) {
             }
             return { reversible: true };
         }
-        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
-        if (loopRefusal === undefined)
+        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
+        if (loop.reason === undefined)
             return { reversible: true };
-        return { reversible: false, ...(pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal) === "declared" ? { mandated: true } : boundaryGate(detailed)) };
+        if (boundaryDeclared(loop) || unjudgedRead(command, allowSet, resolved, loop))
+            return { reversible: false, mandated: true };
+        return { reversible: false, ...boundaryGate(detailed) };
     };
 }
-function attributeRefusal(face, resolved, fullRefusal) {
-    if (resolved === undefined)
-        return "shape";
-    const { denyMatch: _deny, ...withoutDenyJudge } = resolved;
-    const opened = face({ ...withoutDenyJudge, face: "open" });
-    if (opened === undefined || opened !== fullRefusal)
-        return "declared";
-    return face(undefined) === opened ? "shape" : "unread";
+function boundaryUnread(verdict) {
+    return boundaryUndecided(verdict) || boundaryUnjudged(verdict);
 }
-function pollLoopBoundaryVerdict(command, allowSet, resolved, fullRefusal) {
-    return attributeRefusal((b) => classifyBoundedReadonlyPollLoop(command, allowSet, b), resolved, fullRefusal);
+function boundaryUndecided(verdict) {
+    return verdict.undecidedPaths !== undefined && verdict.undecidedPaths.length > 0;
 }
 function boundaryDeclared(verdict) {
     return denyJudgeSpoke(verdict) || verdict.outOfRootRead === true;
@@ -76,9 +72,23 @@ function isBackgroundShellCall(args) {
     return args?.run_in_background === true;
 }
 function readBoundaryMandate(command, allowSet, resolved, verdict) {
-    if (denyJudgeSpoke(verdict))
+    if (resolved === undefined)
+        return {};
+    if (denyJudgeSpoke(verdict) || unjudgedRead(command, allowSet, resolved, verdict))
         return { mandated: true };
-    return resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
+    return classifyOutOfRootReadGate(command, allowSet, resolved).gated ? { mandated: true } : {};
+}
+function boundaryUnjudged(verdict) {
+    return verdict.refusedWhole === true || (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0);
+}
+function unjudgedRead(command, allowSet, resolved, verdict) {
+    if (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0)
+        return true;
+    if (verdict.refusedWhole !== true)
+        return false;
+    if (refusedCommandMayRead(command, allowSet))
+        return true;
+    return resolved !== undefined && classifyOutOfRootReadGate(command, allowSet, resolved).gated;
 }
 function recursiveReadCause(detailed) {
     const recursive = detailed.recursiveReadPaths;
@@ -101,24 +111,31 @@ export function bashReadBoundaryProbe(boundary) {
         const resolved = typeof boundary === "function" ? boundary() : boundary;
         if (resolved === undefined)
             return { reversible: true };
+        const seatVerdict = (verdict) => {
+            if (boundaryDeclared(verdict) || unjudgedRead(command, allowSet, resolved, verdict)) {
+                const cause = recursiveReadCause(verdict);
+                return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
+            }
+            if (boundaryUndecided(verdict))
+                return { reversible: false };
+            if (verdict.reason === undefined)
+                return { reversible: true };
+            return undefined;
+        };
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
-        if (boundaryDeclared(detailed)) {
-            const cause = recursiveReadCause(detailed);
-            return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
-        }
-        if (detailed.reason === undefined) {
-            return detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0 ? { reversible: false } : { reversible: true };
-        }
-        const compound = attributeRefusal((b) => classifyCompoundReadonlyDetailed(command, allowSet, b).reason, resolved, detailed.reason);
-        if (compound === "declared")
+        if (detailed.reason === undefined)
+            return seatVerdict(detailed) ?? { reversible: true };
+        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
+        if (loop.reason === undefined)
+            return seatVerdict(loop) ?? { reversible: true };
+        const compoundVerdict = seatVerdict(detailed);
+        const loopVerdict = seatVerdict(loop);
+        const mandated = [compoundVerdict, loopVerdict].find((verdict) => verdict?.mandated === true);
+        if (mandated !== undefined)
+            return mandated;
+        if (readBoundaryMandate(command, allowSet, resolved, detailed).mandated === true)
             return { reversible: false, mandated: true };
-        if (compound === "unread")
-            return { reversible: false };
-        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
-        if (loopRefusal === undefined)
-            return { reversible: true };
-        const loop = pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal);
-        return loop === "shape" ? { reversible: true } : loop === "declared" ? { reversible: false, mandated: true } : { reversible: false };
+        return compoundVerdict ?? loopVerdict ?? { reversible: true };
     };
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";

package/dist/tools/fs/fs-search-tools.js

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { resolveKey, violationText, violationDetails } from "./safety.js";
+import { clipSpelling, pathFamilyOf, resolveKey, violationText, violationDetails, WIN32_NAMESPACE_REFUSAL_TEXT } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, invalidGlobTokens } from "./search.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { pathTargetBaseOf, splitAbsoluteGlobPattern } from "../../core/effective-path-target.js";
@@ -205,7 +205,10 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
             let path = declaredTarget === undefined ? undefined : pathTargetValue(args, declaredTarget);
             const { max_results } = args;
             if (path === undefined) {
-                const split = splitAbsoluteGlobPattern(pattern);
+                const split = splitAbsoluteGlobPattern(pattern, pathFamilyOf({ root: rootCanonical }));
+                if (split !== undefined && "refused" in split) {
+                    return errorResult(`Error (Glob): pattern "${clipSpelling(pattern)}" ${WIN32_NAMESPACE_REFUSAL_TEXT[split.refused]}; refused (${split.refused}).`);
+                }
                 if (split) {
                     path = split.baseDir;
                     pattern = split.relativePattern;

package/dist/tools/fs/fs-shared.d.ts

@@ -273,6 +273,8 @@ export declare function bashTimeoutCapsSec(caps: {
     defaultSec: number;
     maxSec: number;
 };
+/** Read per call (a deployment steers it without a restart); the one shared resolver holds the grammar,
+ *  the `[OUTPUT_BUDGET_MIN_CHARS, ceiling]` range and the loud outlet for a value it could not honor. */
 export declare function bashMaxOutputChars(): number;
 export declare const FILE_PATH_PARAMS: {
     file_path: Type.TString;

package/dist/tools/fs/fs-shared.js

@@ -1,12 +1,12 @@
 import { Type } from "typebox";
-import { clipWithFilePointer } from "../../core/tool-errors.js";
+import { clipWithFilePointer, OUTPUT_BUDGET_MIN_CHARS } from "../../core/tool-errors.js";
 import { normalizeAbsPathLexically, sha256, similarNameSuggestion, OVERSIZE_READ_ESCAPE_HINT, PARTIAL_VIEW_READ_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, normalizeFileText } from "./encoding.js";
 import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
 import { sharpImageDownsampler } from "../../core/mcp.js";
 import { deliverEngineNotice } from "../../core/types.js";
-import { announceEnvKnob } from "../../core/env-knob-announce.js";
+import { resolveEnvBudget } from "../../core/env-budget.js";
 import { openSystemReminder } from "../../core/reminder-mint.js";
 export const MAX_READ_BYTES = 256 * 1024;
 export const SLICED_READ_MAX_BYTES = 64 * 1024 * 1024;
@@ -182,15 +182,7 @@ export function bashTimeoutCapsSec(caps) {
 const BASH_DEFAULT_MAX_OUTPUT_CHARS = 30_000;
 const BASH_MAX_OUTPUT_CHARS_CEILING = 150_000;
 export function bashMaxOutputChars() {
-    const rawEnv = process.env.BASH_MAX_OUTPUT_LENGTH;
-    if (rawEnv === undefined || rawEnv.trim() === "")
-        return BASH_DEFAULT_MAX_OUTPUT_CHARS;
-    const raw = Number(rawEnv);
-    if (!Number.isInteger(raw) || raw <= 0) {
-        announceEnvKnob(`BASH_MAX_OUTPUT_LENGTH=${rawEnv} was ignored — it is not a positive whole number of characters. Using ${BASH_DEFAULT_MAX_OUTPUT_CHARS} instead.`);
-        return BASH_DEFAULT_MAX_OUTPUT_CHARS;
-    }
-    return Math.min(raw, BASH_MAX_OUTPUT_CHARS_CEILING);
+    return resolveEnvBudget(process.env.BASH_MAX_OUTPUT_LENGTH, { name: "BASH_MAX_OUTPUT_LENGTH", unit: "characters", default: BASH_DEFAULT_MAX_OUTPUT_CHARS, min: OUTPUT_BUDGET_MIN_CHARS, max: BASH_MAX_OUTPUT_CHARS_CEILING });
 }
 export const FILE_PATH_PARAMS = {
     file_path: Type.String({ description: "File path (within the configured root)." }),

package/dist/tools/fs/index.d.ts

@@ -179,6 +179,10 @@ export interface HandsToolkitOptions {
      *  is off anyway when `reminderMark` is absent). */
     reminderDisclosureCounts?: import("../../core/reminder-disclosure.js").ReminderDisclosureCounts;
 }
+/** Whether the band's WRITE half (Edit / Write / NotebookEdit, and the full `bash`) mounts for these options — the ONE
+ *  predicate {@link createHandsToolkit} branches on and prepare-task plans by (the memory phase must know, before the
+ *  band exists, whether the instruction-taught write channel will be there). `readOnly` is the verifier boundary. */
+export declare function handsWriteHalfMounts(opts: Pick<HandsToolkitOptions, "readOnly">): boolean;
 /**
  * Build the per-task hand tool band over an injected env + fresh per-task read state.
  * `rootCanonical` is the already-canonicalized containment root (prepare-task resolves it once). Normal

package/dist/tools/fs/index.js

@@ -21,6 +21,9 @@ import { createReadFileTool } from "./fs-read.js";
 import { createEditFileTool, createWriteFileTool, createNotebookEditTool } from "./fs-write.js";
 import { createGrepTool, createGlobTool } from "./fs-search-tools.js";
 import { createBashTool, createBashReadonlyTool, createEnvTaskOutputTool, createEnvTaskStopTool } from "./fs-bash.js";
+export function handsWriteHalfMounts(opts) {
+    return opts.readOnly !== true;
+}
 export function createHandsToolkit(env, readFileState, rootCanonical, opts = {}) {
     const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = false, mountBackgroundTaskTools = true, additionalRoots, additionalReadRoots, } = opts;
     const readFaceRoots = additionalReadRoots === undefined || additionalReadRoots.length === 0
@@ -49,7 +52,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
     const tools = [
         createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts),
     ];
-    if (!readOnly) {
+    if (handsWriteHalfMounts({ readOnly })) {
         tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited));
     }
     tools.push(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace));

package/dist/tools/fs/safety.d.ts

@@ -258,6 +258,120 @@ export declare function isBinaryContent(sample: string): boolean;
  * test with no verdict of its own.
  */
 export declare function isUncPath(path: string): boolean;
+/** The two spelling families a tree can be in. Read from the ROOT's spelling (the cwd's when a deployment
+ *  supplies no root) — never from `process.platform`: the exec env may be remote and of the other family. */
+export type PathFamily = "win" | "posix";
+/** The family of a call's tree; `undefined` when the call declares neither root nor cwd (a treeless call
+ *  gets no family invented for it — see {@link pathIdentityOf} for what it can still read). */
+export declare function pathFamilyOf(bases: {
+    readonly root: string;
+    readonly cwd?: string | undefined;
+}): PathFamily;
+export declare function pathFamilyOf(bases: {
+    readonly root?: string | undefined;
+    readonly cwd: string;
+}): PathFamily;
+export declare function pathFamilyOf(bases: {
+    readonly root?: string | undefined;
+    readonly cwd?: string | undefined;
+}): PathFamily | undefined;
+/**
+ * FULLY QUALIFIED under the family. win: drive-rooted (`C:\`/`C:/`) or UNC — a `/x` / `\x` is rooted-not-
+ * qualified and joins the base's drive or share root ({@link joinForFamily}), a `C:rel` is drive-relative.
+ * posix: `/`-rooted. `undefined` (a treeless call): only the anchor-free `/`-rooted form, the one spelling
+ * that names a file without a tree.
+ */
+export declare function isAbsoluteForFamily(family: PathFamily | undefined, p: string): boolean;
+/** The refusal words of {@link win32NamespaceScreen} — a closed set (docs/CLOSED-SETS.md). */
+export declare const WIN32_NAMESPACE_REFUSALS: readonly ["device_namespace", "unmappable_namespace", "unc_on_posix_tree", "drive_relative"];
+export type Win32NamespaceRefusal = (typeof WIN32_NAMESPACE_REFUSALS)[number];
+/** What each refusal word says about the spelling (the message clause after `path "…" `). */
+export declare const WIN32_NAMESPACE_REFUSAL_TEXT: {
+    readonly device_namespace: "is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file)";
+    readonly unmappable_namespace: "is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files)";
+    readonly unc_on_posix_tree: "is a UNC (\\\\host\\share) spelling, which names no file on a POSIX tree";
+    readonly drive_relative: "is drive-relative (a drive letter with no separator after the colon), a location no tree can locate";
+};
+/** The fence over the text table: `never` while every refusal word has a row. */
+export type NamespaceRefusalTextCoversEveryWord = AssertAllKeysHandled<Exclude<Win32NamespaceRefusal, keyof typeof WIN32_NAMESPACE_REFUSAL_TEXT>>;
+type AssertAllKeysHandled<T extends never> = T;
+/**
+ * The Win32 namespace screen — run on every model-spelled target BEFORE the family join, at every site
+ * (the fs throat, the effective-target reader, the rule side, the glob splitter), so one spelling is
+ * refused with one word everywhere. `\\.\` ⇒ `device_namespace` (every family); `\\?\` mappable ⇒ the
+ * stripped spelling, which is screened ON (a `\\?\UNC\…` on a POSIX tree still refuses), unmappable ⇒
+ * `unmappable_namespace` (every family); a backslash UNC ⇒ passes under `win`, `unc_on_posix_tree` under
+ * `posix` (the canonicalizer's refusal boundary on POSIX trees is preserved: the family rule governs what
+ * is admitted, never what was already refused); `C:rel` under `win` ⇒ `drive_relative`. A treeless call
+ * passes a UNC spelling through — the identity then reads it as relative, as before.
+ */
+export declare function win32NamespaceScreen(spelled: string, family: PathFamily | undefined): {
+    readonly ok: true;
+    readonly spelled: string;
+} | {
+    readonly ok: false;
+    readonly refuse: Win32NamespaceRefusal;
+};
+declare const PATH_IDENTITY: unique symbol;
+/**
+ * The ONE comparison form of an absolute path (upstream's normal form): posix = the lexical-normal
+ * `/`-rooted path; win = `/c/rest` for a drive (letter lower-cased), `//host/share/rest` for UNC, `\`
+ * folded to `/`, `.`/`..` folded with the anchor preserved. A COMPARISON form — never a path to open, never
+ * compared against a native `C:\…` string. Branded: a spelling is not an identity until {@link pathIdentityOf}
+ * has read it.
+ */
+export type PathIdentity = string & {
+    readonly [PATH_IDENTITY]: true;
+};
+/** Why a spelling has no identity: a namespace refusal, `relative` (join it to a base first), or
+ *  `unanchored` (a win `/x` with no tree root to take a drive from). */
+export type PathIdentityRefusal = Win32NamespaceRefusal | "relative" | "unanchored";
+export type PathIdentityReading = {
+    readonly ok: true;
+    readonly identity: PathIdentity;
+} | {
+    readonly ok: false;
+    readonly reason: PathIdentityRefusal;
+};
+/**
+ * The identity of an ABSOLUTE spelling under the family ({@link PathIdentity}). `anchor` is the tree's root
+ * (or cwd) spelling: under `win` a `/`-rooted spelling whose first segment is not a drive letter
+ * (`/proj/x`) anchors on the root's drive or share, as `path.win32.resolve` anchors it on the current
+ * drive; `/c/x` and `/C:/x` are drive spellings (the cygdrive form and the rule grammar's `/`+body), and
+ * `/\\host\share\x` is the grammar's prefix before a UNC. A relative spelling is `relative` — callers join
+ * it to a base FIRST. A treeless call (`family` undefined) reads only the anchor-free `/`-rooted form, as
+ * the POSIX identity; every other spelling names nothing, which is what a missing base answered before.
+ */
+export declare function pathIdentityOf(spelled: string, family: PathFamily | undefined, anchor?: string): PathIdentityReading;
+/** Is the identity a UNC one (`//host/share/…`)? Identities compare by anchor kind first: a UNC identity is
+ *  never under a rooted one and vice versa (upstream's shape parity). */
+export declare function isUncIdentity(identity: PathIdentity): boolean;
+/** Is `s` already an identity under the family — the identity function is the identity on it? The
+ *  runtime twin of the brand for values that arrive from outside the type system. */
+export declare function isPathIdentity(s: string, family: PathFamily | undefined): s is PathIdentity;
+/** Is the identity a DIRECTORY a rule may speak for — anything but the tree's bare root (`/`, a drive root
+ *  `/c`, a share root `//host/share`), which admits nothing? */
+export declare function isIdentityDir(identity: PathIdentity, family: PathFamily | undefined): boolean;
+/** Does the spelling carry a `.` or `..` segment under the family's separators (a backslash is a name byte on
+ *  POSIX)? A rule body with one admits nothing: folding it could make it name a second directory. */
+export declare function carriesDotSegment(spelled: string, family: PathFamily | undefined): boolean;
+/** A model-spelled path bounded for error text (the spelling is unbounded input). */
+export declare function clipSpelling(spelled: string): string;
+/** A ROOTED (not qualified) spelling handed to the SHELL on a win tree (`/d/x`, `/etc`, `\\x`) is the shell's to
+ *  map — the win32 adapter runs Git Bash, where `/d/x` is drive D and `/etc` the MSYS root, neither the cwd's
+ *  drive root — so no lexical reader may resolve it (fail-closed: the operand is unresolvable, the cd mints
+ *  nothing). The ONE statement of that rule, for every shell-facing resolver. */
+export declare function isShellRootedSpellingUnmapped(family: PathFamily | undefined, spelled: string): boolean;
+/** The win family's native spelling of a UNC written with any leading-separator mix (`//host/share/x`, `\\/host/…`
+ *  ⇒ `\\\\host\\share\\x`), for a lexical normalizer that recognises the backslash form only; every other spelling is
+ *  returned as is. */
+export declare function nativeUncSpellingOf(family: PathFamily | undefined, spelled: string): string;
+/**
+ * Join a RELATIVE-OR-ROOTED spelling to a base under the family, without folding (`..` across a symlinked
+ * parent is the env's to resolve). win = `path.win32` semantics: `/x`/`\x` lands on the base's drive or
+ * share root, anything else under the base with the base's own separator. posix = `/`-join.
+ */
+export declare function joinForFamily(family: PathFamily, base: string, rel: string): string;
 /** The family-aware LEXICAL view of a possibly-relative spelling against a resolution base (no I/O,
  *  `.`/`..` folded via {@link normalizeAbsPathLexically}): the SECOND deny-judgment view. It asks
  *  "does the NAME land on a guarded path", complementing the canonical
@@ -294,7 +408,7 @@ export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, pat
  * A single source of truth for symlink resolution: a sensitive-path policy that matched the raw path
  * instead of the real target would compare against the spelling, not the destination.
  */
-export declare function canonicalizeTarget(env: ExecutionEnv, path: string, signal?: AbortSignal, baseCwd?: string): Promise<{
+export declare function canonicalizeTarget(env: ExecutionEnv, path: string, signal: AbortSignal | undefined, family: PathFamily, baseCwd?: string): Promise<{
     ok: true;
     key: string;
     aliasResolved?: true;
@@ -302,6 +416,7 @@ export declare function canonicalizeTarget(env: ExecutionEnv, path: string, sign
     ok: false;
     message: string;
     unresolvedSymlink?: true;
+    refused?: Win32NamespaceRefusal;
 }>;
 /** Render a `FsViolation` as the model-facing tool error text (returned, never thrown — model retries). */
 export declare function violationText(toolName: string, v: FsViolation): string;
@@ -495,3 +610,4 @@ export declare function deletionOldString(content: string, oldString: string, ne
  *  matters most (and these refusals return as tool results, which do not pass the loop-level budget). */
 export declare const EDIT_ECHO_MAX_CHARS = 200;
 export declare function checkEditMatch(content: string, oldString: string, replaceAll: boolean, truncated: boolean): FsViolation | undefined;
+export {};

package/dist/tools/fs/safety.js

@@ -23,15 +23,6 @@ const SEP = "/";
 export function isAbsolutePathForm(p) {
     return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\");
 }
-function normalizeForCompare(p) {
-    let n = stripWin32ExtendedPrefix(p);
-    if (isUncPath(n) && isWinFormPath(n) && !isWin32DeviceNamespacePath(n))
-        n = foldUncLexically(n).key;
-    n = isWinFormPath(n) ? n.replace(/\\/g, "/") : n;
-    if (/^[A-Za-z]:(\/|$)/.test(n))
-        n = n[0].toLowerCase() + n.slice(1);
-    return n;
-}
 function nativeSepOf(p) {
     return isWinFormPath(p) && p.includes("\\") ? "\\" : "/";
 }
@@ -323,26 +314,137 @@ function foldUncLexically(p) {
     const anchor = `\\\\${host}${share !== undefined ? `\\${share}` : ""}`;
     return { key: out.length > 0 ? `${anchor}\\${out.join("\\")}` : anchor, climbedAboveShare: climbed };
 }
+export function pathFamilyOf(bases) {
+    const tree = bases.root ?? bases.cwd;
+    return tree === undefined ? undefined : isWinFormPath(tree) ? "win" : "posix";
+}
+function isUncSpelling(p) {
+    return /^[\\/]{2}[^\\/]+[\\/]+[^\\/]/.test(p);
+}
+export function isAbsoluteForFamily(family, p) {
+    return family === "win" ? /^[A-Za-z]:[\\/]/.test(p) || isUncSpelling(p) : p.startsWith("/");
+}
+export const WIN32_NAMESPACE_REFUSALS = ["device_namespace", "unmappable_namespace", "unc_on_posix_tree", "drive_relative"];
+export const WIN32_NAMESPACE_REFUSAL_TEXT = {
+    device_namespace: "is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file)",
+    unmappable_namespace: "is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files)",
+    unc_on_posix_tree: "is a UNC (\\\\host\\share) spelling, which names no file on a POSIX tree",
+    drive_relative: "is drive-relative (a drive letter with no separator after the colon), a location no tree can locate",
+};
+export function win32NamespaceScreen(spelled, family) {
+    if (family === "win" && /^[\\/]{2}[?.][\\/]/.test(spelled) && !/^\\\\[?.]\\/.test(spelled))
+        spelled = spelled.replace(/\//g, "\\");
+    if (isWin32DeviceNamespacePath(spelled))
+        return { ok: false, refuse: "device_namespace" };
+    const mapped = stripWin32ExtendedPrefix(spelled);
+    if (mapped.startsWith("\\\\?\\"))
+        return { ok: false, refuse: "unmappable_namespace" };
+    if (mapped.startsWith("\\\\") && family === "posix")
+        return { ok: false, refuse: "unc_on_posix_tree" };
+    if (family === "win" && /^[A-Za-z]:(?![\\/])/.test(mapped))
+        return { ok: false, refuse: "drive_relative" };
+    return { ok: true, spelled: mapped };
+}
+export function pathIdentityOf(spelled, family, anchor) {
+    if (typeof spelled !== "string")
+        return { ok: false, reason: "relative" };
+    if (family !== "win") {
+        if (!spelled.startsWith("/"))
+            return { ok: false, reason: "relative" };
+        return { ok: true, identity: mintIdentity("", spelled.split("/"), false) };
+    }
+    const screened = win32NamespaceScreen(spelled, "win");
+    if (!screened.ok)
+        return { ok: false, reason: screened.refuse };
+    let s = screened.spelled;
+    if (s.startsWith("/") && isAbsoluteForFamily("win", s.slice(1)))
+        s = s.slice(1);
+    if (isUncSpelling(s)) {
+        const segs = s.slice(2).split(/[\\/]+/).filter((x) => x !== "");
+        const host = segs.shift();
+        const share = segs.shift();
+        return { ok: true, identity: mintIdentity(`//${host}/${share}`, segs, true) };
+    }
+    const drive = /^([A-Za-z]):[\\/]/.exec(s) ?? /^[\\/]([A-Za-z])(?=[\\/]|$)/.exec(s);
+    if (drive !== null)
+        return { ok: true, identity: mintIdentity(`/${drive[1].toLowerCase()}`, s.slice(2).split(/[\\/]/), false) };
+    if (s.startsWith("/") || s.startsWith("\\")) {
+        const root = anchor === undefined ? undefined : pathIdentityOf(anchor, "win");
+        if (root === undefined || !root.ok)
+            return { ok: false, reason: "unanchored" };
+        return { ok: true, identity: mintIdentity(identityAnchorOf(root.identity), s.slice(1).split(/[\\/]/), false) };
+    }
+    return { ok: false, reason: "relative" };
+}
+function mintIdentity(anchor, segments, stripTail) {
+    const out = [];
+    for (const seg of segments) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            if (out.length > 0)
+                out.pop();
+            continue;
+        }
+        const stripped = stripTail ? seg.replace(/[. ]+$/, "") : seg;
+        out.push(stripped.length > 0 ? stripped : seg);
+    }
+    return (out.length === 0 ? anchor || "/" : `${anchor}/${out.join("/")}`);
+}
+function identityAnchorOf(identity) {
+    return identity.startsWith("//") ? identity.split("/").slice(0, 4).join("/") : identity.slice(0, 2);
+}
+export function isUncIdentity(identity) {
+    return identity.startsWith("//");
+}
+export function isPathIdentity(s, family) {
+    const r = pathIdentityOf(s, family);
+    return r.ok && r.identity === s;
+}
+export function isIdentityDir(identity, family) {
+    if (family !== "win")
+        return identity !== "/";
+    return identity.length > identityAnchorOf(identity).length;
+}
+export function carriesDotSegment(spelled, family) {
+    return (family === "win" ? /(^|[\\/])\.{1,2}([\\/]|$)/ : /(^|\/)\.{1,2}(\/|$)/).test(spelled);
+}
+export function clipSpelling(spelled) {
+    return spelled.length > 512 ? `${spelled.slice(0, 512)}…` : spelled;
+}
+export function isShellRootedSpellingUnmapped(family, spelled) {
+    return family === "win" && (spelled.startsWith("/") || spelled.startsWith("\\"));
+}
+export function nativeUncSpellingOf(family, spelled) {
+    return family === "win" && isUncSpelling(spelled) ? `\\\\${spelled.slice(2).replace(/\//g, "\\")}` : spelled;
+}
+export function joinForFamily(family, base, rel) {
+    if (family === "posix")
+        return `${base.replace(/\/+$/, "")}/${rel}`;
+    if (rel.startsWith("/") || rel.startsWith("\\")) {
+        const root = /^[A-Za-z]:/.exec(base)?.[0] ?? /^[\\/]{2}[^\\/]+[\\/]+[^\\/]+/.exec(base)?.[0];
+        return root === undefined ? rel : root + rel;
+    }
+    return `${base.replace(/[\\/]+$/, "")}${base.includes("\\") ? "\\" : "/"}${rel}`;
+}
 export function lexicalViewOf(spelled, base) {
-    const abs = isAbsolutePathForm(spelled)
-        ? spelled
-        : `${base.replace(/[\\/]+$/, "")}${isWinFormPath(base) && base.includes("\\") ? "\\" : "/"}${spelled}`;
-    return normalizeAbsPathLexically(abs);
+    const family = pathFamilyOf({ root: base });
+    return normalizeAbsPathLexically(isAbsoluteForFamily(family, spelled) ? spelled : joinForFamily(family, base, spelled));
 }
 function within(rootCanonical, p) {
     if (!rootCanonical)
         return false;
-    const rootN = normalizeForCompare(rootCanonical);
-    const pN = normalizeForCompare(p);
-    if (!rootN)
+    const family = pathFamilyOf({ root: rootCanonical });
+    const rootN = pathIdentityOf(rootCanonical, family);
+    const pN = pathIdentityOf(p, family);
+    if (!rootN.ok || !pN.ok)
         return false;
-    if (pN === rootN)
+    if (pN.identity === rootN.identity)
         return true;
-    const base = rootN.endsWith(SEP) ? rootN : rootN + SEP;
-    return pN.startsWith(base);
+    return pN.identity.startsWith(rootN.identity.endsWith(SEP) ? rootN.identity : rootN.identity + SEP);
 }
 export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRootsCanonical, exactFileReadExemption, readDeny, readFace) {
-    const canon = await canonicalizeTarget(env, path, signal, baseCwd);
+    const canon = await canonicalizeTarget(env, path, signal, pathFamilyOf({ root: rootCanonical }), baseCwd);
     if (!canon.ok)
         return { ok: false, violation: { code: "invalid", message: canon.message } };
     const key = canon.key;
@@ -397,23 +499,21 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     }
     return { ok: true, key };
 }
-export async function canonicalizeTarget(env, path, signal, baseCwd) {
-    if (isWin32DeviceNamespacePath(path)) {
-        return { ok: false, message: `path "${path}" is a Win32 device-namespace path (\\\\.\\ names a raw device object, not a file); refused.` };
-    }
-    const unprefixed = stripWin32ExtendedPrefix(path);
-    if (unprefixed.startsWith("\\\\?\\")) {
-        return { ok: false, message: `path "${path}" is a Win32 extended-length namespace path with no DOS-path equivalent (only \\\\?\\<drive>: and \\\\?\\UNC\\ forms name files); refused.` };
+export async function canonicalizeTarget(env, path, signal, family, baseCwd) {
+    const screened = win32NamespaceScreen(path, family);
+    if (!screened.ok) {
+        return { ok: false, message: `path "${clipSpelling(path)}" ${WIN32_NAMESPACE_REFUSAL_TEXT[screened.refuse]}; refused (${screened.refuse}).`, refused: screened.refuse };
     }
-    if (isUncPath(unprefixed) && isWinFormPath(unprefixed)) {
+    const unprefixed = screened.spelled;
+    if (family === "win" && isUncSpelling(unprefixed)) {
         const folded = foldUncLexically(unprefixed);
         if (folded.climbedAboveShare) {
             return { ok: false, message: `path "${path}" climbs above its UNC share root via ".." (\\\\host\\share is the root of a network path); refused.` };
         }
         return { ok: true, key: folded.key };
     }
-    const spelled = unprefixed.startsWith("//") ? unprefixed.replace(/^\/+/, "/") : unprefixed;
-    const target = baseCwd && !isAbsolutePathForm(spelled) ? `${baseCwd.replace(/[\\/]+$/, "")}/${spelled}` : spelled;
+    const spelled = family === "posix" && unprefixed.startsWith("//") ? unprefixed.replace(/^\/+/, "/") : unprefixed;
+    const target = baseCwd && !isAbsoluteForFamily(family, spelled) ? joinForFamily(family, baseCwd, spelled) : spelled;
     const absR = await env.absolutePath(target, signal);
     if (!absR.ok)
         return { ok: false, message: `cannot resolve path "${path}": ${absR.error.message}` };
@@ -451,7 +551,7 @@ export async function canonicalizeTarget(env, path, signal, baseCwd) {
         if (!link.ok) {
             return { ok: false, message: `cannot read symlink "${path}": ${link.error.message}`, unresolvedSymlink: true };
         }
-        const linkTarget = isAbsolutePathForm(link.value) ? link.value : `${parentDir(abs)}${nativeSepOf(abs)}${link.value}`;
+        const linkTarget = isAbsoluteForFamily(family, link.value) ? link.value : joinForFamily(family, parentDir(abs), link.value);
         const reabs = await env.absolutePath(linkTarget, signal);
         if (!reabs.ok) {
             return { ok: false, message: `cannot resolve symlink target "${linkTarget}" for "${path}": ${reabs.error.message}`, unresolvedSymlink: true };

package/dist/tools/fs/search.js

@@ -1,6 +1,6 @@
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MAX_EXEC_OUTPUT_BYTES } from "../../core/exec-output-tail.js";
-import { hasBinaryExtension, isAbsolutePathForm, isWinFormPath } from "./safety.js";
+import { hasBinaryExtension, isAbsoluteForFamily, isWinFormPath, joinForFamily, pathFamilyOf } from "./safety.js";
 const WALK_MAX_FILES = 5000;
 const WALK_MAX_DEPTH = 32;
 const GREP_DEFAULT_CAP = 250;
@@ -776,7 +776,8 @@ export async function jsGrepDetailed(env, root, p, signal, guards, deny, denyOut
     }
     const ignore = await buildIgnore(env, root, signal);
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
-    const start = p.path ? (isAbsolutePathForm(p.path) ? p.path : `${rootPrefix}${p.path}`) : root;
+    const family = pathFamilyOf({ root });
+    const start = p.path ? (isAbsoluteForFamily(family, p.path) ? p.path : joinForFamily(family, root, p.path)) : root;
     let walked;
     if (p.path) {
         const info = await env.fileInfo(start, signal);
@@ -1054,10 +1055,10 @@ export function detectRipgrep(env) {
 async function sortRgFilesByMtime(env, root, records, signal) {
     if (records.length === 0)
         return [...records];
-    const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
+    const family = pathFamilyOf({ root });
     const toAbs = (p) => {
         const stripped = p.startsWith("./") ? p.slice(2) : p;
-        return isAbsolutePathForm(stripped) ? stripped : `${rootPrefix}${stripped}`;
+        return isAbsoluteForFamily(family, stripped) ? stripped : joinForFamily(family, root, stripped);
     };
     const paths = records.map((r) => r.path ?? r.text);
     const infos = await Promise.all(paths.map((p) => env.fileInfo(toAbs(p), signal)));
@@ -1231,7 +1232,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
         if (deny === undefined || deny.rgExclusionGlobs.length === 0)
             return { note: "" };
         if (p.path) {
-            const startPath = isAbsolutePathForm(p.path) ? p.path : `${root.replace(/[\\/]+$/, "")}${root.includes("\\") ? "\\" : "/"}${p.path}`;
+            const startPath = isAbsoluteForFamily(pathFamilyOf({ root }), p.path) ? p.path : joinForFamily(pathFamilyOf({ root }), root, p.path);
             const info = await env.fileInfo(startPath, signal);
             if (info.ok && info.value.kind === "file")
                 return { note: "" };
@@ -1322,7 +1323,8 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     const t0 = Date.now();
     const baseIgnore = await buildIgnore(env, root, signal);
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
-    const start = opts.path ? (isAbsolutePathForm(opts.path) ? opts.path : `${rootPrefix}${opts.path}`) : root;
+    const family = pathFamilyOf({ root });
+    const start = opts.path ? (isAbsoluteForFamily(family, opts.path) ? opts.path : joinForFamily(family, root, opts.path)) : root;
     if (opts.path !== undefined) {
         const probe = await env.fileInfo(start, signal);
         if (!probe.ok && probe.error.code === "not_found") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.16.0",
+  "version": "7.17.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -85,6 +85,7 @@
     "gate:backlog-ledger": "node scripts/verify-backlog-ledger.mjs",
     "gate:docs-tool-names": "node scripts/verify-docs-tool-names.mjs",
     "gate:comment-ratio": "vitest run test/comment-ratio-ratchet.test.ts",
+    "gate:negative-controls": "vitest run test/gate-negative-controls.test.ts",
     "gate:all": "node scripts/gate-all.mjs",
     "car:gate": "node scripts/car-gate.mjs"
   },