[FEATURE] Mods API: add file identity, change time and case facts to $.fs.stat and $.fs.list

Status Open
Reported on v2.1.296
Maintainer reply None cached
Activity 0 comments · opened Oct 11, 2026

Preflight Checklist

  • [x] I have searched existing requests and this feature hasn't been requested yet
  • [x] This is a single feature request (not multiple features)

Problem Statement

Guard mods compare paths. Claude Code 2.1.296 (macOS) declares, doc comments removed:

export type FsStat = {
    kind: 'file' | 'dir' | 'other';
    size: number;
    mtimeMs: number;
    isLink: boolean;
    realPath?: string;
};

FsEntry ($.fs.list) has name, kind, size, mtimeMs, isLink. Three facts are missing:

  1. File identity. No dev, ino or nlink. The realPath doc says "a hard link ... or a case alias keeps its own spelling". A mod cannot see a file's second name.
  2. Change time. Only mtimeMs, which touch -t sets back.
  3. Letter case. On a case-insensitive volume, cat /work/SECRET reads /work/secret. No API says whether a folder ignores case.

Proposed Solution

  1. FsStat and FsEntry: add dev, ino, nlink, ctimeMs (numbers) and birthtimeMs?.
  2. FsStat with { resolve: true }: guarantee on-disk case in realPath, and update the doc. The embedded Bun realpath seems to do this already on APFS (tested outside Claude Code).
  3. FsStat: add caseSensitive?: boolean for the folder (macOS pathconf(_PC_CASE_SENSITIVE), Linux casefold), to judge names not on disk yet.

Alternative Solutions

$.process.run(['stat', ...]) per file: one process each while a tool call waits.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

  1. Sandbox Tuner walks guarded places for links before a one-press folder allowWrite. It sees symlinks only, so a hard link passes (Known limits). dev, ino and nlink on $.fs.list entries would catch it.
  2. Arrester skips interpreter scripts last changed before the oldest open block. touch -t defeats that. An unprivileged process cannot set ctimeMs back.
  3. Arrester compares letter case exactly (Known limits). Proposed items 2 and 3 would let it stop cat /work/SECRET.

Additional Context

  • Related: a #91870 comment asked for symlink resolution, now { resolve: true }.
  • Out of scope: the Bash sandbox could refuse writes through a file with a second name outside allowWrite.

View original on GitHub ↗