@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/tools/file-tools.js

@@ -1,553 +0,0 @@
-/**
- * file-tools - Pugi CLI file/bash/glob/grep tool surface.
- *
- * Workspace-binding contract (CEO red-alert follow-up):
- *
- *  Every tool dispatch path threads `ctx.root` from the operator's
- *  `process.cwd()` through `EngineTask.workspaceRoot` ->
- *  `native-pugi.run()` -> `toolCtx.root` -> here. Tools call
- *  `resolveWorkspacePath(ctx.root, path)` for every on-disk operation
- *  so a dispatched specialist (e.g. Hiroshi writing tic-tac-toe HTML)
- *  produces files in the OPERATOR'S cwd, never in a server-side temp
- *  space. The path-security gate refuses traversal (`../etc/passwd`,
- *  URL-encoded variants, symlink escapes at the target).
- *
- *  Wiring chain:
- *    1. runtime/cli.ts:   workspaceRoot = process.cwd()
- *    2. EngineTask.workspaceRoot threads through to native-pugi.run().
- *    3. native-pugi:      const root = task.workspaceRoot
- *    4. tool-bridge:      passes ctx.root to file-tools / bash.
- *    5. file-tools:       resolveWorkspacePath(ctx.root, path).
- *
- *  The contract is locked by `test/tools-write-to-workspace.spec.ts`
- *  (6 cases covering relative + nested + absolute paths + traversal
- *  refusal). If any layer of the chain regressed silently, dispatched
- *  files would land in `/tmp` instead of the operator's repo, which
- *  is the same failure surface as the menu-mode anti-pattern the
- *  sibling commits close.
- */
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, relative } from 'node:path';
-import { globSync } from 'node:fs';
-import { decidePermission } from '../core/permission.js';
-import { StaleReadError, createReadRecord, hashContent, } from '../core/file-cache.js';
-import { resolveWorkspacePath } from '../core/path-security.js';
-import { scanForInjection, summarizeFindings } from '../core/security/injection-scanner.js';
-import { recordFileMutation, recordToolCall, recordToolResult } from '../core/session.js';
-/**
- * WriteGate marker — thrown by `gateOnCancellation` when the
- * caller supplied a cancellation token that has already aborted. The
- * tool dispatch loop in `tool-bridge.ts` recognises the name and folds
- * the throw into a `status: 'aborted'` tool result rather than a hard
- * error so the loop terminates cleanly.
- */
-export class OperatorAbortedError extends Error {
-    constructor(toolName) {
-        super(`operator_aborted: ${toolName} refused — operator cancelled the dispatch.`);
-        this.name = 'OperatorAbortedError';
-    }
-}
-// Re-export StaleReadError so tool-bridge / test consumers can import
-// the typed error from a single file-tools surface alongside
-// OperatorAbortedError. Same shape as the existing OperatorAbortedError
-// re-surface pattern.
-export { StaleReadError } from '../core/file-cache.js';
-/**
- * WriteGate: refuse the tool dispatch when the active
- * cancellation token has aborted. Idempotent (the token's `isAborted`
- * is a getter, no side effects). Returns void on the happy path so the
- * tool can proceed; throws `OperatorAbortedError` when cancelled.
- *
- * The audit trail still gets the call: `recordToolCall` already fired
- * upstream of this guard so the abort + reason are persisted. The
- * matching `recordToolResult` is fired by the caller in its catch
- * block with `status: 'cancelled'` (see existing path for `error`).
- */
-export function gateOnCancellation(ctx, toolName) {
-    if (ctx.cancellation && ctx.cancellation.isAborted) {
-        throw new OperatorAbortedError(toolName);
-    }
-}
-/**
- * Re-check the permission decision against the *resolved* real path so
- * a workspace-local symlink (`alias -> .env`) cannot bypass the protected
- * basename check. The first `decidePermission` call sees only the user
- * input (`alias`); this second call sees the realpath relative to root
- * (`.env`), which `protectedTargetReason` recognises.
- *
- * Returns the resolved absolute path. Throws when the resolved path is
- * gated by anything other than `allow`.
- */
-function permissionGatedResolve(ctx, inputPath, action, toolName) {
-    const resolved = resolveWorkspacePath(ctx.root, inputPath);
-    let realPath;
-    try {
-        realPath = realpathSync.native(resolved);
-    }
-    catch (error) {
-        // For writes to a file that does not yet exist there is no symlink
-        // to follow; fall back to the resolved path so the workspace check
-        // already done in `resolveWorkspacePath` is the only gate.
-        const code = error.code;
-        if (code === 'ENOENT' || code === 'ENOTDIR')
-            return resolved;
-        throw error;
-    }
-    if (realPath === resolved)
-        return resolved;
-    const realRelative = relative(ctx.root, realPath);
-    const realDecision = decidePermission({ tool: toolName, kind: action, target: realRelative }, ctx.settings, ctx.root);
-    if (realDecision.decision !== 'allow') {
-        throw new Error(`Permission ${realDecision.decision} for ${action} ${realRelative} (via symlink ${inputPath}): ${realDecision.reason}`);
-    }
-    return realPath;
-}
-export function readTool(ctx, path) {
-    const toolCallId = recordToolCall(ctx.session, 'read', path);
-    // WriteGate: fail fast on operator cancel BEFORE permission
-    // decision so a half-second post-cancel race never lands the read.
-    if (ctx.cancellation && ctx.cancellation.isAborted) {
-        const reason = 'operator_aborted: read refused';
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        throw new OperatorAbortedError('read');
-    }
-    const decision = decidePermission({ tool: 'read', kind: 'read', target: path }, ctx.settings, ctx.root);
-    if (decision.decision !== 'allow') {
-        const reason = `Permission ${decision.decision} for read ${path}: ${decision.reason}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    let resolved;
-    try {
-        resolved = permissionGatedResolve(ctx, path, 'read', 'read');
-    }
-    catch (error) {
-        const reason = error.message;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw error;
-    }
-    const content = readFileSync(resolved, 'utf8');
-    ctx.readCache.set(createReadRecord(ctx.root, path, content, 'read_tool'));
-    recordToolResult(ctx.session, toolCallId, 'success', `Read ${path}`);
-    return content;
-}
-export function writeTool(ctx, path, content) {
-    const toolCallId = recordToolCall(ctx.session, 'write', path);
-    // WriteGate: refuse the write when the operator has cancelled
-    // the dispatch. The audit log captures the cancellation reason so a
-    // post-mortem can distinguish operator_aborted from settings-deny.
-    if (ctx.cancellation && ctx.cancellation.isAborted) {
-        const reason = 'operator_aborted: write refused';
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        throw new OperatorAbortedError('write');
-    }
-    const decision = decidePermission({ tool: 'write', kind: 'edit', target: path }, ctx.settings, ctx.root);
-    if (decision.decision !== 'allow') {
-        const reason = `Permission ${decision.decision} for write ${path}: ${decision.reason}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    let resolved;
-    try {
-        resolved = permissionGatedResolve(ctx, path, 'edit', 'write');
-    }
-    catch (error) {
-        const reason = error.message;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw error;
-    }
-    const existed = existsSync(resolved);
-    // stale-read gate for writeTool's update-existing path. The
-    // model uses writeTool for two distinct intents:
-    //
-    //  - create-new: path does not exist on disk. There is no prior
-    //    read to validate against; skip the gate. This is the
-    //    intentional escape hatch the leak spec also calls out.
-    //  - overwrite-existing: path exists. Without the gate the model
-    //    could blind-clobber an externally-modified file, losing the
-    //    concurrent change silently. Force the model to re-read first.
-    //
-    // We deliberately apply the SAME stale-validation primitive editTool
-    // uses so the two write surfaces stay symmetric and a future fix to
-    // either one cannot accidentally weaken the other.
-    let before;
-    if (existed) {
-        before = readFileSync(resolved, 'utf8');
-        const currentStat = statSync(resolved);
-        const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
-        if (validation.stale) {
-            const reason = `stale_read: write ${path} refused — ${validation.detail}`;
-            recordToolResult(ctx.session, toolCallId, 'error', reason);
-            throw new StaleReadError(path, validation.reason, validation.detail);
-        }
-    }
-    const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
-    writeFileSync(tmp, content, { encoding: 'utf8', mode: 0o600 });
-    renameSync(tmp, resolved);
-    // Injection scan (ported an external utility,
-    // Apache-2.0). Scan the BODY (never the path — path security is
-    // owned by `path-security.ts`). Findings are SURFACED as an extra
-    // line on the session tool-result, never block the write. Hard-
-    // block requires a separate CEO-signed PR. Failure here must NOT
-    // throw: a buggy scanner cannot rugpull the write that already
-    // landed on disk above.
-    surfaceInjectionWarning(ctx, toolCallId, 'write', path, content);
-    // Refresh the cache with the post-write content so the model can
-    // chain a follow-up read+edit on the same file without an extra
-    // round-trip. Same pattern editTool uses below.
-    ctx.readCache.set(createReadRecord(ctx.root, path, content, 'read_tool'));
-    recordFileMutation(ctx.session, {
-        toolCallId,
-        path,
-        operation: existed ? 'update' : 'create',
-        beforeHash: before ? hashContent(before) : undefined,
-        afterHash: hashContent(content),
-    });
-    recordToolResult(ctx.session, toolCallId, 'success', `${existed ? 'Updated' : 'Created'} ${path}`);
-}
-/**
- * Surface an injection-scan warning on a file write/edit BODY. The
- * scan never blocks — it folds findings into the session as a
- * `tool_result` with status `warn` so an operator (or SOC pipeline
- * tailing `<workspace>/.pugi/events.jsonl`) sees the signal without a
- * mid-dispatch rollback.
- *
- * Wrapped in try/catch so a malformed scanner never crashes the tool
- * loop — the write itself has already landed on disk by the time we
- * call this.
- */
-function surfaceInjectionWarning(ctx, triggeringToolCallId, tool, path, body) {
-    try {
-        const findings = scanForInjection(body);
-        if (findings.length === 0)
-            return;
-        const summary = summarizeFindings(findings);
-        const warnCallId = recordToolCall(ctx.session, 'injection_warning', path);
-        const message = `injection_warning: ${tool} ${path} — ${summary.total} pattern(s) ` +
-            `(score=${summary.score}, kinds=${summary.kinds.join('|')}). ` +
-            `Triggering call: ${triggeringToolCallId}. ` +
-            `Detector: external-injection-patterns. Write was NOT blocked.`;
-        recordToolResult(ctx.session, warnCallId, 'success', message);
-    }
-    catch {
-        // Scanner failure must NEVER throw — the write has already
-        // landed and the tool loop has to continue. Silent no-op
-        // mirrors the audit-trail contract.
-    }
-}
-export function editTool(ctx, path, oldString, newString) {
-    const toolCallId = recordToolCall(ctx.session, 'edit', path);
-    // WriteGate: refuse the edit when the operator has cancelled
-    // the dispatch. Edits are higher-risk than reads — surface the abort
-    // BEFORE we even consult permissions so a cancel-during-tool-loop
-    // never partially mutates the workspace.
-    if (ctx.cancellation && ctx.cancellation.isAborted) {
-        const reason = 'operator_aborted: edit refused';
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        throw new OperatorAbortedError('edit');
-    }
-    const decision = decidePermission({ tool: 'edit', kind: 'edit', target: path }, ctx.settings, ctx.root);
-    if (decision.decision !== 'allow') {
-        const reason = `Permission ${decision.decision} for edit ${path}: ${decision.reason}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    let resolved;
-    try {
-        resolved = permissionGatedResolve(ctx, path, 'edit', 'edit');
-    }
-    catch (error) {
-        const reason = error.message;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw error;
-    }
-    // stale-read gate. Validate the model's read-time view of
-    // the file against the on-disk state BEFORE applying the mutation.
-    // We read disk content once and feed it to the validator so a single
-    // syscall covers both the gate decision AND the oldString/newString
-    // replacement below.
-    const before = readFileSync(resolved, 'utf8');
-    const currentStat = statSync(resolved);
-    const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
-    if (validation.stale) {
-        const reason = `stale_read: edit ${path} refused — ${validation.detail}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new StaleReadError(path, validation.reason, validation.detail);
-    }
-    const currentHash = hashContent(before);
-    const matches = before.split(oldString).length - 1;
-    if (matches === 0) {
-        const reason = `Cannot edit ${path}: oldString not found`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    if (matches > 1) {
-        const reason = `Cannot edit ${path}: oldString is not unique`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    const after = before.replace(oldString, newString);
-    const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
-    writeFileSync(tmp, after, { encoding: 'utf8', mode: 0o600 });
-    renameSync(tmp, resolved);
-    // Injection scan (ported an external utility,
-    // Apache-2.0). We scan the NEW SUBSTRING the model is inserting,
-    // not the full post-edit file — the rest of the file is operator-
-    // owned content that pre-dates this dispatch. False-positive on
-    // legitimate prose that mentions banned phrases is the worst
-    // outcome and the warn-only contract bounds the cost.
-    surfaceInjectionWarning(ctx, toolCallId, 'edit', path, newString);
-    ctx.readCache.set(createReadRecord(ctx.root, path, after, 'read_tool'));
-    recordFileMutation(ctx.session, {
-        toolCallId,
-        path,
-        operation: 'update',
-        beforeHash: currentHash,
-        afterHash: hashContent(after),
-    });
-    recordToolResult(ctx.session, toolCallId, 'success', `Edited ${path}`);
-}
-export function globTool(ctx, pattern) {
-    const toolCallId = recordToolCall(ctx.session, 'glob', pattern);
-    // WriteGate: cancel-aware short-circuit. Glob is read-only but
-    // can be expensive on large trees; respecting the abort here keeps
-    // the tool loop responsive when the operator hits Ctrl+C mid-scan.
-    if (ctx.cancellation && ctx.cancellation.isAborted) {
-        const reason = 'operator_aborted: glob refused';
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        throw new OperatorAbortedError('glob');
-    }
-    // Pugi globs are workspace-scoped. Reject any pattern that could enumerate
-    // outside the workspace:
-    //  1. absolute paths (`/etc/**/*`) — globSync resolves these against `/`
-    //     regardless of `cwd`, so they fan out outside the repo.
-    //  2. `..` as a path SEGMENT (`../*`, `src/../etc`) — parent traversal.
-    //     A substring check would over-reject legitimate names like
-    //     `src/v1..v2/*` so we split on `/` instead.
-    if (isAbsolute(pattern)) {
-        const reason = `Absolute glob patterns are not allowed: ${pattern}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    if (pattern.split('/').some((segment) => segment === '..')) {
-        const reason = `Glob pattern escapes workspace via '..' segment: ${pattern}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    const results = globSync(pattern, {
-        cwd: ctx.root,
-        withFileTypes: false,
-        exclude: ['node_modules/**', 'dist/**', '.git/**', '.pugi/**'],
-    })
-        .map((entry) => String(entry))
-        .slice(0, 500);
-    recordToolResult(ctx.session, toolCallId, 'success', `Glob matched ${results.length} paths`);
-    return results;
-}
-export function grepTool(ctx, query) {
-    const toolCallId = recordToolCall(ctx.session, 'grep', query);
-    // WriteGate: refuse before scanning. Grep walks the whole
-    // workspace and can take seconds on a large repo; check abort first
-    // so a cancel mid-scan returns immediately rather than after the
-    // full walk completes.
-    if (ctx.cancellation && ctx.cancellation.isAborted) {
-        const reason = 'operator_aborted: grep refused';
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        throw new OperatorAbortedError('grep');
-    }
-    const files = globTool(ctx, '**/*').filter((path) => !path.endsWith('/'));
-    const matches = [];
-    for (const path of files) {
-        if (matches.length >= 200)
-            break;
-        // WriteGate: poll abort inside the file loop so a cancel
-        // arriving mid-scan terminates early. The per-file branch keeps
-        // the responsiveness bounded by the slowest single-file read.
-        if (ctx.cancellation && ctx.cancellation.isAborted) {
-            const reason = `operator_aborted: grep stopped mid-scan after ${matches.length} matches`;
-            recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-            throw new OperatorAbortedError('grep');
-        }
-        // Permission gate every file read individually — grep used to bypass
-        // `decidePermission` and could surface lines from protected files
-        // (.env, *.sql, *.pem, ~/.ssh/**) when invoked from a directory walk.
-        const decision = decidePermission({ tool: 'grep', kind: 'read', target: path }, ctx.settings, ctx.root);
-        if (decision.decision !== 'allow')
-            continue;
-        let fullPath;
-        try {
-            // `permissionGatedResolve` follows symlinks and re-checks the
-            // realpath against the permission rules. Without this an attacker
-            // could plant `alias -> .env` inside the workspace and recover
-            // secrets through `pugi explain .` because the initial decision
-            // only saw the unprotected basename `alias`.
-            fullPath = permissionGatedResolve(ctx, path, 'read', 'grep');
-        }
-        catch {
-            continue;
-        }
-        if (dirname(fullPath).includes('node_modules'))
-            continue;
-        try {
-            const lines = readFileSync(fullPath, 'utf8').split('\n');
-            lines.forEach((text, index) => {
-                if (matches.length < 200 && text.includes(query)) {
-                    matches.push({ path: relative(ctx.root, fullPath), line: index + 1, text });
-                }
-            });
-        }
-        catch {
-            // Binary or unreadable files are ignored by the scaffolded grep tool.
-        }
-    }
-    recordToolResult(ctx.session, toolCallId, 'success', `Grep matched ${matches.length} lines`);
-    return matches;
-}
-/**
- * Workspace-scoped bash tool. Sized for the M1 engine adapter:
- *  - Runs through `/bin/sh -c <command>` so the model can use pipes,
- *    redirection, and shell builtins (`ls | wc -l`, `git status`).
- *  - `cwd` is pinned to the workspace root so a stray `cd /` cannot
- *    leak commands outside the repo (the child process inherits root
- *    filesystem visibility — destructive patterns are blocked by
- *    `decidePermission`, not by chroot).
- *  - Output capped at 64KB combined stdout/stderr to keep the
- *    transcript bounded; the model gets the head + a `(...truncated)`
- *    marker if the cap fires.
- *  - 30s wall-clock timeout. The engine loop's per-tool error path
- *    surfaces the timeout to the model so it can retry with a narrower
- *    command or give up.
- *
- * Permission gating: `kind: 'bash'`. The CLI's permission module already
- * hard-denies the destructive-patterns list (rm -rf /, DROP DATABASE,
- * etc) regardless of mode. Plan-mode callers MUST gate the bash tool
- * out before it reaches the registry — `engine-tools.ts` does this.
- */
-export const BASH_OUTPUT_CAP = 64 * 1024;
-export const BASH_DEFAULT_TIMEOUT_MS = 30_000;
-// Child-process stdio buffer — large enough that the model-facing
-// truncation cap (`BASH_OUTPUT_CAP`) is always the gate, never the
-// child's internal buffer. Code Reviewer P2 retro flagged
-// `BASH_OUTPUT_CAP * 2` as too tight: real builds (`pnpm build`,
-// `tsc --noEmit`) routinely exceed 128 KB combined and the model
-// then saw a fatal `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` instead of a
-// graceful `(...truncated at N bytes)` tail.
-export const BASH_CHILD_MAXBUFFER = 10 * 1024 * 1024;
-export function bashTool(ctx, command, options = {}) {
-    const toolCallId = recordToolCall(ctx.session, 'bash', command);
-    // WriteGate: bash is the highest-risk tool surface. Refuse
-    // before the destructive-pattern classifier even runs so a
-    // cancelled dispatch never spawns a child process. Note: this is
-    // pre-spawn cancellation only; once the /bin/sh -c process is
-    // running, the synchronous spawnSync wait blocks until it exits or
-    // the 30s timeout fires. Phase 2 will wire SIGTERM forwarding via
-    // an async wrapper.
-    if (ctx.cancellation && ctx.cancellation.isAborted) {
-        const reason = 'operator_aborted: bash refused';
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        throw new OperatorAbortedError('bash');
-    }
-    const decision = decidePermission({ tool: 'bash', kind: 'bash', target: command }, ctx.settings, ctx.root);
-    if (decision.decision !== 'allow') {
-        const reason = `Permission ${decision.decision} for bash: ${decision.reason}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    // `/bin/sh -c` is portable enough for the M1 alpha; downstream
-    // operators on hosts without /bin/sh can override via $SHELL, but
-    // that is an explicit opt-in for now.
-    //
-    // Env sanitisation strategy: build the child env from an explicit
-    // allow-list rather than inheriting `process.env` and trying to
-    // strip secrets after the fact. Code Reviewer P1 flagged
-    // that the deny-list approach missed ANTHROPIC_API_KEY / GH_TOKEN
-    // / AWS_SECRET_ACCESS_KEY / DATABASE_URL / arbitrary *_TOKEN /
-    // *_SECRET / *_KEY variables — every CI agent rotation would risk
-    // leaking a new secret name. Allow-listed PATH / HOME / USER /
-    // SHELL / LANG / LC_* / TERM / TZ + Pugi-internal PUGI_ROOT for
-    // tools that need it. Any other env variable is invisible to the
-    // child process.
-    const childEnv = {};
-    const SAFE_ENV_ALLOW = new Set([
-        'PATH',
-        'HOME',
-        'USER',
-        'LOGNAME',
-        'SHELL',
-        'LANG',
-        'TZ',
-        'TERM',
-        'PWD',
-    ]);
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value === undefined)
-            continue;
-        if (SAFE_ENV_ALLOW.has(key) || key.startsWith('LC_')) {
-            childEnv[key] = value;
-        }
-    }
-    const timeoutMs = options.timeoutMs ?? BASH_DEFAULT_TIMEOUT_MS;
-    // `spawnSync` (vs `execFileSync`) captures stdout AND stderr on
-    // BOTH success and failure paths. Code Reviewer P1:
-    // `execFileSync` returns only stdout on exit 0, silently dropping
-    // stderr output from `tsc`, `eslint`, `pytest`, etc. — the model
-    // would see `(no output)` for successful runs that emitted real
-    // warnings.
-    //
-    // maxBuffer is generous (10 MB) so the child process is never the
-    // truncation gate — the post-hoc `.slice(0, BASH_OUTPUT_CAP)` below
-    // is the single source of truth for what the model sees. Code
-    // Reviewer P2 retro: the previous `BASH_OUTPUT_CAP * 2`
-    // (128 KB) would hard-throw `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`
-    // on noisy commands (`pnpm build`, `tsc --noEmit` on the whole
-    // monorepo) instead of returning the truncated head.
-    const result = spawnSync('/bin/sh', ['-c', command], {
-        cwd: ctx.root,
-        env: childEnv,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: timeoutMs,
-        maxBuffer: BASH_CHILD_MAXBUFFER,
-    });
-    if (result.error) {
-        const err = result.error;
-        if (err.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
-            const reason = `bash command timed out after ${timeoutMs}ms`;
-            recordToolResult(ctx.session, toolCallId, 'error', reason);
-            throw new Error(reason);
-        }
-        if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
-            // maxBuffer overflow — surface as truncated rather than an
-            // opaque Node internal code so the model sees the same
-            // truncation marker it gets on stdout/stderr cap hits. With the
-            // post-Code-Reviewer-P2-retro-2026-05-23 maxBuffer at 10 MB
-            // this branch only fires on truly pathological output (>10 MB
-            // single command).
-            const reason = `bash output exceeded ${BASH_CHILD_MAXBUFFER} byte child-process buffer`;
-            recordToolResult(ctx.session, toolCallId, 'error', reason);
-            throw new Error(reason);
-        }
-        const reason = `bash invocation failed: ${err.message ?? String(err)}`;
-        recordToolResult(ctx.session, toolCallId, 'error', reason);
-        throw new Error(reason);
-    }
-    const stdout = (result.stdout ?? '').toString();
-    const stderr = (result.stderr ?? '').toString();
-    const truncatedOut = stdout.length > BASH_OUTPUT_CAP;
-    const truncatedErr = stderr.length > BASH_OUTPUT_CAP;
-    const truncated = truncatedOut || truncatedErr;
-    const out = truncatedOut
-        ? `${stdout.slice(0, BASH_OUTPUT_CAP)}\n(...truncated at ${BASH_OUTPUT_CAP} bytes)`
-        : stdout;
-    const err = truncatedErr
-        ? `${stderr.slice(0, BASH_OUTPUT_CAP)}\n(...truncated at ${BASH_OUTPUT_CAP} bytes)`
-        : stderr;
-    const exitCode = result.status ?? 1;
-    // Non-zero exit is a normal outcome (e.g. `grep` finding no match,
-    // `test -f` returning 1). Surface it as a success at the audit
-    // layer; the engine loop feeds the exit code back to the model.
-    recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${exitCode} stdout=${stdout.length} stderr=${stderr.length}`);
-    return { stdout: out, stderr: err, exitCode, truncated };
-}
-//# sourceMappingURL=file-tools.js.map