文件系统 capability 与策略

102    async execute(args: WriteToolArgs, exec) {103      const input = parseWriteArgs(args)104      // Resolve the per-call sandbox policy (approved mode > session override105      // > backend default, plus the session cwd root) BEFORE anything executes;106      // an escalating call throws its distinct text on any non-grant.107      const sandboxPolicy = await sandbox.resolvePolicy('write', args, exec)108      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot))109      // Single-slot decision: the policy plugin produces createIfAbsent/110      // replaceIfVersion; the bare default is undefined (unconditional). No stat.111      const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)112      let outcome: FsWriteOutcome113      try {114        outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal, sandboxPolicy)115      } catch (error: unknown) {116        // A sandbox denial becomes the shared [sandbox: …] marker (the model117        // recognizes it from bash); stale/not-observed failures gain their118        // model-facing remedy; anything else passes through.119        throw remediateFsError(sandbox.mapError(error, sandboxPolicy))120      }121      // Record the present observation (a no-op when no policy plugin listens).122      ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)123      return {124        path: target.displayPath,125        operation: outcome.operation,126        before: outcome.before,127        after: outcome.after,128      }129    },

86export abstract class FileSystem extends Service {87  constructor(ctx: Context) {88    super(ctx, 'fs')89  }

146export async function resolveLocalTarget(cwd: string, path: string): Promise<LocalTarget> {147  if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')148  const displayPath = resolve(cwd, path)149  try {150    // Prefer the file's own realpath (resolves a symlinked file to its target).151    return { displayPath, targetKey: FsTargetKey(await realpath(displayPath)) }152  } catch (error: unknown) {153    // A path component is a file, not a directory (e.g. "afile/child.txt" where154    // "afile" is a regular file): the target can neither exist nor be created,155    // so surface the structured taxonomy instead of a raw Node ENOTDIR.156    /* v8 ignore next -- Windows reports this case as ENOENT and repairs it in the ancestor walk below. */157    if (isENOTDIR(error)) throw new FsError(`cannot resolve "${displayPath}": a parent path segment is not a directory`, 'FS_NOT_FOUND')158    /* v8 ignore next -- non-ENOENT realpath failure needs a permission/IO fault; ENOENT falls through to ancestor resolution. */159    if (!isENOENT(error)) throw error160  }161  // File absent: realpath the nearest existing ancestor and re-append the162  // missing suffix (the file basename plus any not-yet-created intermediate163  // dirs), so the key is stable across creation of those dirs.164  const missing = [basename(displayPath)]165  let ancestor = dirname(displayPath)166  while (true) {167    try {168      const realAncestor = await realpath(ancestor)169      // On Windows, realpath of a regular file succeeds where POSIX returns170      // ENOTDIR (the OS reports ENOENT for `regular-file/child`, not ENOTDIR).171      // Stat the ancestor to restore the semantic distinction: a non-directory172      // ancestor means the target passes through a file and can never be created.173      /* v8 ignore start -- native Windows coverage exercises this repair; POSIX reports ENOTDIR before this point. */174      if (process.platform === 'win32') {175        const parentInfo = await stat(realAncestor)176        if (!parentInfo.isDirectory()) {177          throw new FsError(`cannot resolve "${displayPath}": a parent path segment is not a directory`, 'FS_NOT_FOUND')178        }179      }180      /* v8 ignore stop */181      return { displayPath, targetKey: FsTargetKey(join(realAncestor, ...missing)) }182    } catch (error: unknown) {183      /* v8 ignore next -- native Windows coverage exercises the FsError raised by the repair above. */184      if (error instanceof FsError) throw error185      /* v8 ignore next -- a non-ENOENT realpath failure needs a permission/IO fault. */186      if (!isENOENT(error)) throw error187      const parent = dirname(ancestor)188      /* v8 ignore next -- the filesystem root always realpaths, so the walk terminates before parent === ancestor. */189      if (parent === ancestor) return { displayPath, targetKey: FsTargetKey(displayPath) }190      missing.unshift(basename(ancestor))191      ancestor = parent192    }193  }194}

65  writeIntent(target: FsTarget, actor: object | undefined): FsWriteIntent {66    const owner = this.owner(actor)67    const prior = owner ? this.get(owner, target.targetKey) : undefined68    return prior?.kind === 'present'69      ? { kind: 'replaceIfVersion', version: prior.version }70      : { kind: 'createIfAbsent' }71  }

123export type FsWriteIntent =124  | { kind: 'createIfAbsent' }125  | { kind: 'replaceIfVersion'; version: FsVersion }

78  editIntent(target: FsTarget, actor: object | undefined): { version: FsVersion } {79    const owner = this.owner(actor)80    const prior = owner ? this.get(owner, target.targetKey) : undefined81    if (!owner || prior === undefined) {82      throw new FsError(`edit requires reading "${target.displayPath}" first`, 'FS_NOT_OBSERVED')83    }84    if (prior.kind === 'absent') {85      throw new FsError(`cannot edit "${target.displayPath}": not found`, 'FS_NOT_FOUND')86    }87    return { version: prior.version }88  }

36  private owner(actor: object | undefined): object | undefined {37    // tsgolint treats object as assignable to weak FsObservationActor, while tsc still requires the structural cast for property access.38    // See the analyzer-divergence consequence in .agents/notes/implemented/process/2026-07-29-oxlint-linter.md.39    // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- The analyzers disagree on this weak type.40    return (actor as FsObservationActor | undefined)?.agent?.session41  }

178      if (expected?.kind === 'replaceIfVersion') {179        // Stale guard: the file must still exist at the version the owner observed.180        if (!existing) throw new FsError(`cannot write "${target.displayPath}": file no longer exists`, 'FS_STALE_VERSION')181        if (existing.version !== expected.version) {182          throw new FsError(`cannot write "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')183        }184      } else if (expected?.kind === 'createIfAbsent' && existing) {185        // createIfAbsent onto an existing file: a blind overwrite — require a read first.186        throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, 'FS_NOT_OBSERVED')187      }188      // No expectation means an unconditional but still atomic write.

221  override async editText(222    target: FsTarget,223    edit: FsEditRequest,224    expected?: { version: FsVersion },225    signal?: AbortSignal,226  ): Promise<FsEditOutcome> {227    return this.withLock(target.targetKey, async () => {228      const existing = await probe(target.targetKey)229      // Stale guard before literal matching: an edit based on an old read reports230      // FS_STALE_VERSION, not FS_EDIT_NOT_FOUND/FS_AMBIGUOUS_EDIT against newer content.231      // Missing targets use the same stale code on guarded and unconditional edit paths.232      if (!existing) throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')233      if (existing.type !== 'file') throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')234      // expected === undefined: unconditional edit of the current content — no235      // version guard. Still inside the per-target lock, so the read→match→write236      // window is serialized and atomic.237      if (expected && existing.version !== expected.version) {238        throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')239      }

44declare module '@deepseek-ai/cordis' {45  interface Context {46    fs: FileSystem47  }4849  interface Events {50    /**51     * Single-slot decision for the next {@link FileSystem.writeText}. Calling52     * `next()` yields the bare provider's unconditional write; the first listener53     * that returns an intent owns the decision rather than composing with peers.54     * @param target - the resolved target about to be written.55     * @param actor - the opaque tool-execution context the decider keys off.56     * @mode waterfall57     */58    'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>59    /**60     * Single-slot decision for the next {@link FileSystem.editText}. Calling61     * `next()` yields an unconditional edit; the first returned guard wins.62     * @param target - the resolved target about to be edited.63     * @param actor - the opaque tool-execution context the decider keys off.64     * @mode waterfall65     */66    'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>67    /**68     * Record an authoritative positive or negative observation. Listeners must69     * be synchronous recorders: throws fail the tool call and returned promises70     * are not awaited.71     * @param target - the target whose presence or absence was observed.72     * @param observation - present with its version, or confirmed absent.73     * @param actor - the observing tool-execution context; undefined records nothing useful.74     * @mode emit75     */76    'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void77  }78}

52export type FsObservation =53  | { readonly kind: 'present'; readonly version: FsVersion }54  | { readonly kind: 'absent' }

106export function apply(ctx: Context): void {107  const gate = new ObservedStateGate()108109  ctx.effect(() => () => {110    // Drop all recorded state on disposal so a reloaded plugin starts clean111    // (HMR safety). The WeakMap itself would be GC'd, but replacing it makes the112    // release observable and immediate for tests.113    gate.clear()114  }, 'fs-observation-policy observed-state teardown')115116  // fs/write-intent: occupy the single decision slot — do NOT call next().117  // Deferred through Promise.resolve().then so the declared Promise return type118  // holds (a throw rejects, never escapes synchronously through the waterfall).119  ctx.on('fs/write-intent', (target, actor) => Promise.resolve().then(() => gate.writeIntent(target, actor)))120121  // fs/edit-intent: occupy the single decision slot — do not call next().122  ctx.on('fs/edit-intent', (target, actor) => Promise.resolve().then(() => gate.editIntent(target, actor)))123124  // fs/observed must remain synchronous and non-throwing: emit does not await125  // promises, and successful mutations have already committed. WeakMap.set126  // satisfies that contract for both presence and absence.127  ctx.on('fs/observed', (target, observation, actor) => {128    gate.observe(target, observation, actor)129  })130}

249  if (await ctx.fs.stat(target, exec.signal) !== undefined) {250    throw new Error(`File already exists at: ${target.displayPath}. Cannot overwrite files using command \`create\`.`)251  }252  const intent = await ctx.waterfall(253    'fs/write-intent',254    target,255    exec,256    () => ({ kind: 'createIfAbsent' } as const),257  )

126  private async checkedTarget(target: FsTarget, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsTarget> {127    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve()128    const { mode } = policy129    if (mode === 'danger-full-access') return target130    if (mode === 'read-only') {131      throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, 'FS_SANDBOX_DENIED')132    }133    // workspace-write: containment on the FRESH canonical path (catches a134    // symlink ancestor swapped since the tool resolved this target), and the135    // mutation delegates with THIS fresh target — never the stale one.136    const fresh = await this.resolve(target.displayPath)137    let contained = false138    for (const root of writableRoots(policy)) {139      if (await isPathUnder(fresh.targetKey, root)) {140        contained = true141        break142      }143    }144    if (!contained) {145      throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, 'FS_SANDBOX_DENIED')146    }147    return fresh148  }

43  constructor(private readonly ctx: Context) {44    const defaultMode = ctx.fs.sandboxMode45    this.escalationModes = defaultMode === undefined ? [] : ESCALATION_TARGETS46    this.policy = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy')47    if (defaultMode !== undefined && this.policy === undefined) {48      throw new Error('tool-fs: the mounted filesystem confines but ctx.sandboxPolicy is missing')49    }50  }

9[The split-fs-seam Agent Note](../simplification/2026-06-26-fsspec-style-fs-seam.md) put `ctx.fileContext` between the model-facing tools and the `ctx.fs` provider: `dsh-tool-fs` injects `fileContext` and routes every `read`/`write`/`edit` through its methods. That makes `fileContext` **in-path and mandatory**. The tool cannot reach `ctx.fs` without it, the policy layer owns the fs I/O and the read windowing, and a deployment that does not want observed-state policy cannot simply drop the package — `dsh-tool-fs` would fail to resolve `ctx.fileContext`.

21Invert the control flow. **`dsh-tool-fs` becomes the executor and calls `ctx.fs` directly**; **`dsh-fs-observation-policy` becomes a gate + recorder plugin** that participates through events, never through a method the tool calls and never by registering a `ctx.fileContext` service.

34The model is additive: bare `ctx.fs` performs atomic, unconstrained text I/O, while `dsh-fs-observation-policy` adds observed state, read-before-edit, and version guards. Removing the policy therefore leaves the tools usable but unconstrained. Shipped agent configs load the policy; the bare mode exists to keep policy optional at the service boundary, not as the normal deployment stance.

111The `fs/*` decision events are **unbound waterfalls dispatched by the tool** (like `agent/request`, which the loop dispatches with no `this`), not service-bound waterfalls (like `llm/stream`). The dispatcher is the `dsh-tool-fs` plugin, which is not a service.

13| `fs-observation-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |

42`dsh-fs-observation-policy` enforces "you must write/edit based on the version you read" **without ever calling `stat` or comparing versions itself**. It supplies the observed version as the CAS basis and lets the provider's mutation critical section detect staleness:4344- "What did this owner last observe?" is the one thing `dsh-fs-observation-policy` decides locally — a `WeakMap` lookup, no I/O. No record means unseen; an absent record permits only guarded creation; a present record carries the replacement/edit basis.45- "Is the version still current, or is the create target still absent?" is decided **inside the provider's atomic mutation boundary**. `dsh-fs-observation-policy` supplies `replaceIfVersion` or `createIfAbsent`; the provider raises `FS_STALE_VERSION` for a moved version and `FS_NOT_OBSERVED` when a guarded create loses to another creator.4647This is deliberate. If `dsh-fs-observation-policy` stat-ed and compared versions in its waterfall handler, there would be a TOCTOU gap between that check and the tool's actual write — the file could change in between, so the check would be a false guarantee that the provider's lock has to back up anyway. Putting the version check in the provider's critical section is both race-free and zero extra `stat`. So `dsh-fs-observation-policy` does **no** filesystem I/O; the "must be based on the latest read" guarantee is *realized* by CAS, and `dsh-fs-observation-policy` only chooses the basis (`vObserved`) and gates on prior observation.

185`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event carrying an `FsObservation`: present at a version or confirmed absent. It is dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener can replace a read error or surface as the tool's `isError` result after a mutation already succeeded. The generated [cordis surface](#cordis-surface) below shows the exact signatures.

119| Add filesystem access or policy | register a `ctx.fs` provider or listen to `fs/*` events |

1/**2 * Host-filesystem implementation of `ctx.fs`. Realpath-derived target identity makes aliases3 * share stale guards, and writes through a symlink update its target without replacing the link.4 * @module @deepseek-ai/dsh-fs-local5 */

660- Fixed single-segment `dir/**` allow rules like `Edit(src/**)` auto-approving writes to nested `dir/` directories anywhere in the tree instead of only `<cwd>/dir`

1574- Fixed Windows permission rules never matching when spelled with backslashes (`~\`, `\\server\share`) or case-variant paths, and Read deny rules not hiding files from Glob/Grep results

1557- Fixed deny rules on home-directory paths (e.g. `Read(~/Desktop/**)`) not blocking Bash commands that reference the path via `$HOME`

27- The `sandbox` property only applies to the `Bash` tool; it does not apply to other tools (like Read, Write, WebSearch, WebFetch, MCPs), hooks, or internal commands

364- Changed the Write tool so newer models can overwrite an existing file they haven't read this session, matching the Edit tool's rules; older models still require the read first