deepseek-coordination 0.1.2 → 0.1.5

package/src/plugin/settings.js

@@ -0,0 +1,340 @@
+/**
+ * dsh-os settings service: the state the settings panel edits and the takeover reads.
+ *
+ * WHY THIS EXISTS AS A SERVICE RATHER THAN A CLOSURE IN takeover.js
+ *
+ * The switch has to be readable by the interception on every tool call, writable by the HTTP routes the
+ * browser panel talks to, and visible to both without either one owning the other. A Cordis service is
+ * how that is expressed in this runtime: `takeover.js` injects `dsh-os-settings` and calls `enabled()`
+ * on each call, and the routes mutate the same object.
+ *
+ * WHY THE STATE IS A FILE AND NOT THE PROFILE
+ *
+ * A toggle a user flips in a panel must survive a restart, and `cordis.patch.yml` is a deployment input
+ * rather than runtime state: writing it from a plugin would make the profile's patch layer — the layer
+ * a human reviews — change underneath them. The state therefore lives in its own JSON document.
+ *
+ * LOCATION. `DSH_HOME` is preferred over the package root when it is set, because the package directory
+ * is the installed artifact: it is replaced wholesale on upgrade, it may be read-only, and on Windows it
+ * commonly sits under a path that an installer owns. A setting that only survives until the next upgrade
+ * is worse than no setting. The package root remains the fallback so a checkout works with no
+ * environment at all.
+ *
+ * FAILURE POLICY. A settings file that cannot be read is treated as absent and the documented defaults
+ * are used; a settings file that cannot be written fails the HTTP call with a readable reason. Neither
+ * case may take the host down: the whole point of the feature is that it is optional.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { dirname, join } from 'node:path'
+
+import { PKG_ROOT } from './invoke.js'
+import { TAKEOVER_TOOLS } from './takeover.js'
+
+/** Service name other plugins inject. */
+export const SERVICE_NAME = 'dsh-os-settings'
+
+/** How many recent activity entries the panel can show. */
+const ACTIVITY_LIMIT = 50
+
+/** The shape of every boolean this service stores, so a hand-edited file cannot invert a default. */
+function asBoolean(value, fallback) {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/** Normalise an arbitrary parsed document into the settings shape, keeping only known keys. */
+export function normalizeSettings(raw) {
+  const source = raw !== null && typeof raw === 'object' ? raw : {}
+  const tools = source.tools !== null && typeof source.tools === 'object' ? source.tools : {}
+  const normalizedTools = {}
+  for (const tool of TAKEOVER_TOOLS) {
+    normalizedTools[tool] = asBoolean(tools[tool], true)
+  }
+  return {
+    version: 1,
+    // The master switch.
+
+    enabled: asBoolean(source.enabled, false),
+    tools: normalizedTools,
+    // 'target' preserves the target file's BOM and line endings; 'builtin' reproduces the built-in
+    // UTF-8-without-BOM, LF behaviour exactly. 'target' is the default because it is the reason the
+    // takeover exists.
+    writeFormat: source.writeFormat === 'builtin' ? 'builtin' : 'target',
+  }
+}
+
+/** Where the settings document lives, with the reason each candidate is in the order it is in. */
+export function settingsPath(env = process.env) {
+  const home = env.DSH_HOME
+  if (typeof home === 'string' && home.trim() !== '') return join(home, 'dsh-os', 'settings.json')
+  return join(PKG_ROOT, '.dsh-os-settings.json')
+}
+
+/** Read the document, or the defaults. Never throws: an unreadable file is an absent one. */
+export function readSettings(file) {
+  try {
+    if (!existsSync(file)) return normalizeSettings(undefined)
+    const raw = readFileSync(file, 'utf8')
+    if (raw.trim() === '') return normalizeSettings(undefined)
+    return normalizeSettings(JSON.parse(raw))
+  } catch {
+    return normalizeSettings(undefined)
+  }
+}
+
+/**
+ * Write the document atomically: sibling temporary file, then rename.
+ *
+ * A panel toggle and a tool call can overlap, and a half-written settings file would be read as
+ * "defaults" on the next start — silently disabling a feature the user turned on. Rename is atomic on
+ * the same filesystem, and the temporary file is a sibling by construction.
+ */
+export function writeSettings(file, settings) {
+  mkdirSync(dirname(file), { recursive: true })
+  const temporary = `${file}.${randomBytes(6).toString('hex')}.tmp`
+  try {
+    writeFileSync(temporary, `${JSON.stringify(settings, null, 2)}\n`, 'utf8')
+    renameSync(temporary, file)
+  } catch (error) {
+    try { rmSync(temporary, { force: true }) } catch { /* the original failure is the one that matters */ }
+    throw error
+  }
+}
+
+/**
+ * The live settings object, registered as a Cordis service.
+ *
+ * `record`/`recordFallback` exist so the panel can show what actually happened rather than only what is
+ * configured: "takeover is on" and "takeover is answering calls" are different claims, and only the
+ * second one is evidence that the feature works.
+ */
+export class SettingsService {
+  constructor(ctx, config = {}) {
+    this.ctx = ctx
+    this.file = config.settingsPath ?? settingsPath()
+    this.settings = readSettings(this.file)
+    this.activity = []
+    this.listeners = new Set()
+  }
+
+  /** The whole document, as the panel renders it. */
+  current() {
+    return {
+      ...this.settings,
+      path: this.file,
+      tools: { ...this.settings.tools },
+      activity: [...this.activity],
+    }
+  }
+
+  /** Whether takeover is answering calls at all: the master switch. */
+  enabled() {
+    return this.settings.enabled === true
+  }
+
+  /** Whether one tool is taken over. Meaningless while the master switch is off, and reported as such. */
+  toolEnabled(tool) {
+    if (!this.settings.enabled) return false
+    return this.settings.tools?.[tool] === true
+  }
+
+  /**
+   * How a redirected write should encode its bytes: `'target'` preserves the file's own BOM and line
+   * endings, `'builtin'` reproduces the built-in UTF-8-without-BOM, LF behaviour exactly.
+   */
+  writeFormat() {
+    return this.settings.writeFormat === 'builtin' ? 'builtin' : 'target'
+  }
+
+  /** Apply a partial update, persist it, and tell the panel. Returns the new document. */
+  update(patch) {
+    const next = normalizeSettings({ ...this.settings, ...patch, tools: { ...this.settings.tools, ...(patch.tools ?? {}) } })
+    writeSettings(this.file, next)
+    this.settings = next
+    this.emit()
+    return this.current()
+  }
+
+  /**
+   * Record one intercepted call.
+   *
+   * Bounded and in-memory on purpose: this is a live activity feed for a panel, not an audit log. The
+   * durable trail is `permission.json`'s audit array, written by the consent delegate.
+   */
+  record(tool, exec, value) {
+    this.push({
+      at: new Date().toISOString(),
+      tool,
+      outcome: 'taken-over',
+      // The path or command, which is what makes the feed readable at a glance.
+      subject: subjectOf(tool, exec?.arguments),
+      bytes: typeof value?.after === 'string' ? Buffer.byteLength(value.after, 'utf8') : undefined,
+    })
+  }
+
+  /** Record that an interception declined a call and the built-in tool answered it instead. */
+  recordFallback(tool, exec, error) {
+    this.push({
+      at: new Date().toISOString(),
+      tool,
+      outcome: 'fell-back',
+      subject: subjectOf(tool, exec?.arguments),
+      reason: error instanceof Error ? error.message : String(error),
+    })
+  }
+
+  push(entry) {
+    this.activity.push(entry)
+    if (this.activity.length > ACTIVITY_LIMIT) this.activity.splice(0, this.activity.length - ACTIVITY_LIMIT)
+    this.emit()
+  }
+
+  /** Subscribe to changes; returns the unsubscribe function, as `ctx.effect` expects. */
+  subscribe(listener) {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  emit() {
+    for (const listener of this.listeners) {
+      try { listener() } catch { /* a panel listener must not break a tool call */ }
+    }
+  }
+}
+
+/** The tool-call subject a human would recognise: the file for file tools, the command for pwsh. */
+function subjectOf(tool, args) {
+  if (args === null || typeof args !== 'object') return ''
+  if (tool === 'pwsh') return typeof args.command === 'string' ? args.command.slice(0, 200) : ''
+  return typeof args.file_path === 'string' ? args.file_path : ''
+}
+
+// ---------------------------------------------------------------------------
+// HTTP surface for the browser panel
+// ---------------------------------------------------------------------------
+
+/** Write one JSON response. Local rather than imported: this package has no runtime dependencies. */
+function writeJson(res, status, value) {
+  const body = JSON.stringify(value)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(body)
+}
+
+/** Read one JSON request body with a ceiling, so a malformed caller cannot grow the heap. */
+function readJsonBody(req, limit = 65536) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('error', reject)
+    req.on('end', () => {
+      const text = Buffer.concat(chunks).toString('utf8').trim()
+      if (text === '') return resolve({})
+      try { resolve(JSON.parse(text)) } catch (error) { reject(new Error(`request body is not JSON: ${error.message}`)) }
+    })
+  })
+}
+
+/**
+ * The panel's three endpoints.
+ *
+ * They are registered through `ctx.webServer`, the same seam the built-in SPA and the other UI plugins
+ * use, so they are reachable at the same origin with no port, token or CORS negotiation.
+ */
+export function makeSettingsRoutes(service) {
+  const state = () => ({ ok: true, settings: service.current(), available: TAKEOVER_TOOLS })
+  return [
+    {
+      kind: 'exact',
+      path: '/api/dsh-os/settings',
+      handler: (req, res) => {
+        if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'method-not-allowed' })
+        writeJson(res, 200, state())
+      },
+    },
+    {
+      kind: 'exact',
+      path: '/api/dsh-os/set',
+      handler: (req, res) => {
+        if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'method-not-allowed' })
+        readJsonBody(req).then((body) => {
+          // Only known keys are forwarded: `update` normalises anyway, but refusing an unknown shape here
+          // means a typo in the panel is a visible error instead of a silent no-op.
+          const patch = {}
+          if (typeof body.enabled === 'boolean') patch.enabled = body.enabled
+          if (body.writeFormat === 'target' || body.writeFormat === 'builtin') patch.writeFormat = body.writeFormat
+          if (body.tools !== null && typeof body.tools === 'object') {
+            patch.tools = {}
+            for (const tool of TAKEOVER_TOOLS) {
+              if (typeof body.tools[tool] === 'boolean') patch.tools[tool] = body.tools[tool]
+            }
+          }
+          if (Object.keys(patch).length === 0) {
+            writeJson(res, 400, { ok: false, error: 'no recognised setting in the request body' })
+            return
+          }
+          try {
+            service.update(patch)
+            writeJson(res, 200, state())
+          } catch (error) {
+            writeJson(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) })
+          }
+        }, (error) => {
+          writeJson(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) })
+        })
+      },
+    },
+  ]
+}
+
+/**
+ * The plugin row for the settings service.
+ *
+ * There is deliberately NO `inject` here, and that is the whole point of this shape.
+ *
+ * An `inject: ['webServer']` on the row would gate the row's activation on a service that a profile may
+ * legitimately never provide — and the settings service is what the TAKEOVER injects, so a profile
+ * without a web server would not merely lose the panel, it would silently lose the interception too.
+ * The panel is an interface; the interception is the feature.
+ *
+ * So the service is provided unconditionally, and the HTTP routes are registered through `ctx.inject`,
+ * which runs its callback when (and only when) `webServer` is available and unwinds it if it goes away.
+ * A headless deployment therefore keeps a working takeover with no endpoints, and a Web one gets both.
+ */
+export const name = 'dsh-os-settings'
+
+export function apply(ctx, config = {}) {
+  const service = new SettingsService(ctx, config)
+
+  // `ctx.provide` REGISTERS the service and returns a disposer; `ctx.set` only overwrites the value of a
+  // service that was already provided, and calling it first throws
+  //   Error: cannot set property "dsh-os-settings" without provide
+  // which would abort the whole entry. Same trap the consent delegate documents.
+  const disposeService = ctx.provide?.(SERVICE_NAME, service)
+  void disposeService
+
+  // A context without the injection API (the unit tests' stand-in) simply gets no routes, which is
+  // honest rather than half-registered.
+  if (typeof ctx.inject !== 'function') return
+
+  ctx.inject(['webServer'], (scoped) => {
+    scoped.effect(() => {
+      const disposers = makeSettingsRoutes(service).map((route) => scoped.webServer.register(route))
+      return () => {
+        for (const dispose of disposers) dispose()
+      }
+    }, 'dsh-os-settings: routes')
+  })
+}
+
+/** Exported for tests. */
+export const __internals = { normalizeSettings, writeJson, readJsonBody, subjectOf, ACTIVITY_LIMIT }

package/src/plugin/takeover.js

@@ -54,7 +54,7 @@
  */
 
 import { randomBytes } from 'node:crypto'
-import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { basename, dirname, isAbsolute, join } from 'node:path'
 
 import { invokeForResult, resolveInvocation } from './invoke.js'
@@ -157,25 +157,9 @@ export function writeFileAtomic(path, bytes) {
 // per-tool handlers
 // ---------------------------------------------------------------------------
 
-/** Split an `output.text` slice into the `{ number, text }` records the built-in `read` reports. */
-function windowFromSlice(sliceText, offset, totalLines) {
-  const all = sliceText.split('\n')
-  // dsh-os splits on LF and a file ending in a newline therefore yields a final empty element. The
-  // built-in `read` does not report that trailing element as a line, so it is dropped here rather than
-  // inflating totalLines by one.
-  if (all.length > 0 && all[all.length - 1] === '') all.pop()
-  const lines = []
-  for (let index = 0; index < all.length; index += 1) {
-    const number = offset + index
-    if (number > totalLines) break
-    lines.push({ number, text: all[index] })
-  }
-  return lines
-}
-
 /** Run `file view` and return its envelope result. */
-async function viewFile(invocation, path, flags = []) {
-  return invokeForResult(invocation, 'file view', [path], flags)
+async function viewFile(invoke, invocation, path, flags = []) {
+  return invoke(invocation, 'file view', [path], flags)
 }
 
 /**
@@ -184,23 +168,35 @@ async function viewFile(invocation, path, flags = []) {
  * The value must satisfy the built-in schema exactly (`path`, `offset`, `lines[{number,text}]`,
  * `totalLines`, additionalProperties false), because that value is what the built-in renderer formats
  * and what the built-in presentation metadata is derived from.
+ *
+ * `lines` and `lineCount` are read from the envelope rather than derived from `text`. That is not a
+ * style choice: `file view` builds its line objects BEFORE applying `--max-bytes` (file.ps1:387-419),
+ * so `lineCount` is the file's real line count while `text` is a truncated slice of it. Deriving
+ * `totalLines` from `text` would silently under-report every file larger than the flag's cap, and the
+ * built-in renderer uses `totalLines` to decide whether to print the "use offset to continue" footer.
  */
-async function handleRead(args, invocation) {
+async function handleRead(args, invocation, readLimit, invoke = invokeForResult) {
   const path = String(args.file_path)
   const offset = Number.isInteger(args.offset) && args.offset > 0 ? args.offset : 1
-  const limit = Number.isInteger(args.limit) && args.limit > 0 ? args.limit : 2000
+  // The built-in default comes from the `tool-fs` row's `readLimit` config (2000), so it is carried in
+  // rather than hardcoded: a deployment that raised it must not see a different window size here.
+  const limit = Number.isInteger(args.limit) && args.limit > 0 ? Math.min(args.limit, readLimit) : readLimit
 
-  const view = await viewFile(invocation, path)
-  // `lineCount` counts the trailing empty element the same way `split` does, so the reported total is
-  // taken from the slice arithmetic instead: the verb's own text is authoritative.
-  const text = String(view.text ?? '')
-  const endsWithNewline = text.endsWith('\n')
-  const allLines = text.split('\n')
-  if (endsWithNewline) allLines.pop()
-  const totalLines = allLines.length
+  const view = await viewFile(invoke, invocation, path)
+  const totalLines = Number.isInteger(view.lineCount) ? view.lineCount : 0
 
-  const selected = allLines.slice(offset - 1, offset - 1 + limit)
-  const lines = selected.map((lineText, index) => ({ number: offset + index, text: lineText }))
+  // The built-in tool treats an offset past the end of a non-empty file as an error rather than an
+  // empty read, so a caller that asked for line 900 of a 10-line file is told, not handed nothing.
+  if (totalLines > 0 && offset > totalLines) {
+    throw new Error(`offset ${offset} is out of range for ${path}, which has ${totalLines} line(s)`)
+  }
+
+  const all = Array.isArray(view.lines) ? view.lines : []
+  const lines = []
+  for (const line of all) {
+    if (line.number < offset || line.number > offset + limit - 1) continue
+    lines.push({ number: line.number, text: String(line.text ?? '') })
+  }
 
   return { path: view.path ?? path, offset, lines, totalLines }
 }
@@ -209,24 +205,36 @@ async function handleRead(args, invocation) {
  * Answer a built-in `write` call.
  *
  * `before` and `after` are the decoded text, matching what the built-in `read` reports for the same
- * file, while the bytes actually landing on disk keep the target's original BOM and line endings. That
- * split is deliberate: the values are compared by the model and diffed by the UI (both of which work in
- * normalised text), and only the byte-level write needs the file's convention.
+ * file, while the bytes actually landing on disk follow `writeFormat`:
+ *
+ *   * `'target'` (the default) keeps the target's original BOM and line endings, which is the reason the
+ *     takeover exists: rewriting a CRLF or BOM file as plain LF+UTF-8 produces a whole-file diff and can
+ *     break whatever depended on the convention;
+ *   * `'builtin'` reproduces the built-in tool exactly — UTF-8 without a BOM, LF — for a caller who wants
+ *     takeover to change where the bytes came from and nothing else.
+ *
+ * The split between value and bytes is deliberate: the values are compared by the model and diffed by
+ * the UI, both of which work in normalised text, and only the byte-level write needs the convention.
  */
-async function handleWrite(args, invocation) {
+async function handleWrite(args, invocation, writeFormat = 'target', invoke = invokeForResult) {
   const path = String(args.file_path)
   const content = String(args.content ?? '')
 
-  const before = existsSync(path) ? decodeTextFile(readFileSync(path)) : null
-  const format = readTargetFormat(path)
-
-  writeFileAtomic(path, encodeTextForTarget(content, format))
-
-  // The verb is still consulted for the write itself only when the target did not exist: `file create`
-  // refuses to overwrite by contract, so an existing target is replaced here. A new target goes through
-  // the verb, which is where the parent-directory creation and the protected-path check live.
-  if (before === null) {
-    const created = await invokeForResult(invocation, 'file create', [path, content, format.bom ? 'utf-8-bom' : 'utf-8'], [], { allow: true })
+  // A target that does not exist yet goes through `file create`, which is where parent-directory
+  // creation and the protected-path check live. The order matters: an earlier version wrote the file
+  // first and only then called the verb, which made both of those guarantees unreachable — the write
+  // had already succeeded (or already failed on a missing parent) before the verb ever ran.
+  //
+  // A new file is always UTF-8 without a BOM and LF, under either write format: there is no target
+  // convention to preserve, so the built-in behaviour is the only defensible answer.
+  if (!existsSync(path)) {
+    const created = await invoke(
+      invocation,
+      'file create',
+      [path, content, 'utf-8'],
+      [],
+      { allow: true },
+    )
     return {
       path: created.path ?? path,
       operation: 'create',
@@ -235,6 +243,15 @@ async function handleWrite(args, invocation) {
     }
   }
 
+  const before = decodeTextFile(readFileSync(path))
+  const format = writeFormat === 'builtin' ? { bom: false, eol: 'lf' } : readTargetFormat(path)
+
+  // The existing target is replaced here because `file create` refuses to overwrite by contract
+  // (`E_EXISTS`), and no verb performs a whole-file replacement. The bytes still go through dsh-os's
+  // encoding rules — `readTargetFormat` reads the BOM and line-ending convention off the target and
+  // `encodeTextForTarget` re-applies them — which is the behaviour this takeover exists to provide.
+  writeFileAtomic(path, encodeTextForTarget(content, format))
+
   return {
     path,
     operation: 'update',
@@ -251,17 +268,23 @@ async function handleWrite(args, invocation) {
  * built-in contract: one match is required unless `replace_all` is set, and a violation throws so the
  * caller falls back to the built-in tool rather than inventing a different answer.
  */
-async function handleEdit(args, invocation) {
+async function handleEdit(args, invocation, writeFormat = 'target', invoke = invokeForResult) {
   const path = String(args.file_path)
   const oldString = String(args.old_string ?? '')
   const newString = String(args.new_string ?? '')
   const replaceAll = args.replace_all === true
 
+  // An edit never creates, so the verb layer is not consulted; the injectable invoker is accepted for
+  // symmetry with the other handlers and so a test can pin that no verb is reached on this path.
+  void invoke
+  void invocation
+
   if (oldString === '') throw new Error('old_string must be a non-empty string')
   if (oldString === newString) throw new Error('old_string and new_string must differ')
 
-  const format = readTargetFormat(path)
-  if (!format.exists) throw new Error(`cannot edit '${path}': it does not exist`)
+  const target = readTargetFormat(path)
+  if (!target.exists) throw new Error(`cannot edit '${path}': it does not exist`)
+  const format = writeFormat === 'builtin' ? { bom: false, eol: 'lf' } : target
   const before = decodeTextFile(readFileSync(path))
 
   const occurrences = before.split(oldString).length - 1
@@ -286,8 +309,18 @@ async function handleEdit(args, invocation) {
  * `kind: "foreground"`, both stream objects with their `truncated` flags, and the null-able
  * `exitCode`/`signal` pair.
  *
- * `signal` is always null: dsh-os reports a numeric exit status and does not surface the terminating
- * signal separately, and inventing a value there would be a claim the envelope does not support.
+ * Two fields are necessarily constant here, and both are honest rather than lazy:
+ *
+ *   * `signal` is always null. An envelope carries a numeric exit status and no terminating-signal
+ *     field, so the built-in `[killed by signal: X]` marker is unreachable through this path.
+ *   * `truncated` is always false. The `execute.command` result carries the whole stdout string with no
+ *     cap and no spill path, so there is nothing to report as truncated. The built-in tool's own
+ *     `[output truncated; full output: …]` marker is therefore also unreachable here — which is a real
+ *     loss for a command that prints megabytes, not a cosmetic one.
+ *
+ * `timedOut` IS reachable: a deadline that expires returns an envelope with `timedOut: true` and a null
+ * exit code rather than throwing (execute.ps1), so the built-in `[timed out after Nms]` marker is
+ * preserved.
  */
 async function handlePwsh(args, invocation, timeoutMs) {
   const command = String(args.command ?? '')
@@ -302,9 +335,6 @@ async function handlePwsh(args, invocation, timeoutMs) {
 
   const result = await invokeForResult(invocation, 'execute.command', ['pwsh', '-NoLogo', '-NoProfile', '-Command', command], flags, { allow: true, timeoutMs: requestedTimeout + 5000 })
 
-  const stdoutText = String(result.stdout ?? '')
-  const stderrText = String(result.stderr ?? '')
-
   return {
     kind: 'foreground',
     exitCode: Number.isInteger(result.exitCode) ? result.exitCode : null,
@@ -312,8 +342,8 @@ async function handlePwsh(args, invocation, timeoutMs) {
     timedOut: result.timedOut === true,
     aborted: false,
     timeoutMs: Math.round(requestedTimeout),
-    stdout: { text: stdoutText, truncated: result.stdoutTruncated === true },
-    stderr: { text: stderrText, truncated: result.stderrTruncated === true },
+    stdout: { text: String(result.stdout ?? ''), truncated: false },
+    stderr: { text: String(result.stderr ?? ''), truncated: false },
   }
 }
 
@@ -341,10 +371,17 @@ function eligible(tool, args) {
     case 'edit':
       return forwardablePath(args.file_path)
     case 'pwsh':
-      // A background call's result is a harness job id, and this surface cannot produce one. The
-      // session-scoped sandbox escalation arguments are likewise the harness's own seam.
+      // A background call's result is a harness job id, and this surface cannot produce one: the verb
+      // rejects `--background` outright. The session-scoped sandbox escalation arguments are likewise
+      // the harness's own seam and are not consulted here.
       if (args.run_in_background === true) return false
       if (args.sandbox_permissions !== undefined) return false
+      // A relative workdir is resolved by the built-in tool against the session's working directory, and
+      // this plugin has no equivalent of that resolution. It is NOT because the verb would resolve it
+      // wrongly: `execute.command` sets the spawned process's working directory explicitly
+      // (execute.ps1 `$psi.WorkingDirectory`), so an absolute path behaves identically either way. The
+      // gap is only in resolving a relative one, so only a relative one keeps the built-in path.
+      if (args.workdir !== undefined && !forwardablePath(args.workdir)) return false
       return typeof args.command === 'string' && args.command.trim() !== ''
     default:
       return false
@@ -353,6 +390,9 @@ function eligible(tool, args) {
 
 export function apply(ctx, config = {}) {
   const toolTimeoutMs = config.timeoutMs ?? 120000
+  // Mirrors the `tool-fs` row's `readLimit` (2000 by default): the interception must not quietly apply
+  // a different window size than the built-in it replaced.
+  const readLimit = Number.isInteger(config.readLimit) && config.readLimit > 0 ? config.readLimit : 2000
 
   ctx.on('tools/execute', async (exec, next) => {
     const settings = ctx['dsh-os-settings']
@@ -370,9 +410,9 @@ export function apply(ctx, config = {}) {
 
     try {
       let value
-      if (tool === 'read') value = await handleRead(args, invocation)
-      else if (tool === 'write') value = await handleWrite(args, invocation)
-      else if (tool === 'edit') value = await handleEdit(args, invocation)
+      if (tool === 'read') value = await handleRead(args, invocation, readLimit)
+      else if (tool === 'write') value = await handleWrite(args, invocation, settings.writeFormat())
+      else if (tool === 'edit') value = await handleEdit(args, invocation, settings.writeFormat())
       else value = await handlePwsh(args, invocation, toolTimeoutMs)
 
       settings.record(tool, exec, value)
@@ -388,5 +428,5 @@ export function apply(ctx, config = {}) {
   })
 }
 
-/** Exported for tests: the mapping from built-in arguments onto dsh-os argv. */
-export const __internals = { eligible, handleRead, handleWrite, handleEdit, handlePwsh, windowFromSlice, statSync }
+/** Exported for tests: the eligibility rule and the per-tool handlers. */
+export const __internals = { eligible, handleRead, handleWrite, handleEdit, handlePwsh }