@cspeach/cli 1.1.23 → 1.1.25

package/dist/tools/_filesystem-shared.js

@@ -8,7 +8,8 @@
  * resolveSafePath before doing any IO.
  */
 import * as path from 'node:path';
-import { promises as fsPromises } from 'node:fs';
+import { promises as fsPromises, realpathSync, existsSync } from 'node:fs';
+import { cspeachRoot } from '../config/paths.js';
 /**
  * Phase 3 sensitive in-root directory prefixes — refused by all filesystem
  * tools. Matched as `rel === prefix` or `rel` starts with `prefix + '/'`.
@@ -110,36 +111,49 @@ export function blockedExecutableExtension(targetPath) {
     return BLOCKED_EXECUTABLE_EXTS.has(ext) ? ext : null;
 }
 /**
- * True if `realAbsPath` is denylisted relative to root — either it falls under
- * one of BLOCKED_PREFIXES (directory prefixes) or its basename is in the
- * `.env` family. Caller should refuse the operation when `blocked` is true.
- *
- * CARVE-OUT — the four skill working subdirectories under `.cspeach/`
- * (CSPEACH_WORK_SUBDIRS = cca/upgrades/modernize/tests) are ALLOWED so skills
- * can read+write their own detail files. A path is carved out (NOT blocked)
- * iff ALL hold:
- *   1. its root-relative path (lowercased, '/'-separated) starts with
- *      `.cspeach/<sub>/` for some <sub> in CSPEACH_WORK_SUBDIRS — i.e. it is
- *      STRICTLY INSIDE one of those subdirs (the subdir entry itself is not
- *      carved out), AND
- *   2. its basename does NOT end with `.cspeach.json` (those envelopes are
- *      CLI-owned — direct writes stay blocked), AND
- *   3. its basename is NOT in the `.env` secret family (BLOCKED_BASENAME_RE).
- * The carve-out short-circuits ONLY the `.cspeach` prefix. `.git`,
- * `.cspeach-design`, the `.cspeach` root, non-work subdirs, and `.env*`
- * everywhere else remain blocked.
+ * A path segment the way NTFS resolves it for a name compare:
+ *   - drop any `:stream` / `::$TYPE` / `:$I30:$INDEX_ALLOCATION` suffix
+ *     (`.git::$INDEX_ALLOCATION` opens the `.git` folder, `.env::$DATA` opens
+ *     the `.env` file), then
+ *   - strip trailing dots and spaces (`.git.`, `.git `, `.env ` open the
+ *     same object as the bare name).
+ * `.` and `..` are kept as-is (they are navigation, not names).
  */
-export function isDenylistedPath(realAbsPath, root) {
-    const relFromRoot = path.relative(path.resolve(root), realAbsPath).replace(/\\/g, '/');
+function ntfsCanonicalSegment(seg) {
+    if (seg === '.' || seg === '..')
+        return seg;
+    const colon = seg.indexOf(':');
+    const name = colon === -1 ? seg : seg.slice(0, colon);
+    return name.replace(/[. ]+$/, '');
+}
+/**
+ * Windows reserved device names — `CON`, `PRN`, `AUX`, `NUL`, `COM0`-`COM9`,
+ * `LPT0`-`LPT9` (and the superscript-digit forms) — WITH OR WITHOUT an
+ * extension, ignoring trailing dots/spaces: `CON.xml` and `nul.txt` open the
+ * device, not a file. The one shared rule for every name check.
+ */
+export function isWindowsReservedName(name) {
+    const stem = (name.replace(/[. ]+$/, '').split('.')[0] ?? '').replace(/ +$/, '');
+    return /^(CON|PRN|AUX|NUL|COM[0-9¹²³]|LPT[0-9¹²³])$/i.test(stem);
+}
+/**
+ * The denylist decision on one root-relative, '/'-separated path. Pure string
+ * logic, no normalization — isDenylistedPath runs it on the raw AND the
+ * canonical spelling and blocks if either is blocked.
+ */
+function relIsDenylisted(rel) {
     // Case-insensitive comparison: macOS APFS (default) and Windows NTFS (default)
     // are case-insensitive filesystems, so `.Cspeach/auth.json` resolves to the
     // SAME inode as `.cspeach/auth.json`. A byte-exact denylist match would let
-    // the model bypass protection with a one-keystroke case change. The returned
-    // `relFromRoot` keeps its ORIGINAL case so callers can log what the model
-    // actually requested.
-    const relLower = relFromRoot.toLowerCase();
-    const base = path.basename(relFromRoot);
+    // the model bypass protection with a one-keystroke case change.
+    const relLower = rel.toLowerCase();
+    const base = path.posix.basename(rel);
     const baseLower = base.toLowerCase();
+    // `.git` at ANY depth — a nested repo or submodule (`sub/.git/hooks/…`) is
+    // the same code-execution target as the root one. Checked before the
+    // carve-out so nothing can short-circuit it.
+    if (relLower.split('/').includes('.git'))
+        return true;
     // ── CARVE-OUT: .cspeach/<work-subdir>/… — short-circuits ONLY .cspeach. ──
     // Must be strictly INSIDE a work subdir, not a CLI-owned envelope, and not
     // an .env secret. Placed before the prefix loop so it can return early, but
@@ -147,7 +161,7 @@ export function isDenylistedPath(realAbsPath, root) {
     for (const sub of CSPEACH_WORK_SUBDIRS) {
         if (relLower.startsWith('.cspeach/' + sub + '/')) {
             if (!baseLower.endsWith('.cspeach.json') && !BLOCKED_BASENAME_RE.test(base)) {
-                return { blocked: false, relFromRoot };
+                return false;
             }
             break; // inside a work subdir but failed an exclusion → fall through to block
         }
@@ -156,14 +170,204 @@ export function isDenylistedPath(realAbsPath, root) {
     for (const prefix of BLOCKED_PREFIXES) {
         const prefixLower = prefix.toLowerCase();
         if (relLower === prefixLower || relLower.startsWith(prefixLower + '/')) {
-            return { blocked: true, relFromRoot };
+            return true;
         }
     }
     // Basename denylist — the .env family at ANY depth (.env, .env.local, …).
     // Using the basename (not a prefix) is what catches `.env.production` while
     // still excluding `.environment-notes.md` and `.envrc`.
-    if (BLOCKED_BASENAME_RE.test(base)) {
-        return { blocked: true, relFromRoot };
+    return BLOCKED_BASENAME_RE.test(base);
+}
+/**
+ * Windows 8.3 short names (`GIT~1` for `.git`) cannot be decided by string
+ * math: the alias exists only if the volume generated one. Resolve the
+ * nearest EXISTING ancestor through the filesystem (realpath expands short
+ * names) and re-attach the not-yet-existing tail, so a file that does not
+ * exist yet (`GIT~1/hooks/pre-commit`) is judged by its long-name path.
+ *
+ * Only "does not exist" (ENOENT) moves the walk up a level. Any OTHER error
+ * (EACCES, EPERM, EIO, ELOOP, …) means we cannot tell what the name aliases,
+ * so the caller must fail closed — `{ failClosed: true }`. Returns null only
+ * when nothing up to the drive root exists.
+ */
+function longNameAbs(absPath) {
+    let cur = path.win32.resolve(absPath);
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync.native(cur);
+            return { abs: tail.length ? path.win32.join(real, ...tail) : real };
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                return { failClosed: true };
+            const parent = path.win32.dirname(cur);
+            if (parent === cur)
+                return null;
+            tail.unshift(path.win32.basename(cur));
+            cur = parent;
+        }
+    }
+}
+/** realpath of an existing folder, or null. Successful lookups are cached (per spelling). */
+const realDirCache = new Map();
+function realDirOrNull(dir) {
+    const hit = realDirCache.get(dir);
+    if (hit !== undefined)
+        return hit;
+    try {
+        const real = realpathSync.native(dir);
+        realDirCache.set(dir, real);
+        return real;
+    }
+    catch {
+        return null;
+    }
+}
+/** `rel` is the root itself or strictly below it (not `..`, not another drive). */
+function relIsInside(p, rel) {
+    return rel === '' || (!rel.startsWith('..') && !p.isAbsolute(rel));
+}
+/**
+ * True if `absPath` is the CLI home (`cspeachRoot()`, `~/.cspeach`) or below
+ * it — auth tokens, config, sessions, snapshots, logs. Checked against the
+ * spelled and the real home, and through NTFS spellings of the `.cspeach`
+ * segment (`.cspeach.`, `.cspeach `), case-insensitively.
+ */
+function isUnderCliHome(absPath, p, native) {
+    const home = cspeachRoot();
+    const homes = [p.resolve(home)];
+    if (native) {
+        const real = realDirOrNull(home);
+        if (real && real !== homes[0])
+            homes.push(real);
+    }
+    for (const h of homes) {
+        const fromParent = p.relative(p.dirname(h), absPath).replace(/\\/g, '/');
+        if (!relIsInside(p, fromParent) || fromParent === '')
+            continue;
+        const first = ntfsCanonicalSegment(fromParent.split('/')[0]).toLowerCase();
+        if (first === p.basename(h).toLowerCase())
+            return true;
+    }
+    return false;
+}
+/**
+ * True if `realAbsPath` is denylisted relative to root — either it falls under
+ * one of BLOCKED_PREFIXES (directory prefixes) or its basename is in the
+ * `.env` family. Caller should refuse the operation when `blocked` is true.
+ *
+ * CARVE-OUT — the four skill working subdirectories under `.cspeach/`
+ * (CSPEACH_WORK_SUBDIRS = cca/upgrades/modernize/tests) are ALLOWED so skills
+ * can read+write their own detail files. A path is carved out (NOT blocked)
+ * iff ALL hold:
+ *   1. its root-relative path (lowercased, '/'-separated) starts with
+ *      `.cspeach/<sub>/` for some <sub> in CSPEACH_WORK_SUBDIRS — i.e. it is
+ *      STRICTLY INSIDE one of those subdirs (the subdir entry itself is not
+ *      carved out), AND
+ *   2. its basename does NOT end with `.cspeach.json` (those envelopes are
+ *      CLI-owned — direct writes stay blocked), AND
+ *   3. its basename is NOT in the `.env` secret family (BLOCKED_BASENAME_RE).
+ * The carve-out short-circuits ONLY the `.cspeach` prefix. `.git`,
+ * `.cspeach-design`, the `.cspeach` root, non-work subdirs, and `.env*`
+ * everywhere else remain blocked.
+ *
+ * `.git` is blocked at ANY depth (nested repos, submodules), not only at the
+ * root — its hooks are a code-execution target wherever it lives.
+ *
+ * The CLI HOME (`cspeachRoot()`, `~/.cspeach`) is blocked WHATEVER the root —
+ * also when the CLI runs from `C:\Users`, `C:\` or `/home`, where it is not a
+ * root-level `.cspeach`. The carve-out does not apply there.
+ *
+ * WINDOWS NAME ALIASES (SEC fix, `.git::$INDEX_ALLOCATION`). NTFS opens the
+ * same object under spellings that do not byte-match the denylist:
+ *   - stream suffixes: `.git::$INDEX_ALLOCATION`, `.git:$I30:$INDEX_ALLOCATION`,
+ *     `.env::$DATA`, `name:stream`;
+ *   - trailing dots/spaces: `.git.`, `.git `, `.env `;
+ *   - 8.3 short names: `GIT~1`.
+ * So, in order:
+ *   1. win32: ANY root-relative segment containing ':' is refused outright.
+ *      No project file needs an NTFS alternate data stream, and refusing the
+ *      whole class is safer than enumerating stream types.
+ *   2. All platforms: the denylist is applied to the raw path AND to the
+ *      canonical path (every segment through ntfsCanonicalSegment); blocked if
+ *      either matches. On POSIX ':' and trailing dots are legal, distinct
+ *      names, so ordinary names (`notes:12.md`, `report.`) are NOT refused —
+ *      only a denylisted name wearing a suffix (`.git:x`, `.git.`), which is a
+ *      real alias on an NTFS/SMB mount and never a legitimate project file.
+ *   3. win32: when a segment contains '~' (a possible 8.3 short name), the
+ *      path is also resolved through the filesystem (longNameAbs) and the
+ *      long-name path is checked too. If that lookup fails for any reason
+ *      other than "does not exist", the path is BLOCKED (fail closed).
+ *
+ * If the root is spelled differently from its real path (a link, an 8.3
+ * name, macOS `/var` → `/private/var`) and `realAbsPath` is a REAL path, the
+ * relative path is also computed against the real root, so a real path is
+ * never misread as "outside root, not denylisted".
+ *
+ * `platform` exists for tests (exercise the POSIX rules on a Windows box and
+ * vice versa); production callers omit it. Filesystem lookups only run when
+ * `platform` is the platform the process actually runs on.
+ */
+export function isDenylistedPath(realAbsPath, root, platform = process.platform) {
+    const isWin = platform === 'win32';
+    const native = platform === process.platform;
+    const p = isWin ? path.win32 : path.posix;
+    const absRoot = p.resolve(root);
+    // The returned `relFromRoot` keeps its ORIGINAL case/spelling so callers can
+    // log what the model actually requested.
+    let relFromRoot = p.relative(absRoot, realAbsPath).replace(/\\/g, '/');
+    // Root-relative spellings to judge: against the spelled root, and — when the
+    // path sits outside it — against the real root. A real path under a
+    // junctioned/linked root is SHOWN relative to the real root too, so messages
+    // read `.git/hooks/x`, not `../../real/.git/hooks/x`.
+    const rels = [relFromRoot];
+    if (native && !relIsInside(p, relFromRoot)) {
+        const realRoot = realDirOrNull(absRoot);
+        if (realRoot && realRoot !== absRoot) {
+            const realRel = p.relative(realRoot, realAbsPath).replace(/\\/g, '/');
+            rels.push(realRel);
+            if (relIsInside(p, realRel))
+                relFromRoot = realRel;
+        }
+    }
+    const blocked = { blocked: true, relFromRoot };
+    // The CLI home is protected whatever the root.
+    if (isUnderCliHome(realAbsPath, p, native))
+        return blocked;
+    for (const rel of rels) {
+        const segments = rel.split('/');
+        // (1) win32: an NTFS stream / stream-type suffix anywhere → refuse.
+        if (isWin && segments.some((seg) => seg.includes(':')))
+            return blocked;
+        // (2) raw spelling, then the NTFS-canonical spelling.
+        if (relIsDenylisted(rel))
+            return blocked;
+        const canonical = segments.map(ntfsCanonicalSegment).join('/');
+        if (canonical !== rel && relIsDenylisted(canonical))
+            return blocked;
+    }
+    // (3) win32: possible 8.3 short name → judge the long-name path too.
+    if (isWin && native && rels[0].split('/').some((seg) => seg.includes('~'))) {
+        const long = longNameAbs(realAbsPath);
+        if (long && 'failClosed' in long)
+            return blocked;
+        if (long) {
+            if (isUnderCliHome(long.abs, p, native))
+                return blocked;
+            const roots = [absRoot];
+            const realRoot = realDirOrNull(absRoot);
+            if (realRoot && realRoot !== absRoot)
+                roots.push(realRoot);
+            for (const r of roots) {
+                const longRel = p.relative(r, long.abs).replace(/\\/g, '/');
+                if (!relIsInside(p, longRel))
+                    continue;
+                const longCanonical = longRel.split('/').map(ntfsCanonicalSegment).join('/');
+                if (relIsDenylisted(longRel) || relIsDenylisted(longCanonical))
+                    return blocked;
+            }
+        }
     }
     return { blocked: false, relFromRoot };
 }
@@ -214,11 +418,137 @@ export function resolveSafePath(root, userPath) {
  * found" condition.
  */
 export async function assertRealPathContained(absInputPath, root) {
-    const absRoot = path.resolve(root);
     const real = await fsPromises.realpath(absInputPath);
-    const rel = path.relative(absRoot, real);
-    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    if (!isInsideRoot(real, root))
         throw new PathOutsideRootError(absInputPath, root);
+    return real;
+}
+/**
+ * `target` (a REAL path) is inside root — compared with the root as spelled
+ * and with the root's own real path, so a root that sits behind a link or an
+ * 8.3 name (macOS `/var` → `/private/var`) still contains its own files.
+ */
+export function isInsideRoot(target, root) {
+    const absRoot = path.resolve(root);
+    if (relIsInside(path, path.relative(absRoot, target)))
+        return true;
+    const realRoot = realOfNearestOrNull(absRoot);
+    return realRoot !== null && realRoot !== absRoot && relIsInside(path, path.relative(realRoot, target));
+}
+/**
+ * Real form of a folder that may not exist yet: nearest existing ancestor
+ * realpath'd, missing tail re-attached. null on any non-ENOENT error.
+ */
+function realOfNearestOrNull(abs) {
+    let cur = abs;
+    const tail = [];
+    for (;;) {
+        const real = realDirOrNull(cur);
+        if (real !== null)
+            return tail.length ? path.join(real, ...tail) : real;
+        if (existsSync(cur))
+            return null; // exists but realpath failed — no real form
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return null;
+        tail.unshift(path.basename(cur));
+        cur = parent;
+    }
+}
+/**
+ * The REAL path a write to `absInputPath` will land on, for a target that may
+ * not exist yet. Walks up to the nearest EXISTING ancestor, realpaths it
+ * (following links and expanding Windows 8.3 short names), re-attaches the
+ * not-yet-existing tail, and verifies the result is inside root. Throws
+ * PathOutsideRootError on escape; rethrows any non-ENOENT fs error.
+ *
+ * Write tools MUST hand this result (not the user-spelled path) to
+ * isDenylistedPath: `docs/hooks/pre-commit` where `docs` links to `.git`, or
+ * `GIT~1/hooks/pre-commit`, only show up as `.git/...` after resolution.
+ */
+export async function realPathForWrite(absInputPath, root) {
+    let cur = path.resolve(absInputPath);
+    const tail = [];
+    for (;;) {
+        let real;
+        try {
+            real = await fsPromises.realpath(cur);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                throw err;
+            tail.unshift(path.basename(cur));
+            cur = parent;
+            continue;
+        }
+        const target = tail.length ? path.join(real, ...tail) : real;
+        if (!isInsideRoot(target, root))
+            throw new PathOutsideRootError(absInputPath, root);
+        return target;
+    }
+}
+/** Sync twin of realPathForWrite, for engines whose write path is synchronous. */
+export function realPathForWriteSync(absInputPath, root) {
+    let cur = path.resolve(absInputPath);
+    const tail = [];
+    for (;;) {
+        let real;
+        try {
+            real = realpathSync.native(cur);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                throw err;
+            tail.unshift(path.basename(cur));
+            cur = parent;
+            continue;
+        }
+        const target = tail.length ? path.join(real, ...tail) : real;
+        if (!isInsideRoot(target, root))
+            throw new PathOutsideRootError(absInputPath, root);
+        return target;
+    }
+}
+/**
+ * The one-call write gate: the real landing path of `absInputPath` must be
+ * inside `containRoot` and not denylisted relative to `denyRoot` (nor to
+ * `containRoot`), judged on BOTH the spelled and the real path. Throws
+ * PathOutsideRootError on escape and ProtectedPathError on a denylisted path.
+ * Returns the real landing path.
+ */
+export class ProtectedPathError extends Error {
+    relFromRoot;
+    constructor(relFromRoot) {
+        super(`refusing to write protected path "${relFromRoot}" (denylist: ${DENYLIST_DESCRIPTION})`);
+        this.relFromRoot = relFromRoot;
+        this.name = 'ProtectedPathError';
+    }
+}
+export function assertWritableSync(absInputPath, containRoot, denyRoot = containRoot) {
+    const real = realPathForWriteSync(absInputPath, containRoot);
+    for (const cand of [path.resolve(absInputPath), real]) {
+        for (const r of new Set([denyRoot, containRoot])) {
+            const v = isDenylistedPath(cand, r);
+            if (v.blocked)
+                throw new ProtectedPathError(v.relFromRoot);
+        }
+    }
+    return real;
+}
+export async function assertWritable(absInputPath, containRoot, denyRoot = containRoot) {
+    const real = await realPathForWrite(absInputPath, containRoot);
+    for (const cand of [path.resolve(absInputPath), real]) {
+        for (const r of new Set([denyRoot, containRoot])) {
+            const v = isDenylistedPath(cand, r);
+            if (v.blocked)
+                throw new ProtectedPathError(v.relFromRoot);
+        }
     }
     return real;
 }

package/dist/tools/cap/metadata-import.js

@@ -40,12 +40,10 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { registerTool } from '../index.js';
-import { resolveSafePath, isDenylistedPath, BLOCKED_PREFIXES } from '../_filesystem-shared.js';
+import { resolveSafePath, isDenylistedPath, BLOCKED_PREFIXES, assertWritable, isWindowsReservedName } from '../_filesystem-shared.js';
 import { loadConfig } from '../../config/loader.js';
 import { PlainFetchError, plainSapFetchError } from './_fetch-errors.js';
 const NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,59}$/;
-/** Windows device names: `CON.edmx` opens the console, not a file. */
-const RESERVED_NAME_RE = /^(CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])$/i;
 /** projectDir characters. No `:` (drive letters, NTFS streams), no wildcards, no control chars. */
 const PROJECT_DIR_RE = /^[A-Za-z0-9._\-/\\ ]*$/;
 /** Longest start tag we read attributes from; longer ones are skipped. */
@@ -185,7 +183,7 @@ export async function capMetadataImportHandler(args, ctx, deps = {}) {
     if (!NAME_RE.test(apiName)) {
         return fail('apiName must be a plain name like API_BUSINESS_PARTNER: a letter first, then letters, digits or _, at most 60.');
     }
-    if (RESERVED_NAME_RE.test(apiName)) {
+    if (isWindowsReservedName(apiName)) {
         return fail(`apiName ${apiName} is a reserved Windows device name. Use another name, such as API_${apiName.toUpperCase()}.`);
     }
     const svc = validServicePath(args.servicePath);
@@ -224,6 +222,14 @@ export async function capMetadataImportHandler(args, ctx, deps = {}) {
     if (await isSymlink(target)) {
         return fail(`${relFromRoot} is a symlink. Remove it first; the import never writes through a link.`);
     }
+    // The REAL landing path (links followed, Windows short names expanded) must
+    // not be protected either — `projectDir` may be a junction to `.git`.
+    try {
+        await assertWritable(target, rootAbs);
+    }
+    catch {
+        return fail(outsideMsg);
+    }
     // ── Fetch. ──
     const get = deps.get ?? (async (p) => {
         const cfg = await loadConfig();

package/dist/tools/filesystem/file-write.js

@@ -9,18 +9,16 @@
  * Write is atomic: content goes to <path>.tmp then fs.rename swaps it in so
  * a crash mid-write never leaves a partial file at the target path.
  *
- * Path containment via resolveSafePath + assertRealPathContained. For
- * non-existent target files (the common create case), assertRealPathContained
- * would throw ENOENT because fs.realpath requires the path to exist. In that
- * case we fall back to verifying the parent directory is contained instead,
- * using the original abs path (from resolveSafePath) as the write target.
+ * Path containment via resolveSafePath + realPathForWrite: the real landing
+ * path (nearest existing ancestor realpath'd, missing tail re-attached) is
+ * what gets contained, denylisted and written — never the user's spelling.
  *
  * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_FILE_WRITE=on.
  */
 import { promises as fs, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
-import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath, blockedExecutableExtension, } from '../_filesystem-shared.js';
+import { resolveSafePath, realPathForWrite, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath, blockedExecutableExtension, } from '../_filesystem-shared.js';
 /**
  * 2026-09-23 (Glenn's first run) — a standalone run writes GUIDE.md and said
  * nothing about it. He opened it in a text editor, then tried to drop it into
@@ -69,45 +67,20 @@ export async function fileWriteHandler(args, ctx) {
         }
         return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
     }
-    // 2. Path containment — async phase (follows symlinks to catch symlink escapes).
-    //    For non-existent files (the common create case), fs.realpath throws ENOENT.
-    //    In that case, verify the parent directory is contained instead.
+    // 2. Path containment — async phase. Resolve the REAL landing path: the
+    //    nearest existing ancestor is realpath'd (links followed, Windows 8.3
+    //    short names expanded) and the not-yet-existing tail re-attached. The
+    //    denylist below MUST see this real path — the user's spelling can hide
+    //    `.git` behind a link (`docs -> .git`) or a short name (`GIT~1`).
     let target;
     try {
-        target = await assertRealPathContained(abs, ctx.cwd);
+        target = await realPathForWrite(abs, ctx.cwd);
     }
     catch (err) {
-        if (err.code === 'ENOENT') {
-            // Target file doesn't exist yet (create case) — verify parent is contained.
-            const parent = path.dirname(abs);
-            try {
-                await assertRealPathContained(parent, ctx.cwd);
-            }
-            catch (parentErr) {
-                if (parentErr.code === 'ENOENT') {
-                    // Parent doesn't exist either (will be mkdir -p'd) — verify via string math.
-                    const relFromRoot = path.relative(path.resolve(ctx.cwd), parent);
-                    if (relFromRoot.startsWith('..') || path.isAbsolute(relFromRoot)) {
-                        return { content: 'error: parent directory escapes project root', is_error: true };
-                    }
-                    // Parent is fine — use the original abs as write target.
-                }
-                else if (parentErr instanceof PathOutsideRootError) {
-                    return { content: `error: ${parentErr.message}`, is_error: true };
-                }
-                else {
-                    return { content: `error: ${parentErr.message}`, is_error: true };
-                }
-            }
-            // Use the original abs path (resolveSafePath result) as write target.
-            target = abs;
-        }
-        else if (err instanceof PathOutsideRootError) {
+        if (err instanceof PathOutsideRootError) {
             return { content: `error: ${err.message} (after symlink resolution)`, is_error: true };
         }
-        else {
-            return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
-        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
     }
     // 3. Denylist check: refuse sensitive in-root paths
     const denylist = isDenylistedPath(target, ctx.cwd);

package/dist/tools/filesystem/glob.js

@@ -19,7 +19,7 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
-import { resolveSafePath, PathOutsideRootError, isDenylistedPath } from '../_filesystem-shared.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, isDenylistedPath, DENYLIST_DESCRIPTION, } from '../_filesystem-shared.js';
 const MAX_RESULTS = 500;
 const MAX_FILES_TRAVERSED = 10_000;
 const ALWAYS_SKIPPED_DIRS = new Set([
@@ -150,7 +150,30 @@ export async function globHandler(args, ctx) {
             }
         }
     }
-    await walk(searchRoot, '');
+    // The search root is judged by its REAL path: a junction/symlink used as
+    // the root (`docs -> .git`, `ext -> /outside`) must neither escape root nor
+    // open a protected folder. The walk then runs on the real path, so every
+    // per-file denylist check below sees real paths too.
+    let realRoot;
+    try {
+        realRoot = await assertRealPathContained(searchRoot, ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message} (after symlink resolution)`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    for (const cand of [searchRoot, realRoot]) {
+        const verdict = isDenylistedPath(cand, ctx.cwd);
+        if (verdict.blocked) {
+            return {
+                content: `error: refusing to list protected path "${verdict.relFromRoot}" (denylist: ${DENYLIST_DESCRIPTION})`,
+                is_error: true,
+            };
+        }
+    }
+    await walk(realRoot, '');
     // Sort by mtime descending, cap at MAX_RESULTS
     collected.sort((a, b) => b.mtime - a.mtime);
     const sample = collected.slice(0, MAX_RESULTS).map((f) => f.relPath);

package/dist/tools/filesystem/grep.js

@@ -20,7 +20,7 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
-import { resolveSafePath, PathOutsideRootError, isDenylistedPath } from '../_filesystem-shared.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, isDenylistedPath, DENYLIST_DESCRIPTION, } from '../_filesystem-shared.js';
 import { globToRegex } from './glob.js';
 const MAX_MATCHES = 250;
 const MAX_FILES_TRAVERSED = 10_000;
@@ -129,7 +129,30 @@ export async function grepHandler(args, ctx) {
             }
         }
     }
-    await walk(searchRoot, '');
+    // The search root is judged by its REAL path: a junction/symlink used as
+    // the root (`docs -> .git`, `ext -> /outside`) must neither escape root nor
+    // open a protected folder. The walk then runs on the real path, so every
+    // per-file denylist check below sees real paths too.
+    let realRoot;
+    try {
+        realRoot = await assertRealPathContained(searchRoot, ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message} (after symlink resolution)`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    for (const cand of [searchRoot, realRoot]) {
+        const verdict = isDenylistedPath(cand, ctx.cwd);
+        if (verdict.blocked) {
+            return {
+                content: `error: refusing to search protected path "${verdict.relFromRoot}" (denylist: ${DENYLIST_DESCRIPTION})`,
+                is_error: true,
+            };
+        }
+    }
+    await walk(realRoot, '');
     if (matches.length === 0) {
         return { content: `no matches for /${args.pattern}/${args.case_insensitive ? 'i' : ''}` };
     }