@nathapp/nax-agent 0.91.7-canary.7 → 0.91.7-canary.8

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.91.7-canary.8] - 2026-10-29
+
+- No changes in this package. Released in lockstep with the other nax packages.
+
 ## [0.91.7-canary.7] - 2026-10-29
 
 - No changes in this package. Released in lockstep with the other nax packages.

package/dist/coding-tools/coding-tool-extras.d.ts

@@ -9,6 +9,7 @@
 import type { BashApprovalMode } from "#src/config/bash-approval";
 import type { QualityCommandSpec } from "#src/internal/command-spec/index";
 import type { CommandLauncher } from "#src/sandbox/index";
+import type { BackgroundCommandPort } from "#src/tools/bash-background";
 import { type CodingTool, type DeclaredCommandRunner, type ToolGrant } from "#src/tools/index";
 export interface DeclaredCommandToolsArgs {
     readonly declaredCommands: ReadonlyMap<string, QualityCommandSpec>;
@@ -39,6 +40,7 @@ export interface DeclaredCommandToolsArgs {
      * flag by name.
      */
     readonly unsandboxedCommands?: boolean;
+    readonly backgroundCommands?: BackgroundCommandPort;
 }
 /**
  * US-003: `unsandboxedCommands` as a spreadable field — present only when the
@@ -77,3 +79,9 @@ export declare function unsandboxedRuntimeOption(args: {
     };
 };
 export declare function buildDeclaredCommandTools(args: DeclaredCommandToolsArgs): CodingTool[];
+/** Preserve absence at every session/support forwarding hop. */
+export declare function backgroundToolOptions(args?: {
+    readonly backgroundCommands?: BackgroundCommandPort;
+}): {
+    readonly backgroundCommands?: BackgroundCommandPort;
+};

package/dist/coding-tools/coding-tool-extras.js

@@ -1,3 +1,11 @@
+/**
+ * The session-local tools an operation declares: RunCommand (its declared
+ * commands and, when `Exec` is declared, its argv branch) and Bash.
+ *
+ * Extracted from coding-tool-support.ts to keep that file under its 600-line
+ * source limit ahead of the P4 sandbox wiring. A pure move: every comment that
+ * explains a field below travelled with it.
+ */
 import { createBashTool, createRunCommandTool, } from "#src/tools/index";
 /**
  * US-003: `unsandboxedCommands` as a spreadable field — present only when the
@@ -88,8 +96,17 @@ export function buildDeclaredCommandTools(args) {
                     ...(args.humanApproval === true ? { humanApproval: true } : {}),
                     ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
                     ...unsandboxedToolOptions(args),
+                    ...bashBackgroundOption(args),
                 }),
             ]
             : []),
     ];
 }
+/** Preserve absence at every session/support forwarding hop. */
+export function backgroundToolOptions(args) {
+    return args?.backgroundCommands === undefined ? {} : { backgroundCommands: args.backgroundCommands };
+}
+/** Only Bash receives this capability; RunCommand's argv branch stays unchanged. */
+function bashBackgroundOption(args) {
+    return args.backgroundCommands === undefined ? {} : { background: args.backgroundCommands };
+}

package/dist/coding-tools/coding-tool-support.d.ts

@@ -14,6 +14,7 @@ import type { BashApprovalMode } from "#src/config/bash-approval";
 import type { QualityCommandSpec } from "#src/internal/command-spec/index";
 import type { AskResolver } from "#src/permissions/index";
 import type { CommandLauncher } from "#src/sandbox/index";
+import type { BackgroundCommandPort } from "#src/tools/bash-background";
 import { type CodingTool, type CodingToolName, type CodingToolRuntime, type DeclaredCommandRunner, type ProtectedPathsPolicy, type ToolAuditSink, type ToolGrant, type ToolPatternNarrowing, type ToolSurfaceDraft, type ToolSurfaceRecord } from "#src/tools/index";
 import type { OwnedPathsPolicy } from "#src/tools/owned-paths";
 export interface CodingToolSupport {
@@ -148,6 +149,7 @@ export declare function buildCodingToolSupport(args: {
      * the runtime's own reading of the field is a later story.
      */
     unsandboxedCommands?: boolean;
+    backgroundCommands?: BackgroundCommandPort;
     askOnUnsandboxed?: boolean;
     /** US-001: forwarded into ToolRunContext so Bash/Exec can SIGKILL on cancel. */
     abortSignal?: AbortSignal;

package/dist/coding-tools/coding-tool-support.js

@@ -11,7 +11,7 @@
 import { getSafeLogger, NaxError } from "#src/infra/index";
 import { advertisedSchemaBytes, BASH_TOOL_NAME, compileToolPolicy, createCodingToolRuntime, createNoOpToolAuditSink, createToolAuditSink, EXEC_TOOL_NAME, } from "#src/tools/index";
 import { resolveBashSupport } from "./coding-tool-bash.js";
-import { buildDeclaredCommandTools, unsandboxedRuntimeOption, unsandboxedToolOptions } from "./coding-tool-extras.js";
+import { backgroundToolOptions, buildDeclaredCommandTools, unsandboxedRuntimeOption, unsandboxedToolOptions, } from "./coding-tool-extras.js";
 import { isTempConfined, rawScreenOptionsFor } from "./coding-tool-sandbox.js";
 export function buildCodingToolSupport(args) {
     if (args.declared.length === 0)
@@ -120,6 +120,7 @@ export function buildCodingToolSupport(args) {
                 ...(args.shell !== undefined ? { shell: args.shell } : {}),
                 ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
                 ...unsandboxedToolOptions(args),
+                ...backgroundToolOptions(args),
             }),
         ],
         ...(args.providerIdByTool !== undefined ? { providerIdByTool: args.providerIdByTool } : {}),

package/dist/index.d.ts

@@ -46,3 +46,4 @@ export type { TurnEvent, TurnEventSink } from "#src/session/turn-event";
 export { adaptProviderTool, advertisedSchemaBytes, applyModelTruncationPolicy, BASH_TIMEOUT_MS, BASH_TOOL_NAME, buildCommitArgvs, buildGitArgv, buildGrepArgv, type CodingTool, type CodingToolName, type CodingToolOutcome, type CodingToolRuntime, classifyExec, compileToolPolicy, createBashTool, createCodingToolRuntime, createNoOpToolAuditSink, createRunCommandTool, createToolAuditSink, cutBufferToByteCap, DEFAULT_BASH_SHELL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_MAX_COUNT, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, type DeclaredCommandRequest, type DeclaredCommandResult, type DeclaredCommandRunner, deleteTool, EXEC_TOOL_NAME, type ExecTarget, editTool, expandMcpRuleGrants, expandProviderGrants, flushOpenToolAuditSinks, GIT_ESCAPE_FLAGS, GIT_READ_VERBS, getCodingTool, gitCommitTool, gitExcludePathspecsOf, gitIgnorePatternsOf, gitTool, globTool, grepTool, isKnownManager, listCodingTools, MAX_PROVIDER_DESCRIPTION_BYTES, MAX_PROVIDER_SCHEMA_BYTES, MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER, MCP_INSTRUCTIONS_MAX_CHARS_TOTAL, MCP_RULE_TOOL, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, type ModelTruncationOptions, mcpRuleAdmits, type NormalizeInput, type NormalizeResult, namespacedToolName, narrowGrants, normalizeExec, normalizeManagerBinary, type PolicyVerdict, PROVIDER_ID_RE, type ProtectedPathsPolicy, type ProviderGrantEntry, type ProviderKind, type ProviderTool, partitionMcpRules, partitionNaxOwnedPaths, providerAttachesTo, READ_CEILING, RESERVED_TOOL_NAMES, type ReadFileSliceOptions, type ReadFileSliceResult, type RegisteredSink, type ResolvedProviderTools, readFileSlice, readTool, registerBuiltinCodingTools, registerBuiltinTool, registerCodingTool, registerToolAuditSink, renderProviderInstructions, requestCapabilityTool, resolveProviderTools, resolveWithin, SCRATCHPAD_DIR, SPILL_DIR, type SpillRequest, sanitizeProviderTools, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool, spillRelativePath, substituteCommand, substituteCommandSpec, type ToolAuditHeader, type ToolAuditSink, type ToolCallContext, type ToolCallRecord, type ToolGrant, type ToolPatternNarrowing, type ToolPolicy, type ToolPolicyOptions, type ToolProvider, type ToolResult, type ToolRunContext, type ToolScope, type ToolSurfaceDraft, type ToolSurfaceRecord, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, unregisterToolAuditSink, validateProviderId, writeSpill, writeTool, } from "#src/tools/index";
 export { compileArgvPattern, matchesArgvPattern, type CompiledPattern } from "#src/tools/policy-match";
 export { EMPTY_OWNED_PATHS_POLICY, type OwnedBashCandidate, type OwnedPathsPolicy, } from "#src/tools/owned-paths";
+export type { BackgroundCommandPort, BackgroundCommandHandle, BackgroundCommandSink, BackgroundCommandEnd, ForegroundCommand, } from "#src/tools/bash-background";

package/dist/internal/argv-exec.d.ts

@@ -18,6 +18,10 @@ export interface RunArgvOptions {
      * and the result resolves with `aborted: true`. US-001.
      */
     readonly signal?: AbortSignal;
+    /** Abort to remove only the deadline, without cancelling the command. */
+    readonly releaseDeadline?: AbortSignal;
+    /** Observes every read chunk before capture; observer exceptions are ignored. */
+    readonly onOutput?: (stream: "stdout" | "stderr", chunk: Uint8Array) => void;
 }
 export interface ArgvExecResult {
     readonly exitCode: number;

package/dist/internal/argv-exec.js

@@ -84,7 +84,7 @@ function buildEnv(options) {
  * after a process-group kill: a child that ignores the kill cannot pin
  * runArgv forever on its still-open pipe.
  */
-async function drainToEof(stream, signal) {
+async function drainToEof(stream, signal, onChunk) {
     const reader = stream.getReader();
     const capture = new BoundedCapture(_argvExecDeps.streamCaptureBytes);
     const onAbort = () => {
@@ -100,8 +100,16 @@ async function drainToEof(stream, signal) {
             const { done, value } = await reader.read();
             if (done === true)
                 break;
-            if (value !== undefined)
+            if (value !== undefined) {
+                try {
+                    // Copy even Buffer-backed chunks: observers must not mutate captured bytes.
+                    onChunk?.(Uint8Array.from(value));
+                }
+                catch {
+                    // Observers are best-effort: never let one truncate capture or stop draining.
+                }
                 capture.push(value);
+            }
         }
     }
     catch {
@@ -175,6 +183,24 @@ class BoundedCapture {
         return head + marker + new TextDecoder().decode(tail.subarray(start));
     }
 }
+/** The deadline is releasable independently of command cancellation and drain grace. */
+function armDeadline(options, onTimeout) {
+    let timerId;
+    const release = () => {
+        if (timerId !== undefined)
+            _argvExecDeps.clearTimeout(timerId);
+        timerId = undefined;
+    };
+    if (options.releaseDeadline?.aborted !== true) {
+        // A cancellable timer: releaseDeadline and settlement both clear it mid-flight.
+        timerId = _argvExecDeps.setTimeout(onTimeout, options.timeoutMs);
+        options.releaseDeadline?.addEventListener("abort", release, { once: true });
+    }
+    return () => {
+        release();
+        options.releaseDeadline?.removeEventListener("abort", release);
+    };
+}
 export async function runArgv(options) {
     const signal = options.signal;
     // Already-aborted signal: never spawn. The caller gets `aborted: true` with
@@ -210,14 +236,14 @@ export async function runArgv(options) {
     // BUG-13: unlike every git call (routed through gitWithTimeout), a spawn
     // with no deadline can block its caller forever on a hung install
     // (registry/NFS stall).
-    const timerId = _argvExecDeps.setTimeout(() => {
+    const clearDeadline = armDeadline(options, () => {
         timedOut = true;
         // MEM-4: proc.kill() reaches only the direct child, orphaning postinstall
         // grandchildren. killProcessGroup(pid, "SIGKILL") kills the whole group
         // (negative pid), falling back to the single process on ESRCH.
         killGroup();
         stopReaders();
-    }, options.timeoutMs);
+    });
     // US-001: an abort races the timeout. One listener, removed on every settle
     // path so a never-aborted signal never leaks a registration (AC10).
     const onAbort = () => {
@@ -233,57 +259,61 @@ export async function runArgv(options) {
     // to settle (via reader.cancel()) after we kill the process group. US-001
     // requires that settlement stay bounded even when a background process
     // inherits the pipe and ignores the SIGKILL.
-    const stdoutPromise = drainToEof(proc.stdout, stdoutController.signal);
-    const stderrPromise = drainToEof(proc.stderr, stderrController.signal);
-    const exitCode = await proc.exited;
-    // Post-exit drain grace. After exit, the streams MUST close — they were
-    // owned by the shell, which is now dead. Background processes that
-    // inherited the pipe (the `&` case) keep it open: that's the orphan.
-    const graceMs = _argvExecDeps.drainGraceMs;
-    // Cleared on every settle path: a successful command whose readers close
-    // before the grace elapses would otherwise leave a pending timer whose
-    // callback fires 500ms later and resolves an orphaned promise. Under load
-    // the leaked registrations accumulate in the timer wheel for nothing.
-    let graceTimerId;
-    const gracePromise = new Promise((resolve) => {
-        graceTimerId = _argvExecDeps.setTimeout(() => resolve("expired"), graceMs);
-    });
-    const stdoutSettled = await Promise.race([
-        stdoutPromise,
-        gracePromise.then(() => "expired"),
-    ]);
-    const stderrSettled = await Promise.race([
-        stderrPromise,
-        gracePromise.then(() => "expired"),
-    ]);
-    if (graceTimerId !== undefined)
-        _argvExecDeps.clearTimeout(graceTimerId);
-    const stdoutClosed = stdoutSettled !== "expired";
-    const stderrClosed = stderrSettled !== "expired";
-    if (!stdoutClosed || !stderrClosed) {
-        orphansKilled = true;
-        killGroup();
-        // The OS should close the pipes once the group dies; race that against
-        // a small post-kill budget. If a holdout somehow ignores SIGKILL or is
-        // not yet reaped, abort the matching reader controller — that drives
-        // `reader.cancel()` in drainToEof, which forces the pending `read()` to
-        // resolve with `done: true` and bounds settlement.
-        if (!stdoutClosed)
-            stdoutController.abort();
-        if (!stderrClosed)
-            stderrController.abort();
+    try {
+        const stdoutPromise = drainToEof(proc.stdout, stdoutController.signal, options.onOutput?.bind(undefined, "stdout"));
+        const stderrPromise = drainToEof(proc.stderr, stderrController.signal, options.onOutput?.bind(undefined, "stderr"));
+        const exitCode = await proc.exited;
+        // Post-exit drain grace. After exit, the streams MUST close — they were
+        // owned by the shell, which is now dead. Background processes that
+        // inherited the pipe (the `&` case) keep it open: that's the orphan.
+        const graceMs = _argvExecDeps.drainGraceMs;
+        // Cleared on every settle path: a successful command whose readers close
+        // before the grace elapses would otherwise leave a pending timer whose
+        // callback fires 500ms later and resolves an orphaned promise. Under load
+        // the leaked registrations accumulate in the timer wheel for nothing.
+        let graceTimerId;
+        const gracePromise = new Promise((resolve) => {
+            graceTimerId = _argvExecDeps.setTimeout(() => resolve("expired"), graceMs);
+        });
+        const stdoutSettled = await Promise.race([
+            stdoutPromise,
+            gracePromise.then(() => "expired"),
+        ]);
+        const stderrSettled = await Promise.race([
+            stderrPromise,
+            gracePromise.then(() => "expired"),
+        ]);
+        if (graceTimerId !== undefined)
+            _argvExecDeps.clearTimeout(graceTimerId);
+        const stdoutClosed = stdoutSettled !== "expired";
+        const stderrClosed = stderrSettled !== "expired";
+        if (!stdoutClosed || !stderrClosed) {
+            orphansKilled = true;
+            killGroup();
+            // The OS should close the pipes once the group dies; race that against
+            // a small post-kill budget. If a holdout somehow ignores SIGKILL or is
+            // not yet reaped, abort the matching reader controller — that drives
+            // `reader.cancel()` in drainToEof, which forces the pending `read()` to
+            // resolve with `done: true` and bounds settlement.
+            if (!stdoutClosed)
+                stdoutController.abort();
+            if (!stderrClosed)
+                stderrController.abort();
+        }
+        // Always await the readers to harvest whatever they captured.
+        const stdoutFinal = stdoutClosed ? stdoutSettled : await stdoutPromise;
+        const stderrFinal = stderrClosed ? stderrSettled : await stderrPromise;
+        return {
+            exitCode,
+            stdout: stdoutFinal.text,
+            stderr: stderrFinal.text,
+            timedOut,
+            aborted,
+            orphansKilled,
+        };
+    }
+    finally {
+        clearDeadline();
+        signal?.removeEventListener("abort", onAbort);
     }
-    // Always await the readers to harvest whatever they captured.
-    const stdoutFinal = stdoutClosed ? stdoutSettled : await stdoutPromise;
-    const stderrFinal = stderrClosed ? stderrSettled : await stderrPromise;
-    _argvExecDeps.clearTimeout(timerId);
-    signal?.removeEventListener("abort", onAbort);
-    return {
-        exitCode,
-        stdout: stdoutFinal.text,
-        stderr: stderrFinal.text,
-        timedOut,
-        aborted,
-        orphansKilled,
-    };
 }

package/dist/sandbox/launcher.js

@@ -66,6 +66,8 @@ async function runUnwrapped(req, sandbox, env) {
         stripEnvVars: [...req.stripEnvVars],
         ...(overlay !== undefined ? { env: overlay } : {}),
         ...(req.signal !== undefined ? { signal: req.signal } : {}),
+        ...(req.releaseDeadline !== undefined ? { releaseDeadline: req.releaseDeadline } : {}),
+        ...(req.onOutput !== undefined ? { onOutput: req.onOutput } : {}),
     });
     return { ...result, executed: argv, sandbox };
 }
@@ -102,6 +104,8 @@ async function runWrapped(req, backend, policy, env) {
             stripEnvVars: [...req.stripEnvVars],
             ...(req.env !== undefined ? { env: req.env } : {}),
             ...(req.signal !== undefined ? { signal: req.signal } : {}),
+            ...(req.releaseDeadline !== undefined ? { releaseDeadline: req.releaseDeadline } : {}),
+            ...(req.onOutput !== undefined ? { onOutput: req.onOutput } : {}),
         });
         const denied = result.exitCode !== 0 && LIKELY_SANDBOX_DENIAL.test(result.stderr);
         const violations = backend.annotate(commandId, result.stderr);

package/dist/sandbox/types.d.ts

@@ -116,6 +116,10 @@ export interface LaunchRequest {
     readonly unwrapped?: true;
     /** Aborts the run: forwarded to runArgv, which SIGKILLs the process group. US-001. */
     readonly signal?: AbortSignal;
+    /** Releases the deadline without cancelling the run. Forwarded to runArgv. */
+    readonly releaseDeadline?: AbortSignal;
+    /** Best-effort per-chunk observer, forwarded before bounded output capture. */
+    readonly onOutput?: (stream: "stdout" | "stderr", chunk: Uint8Array) => void;
 }
 export interface LaunchResult extends ArgvExecResult {
     /** The logical argv (what the tool asked to run), not the sandbox wrapper argv. */

package/dist/session/agent-session-types.d.ts

@@ -7,6 +7,7 @@ import type { CommandInterceptor } from "#src/command-interceptor/index";
 import type { CommandShadow } from "#src/command-safety/types";
 import type { TokenUsage } from "#src/cost/standard-types";
 import type { TranscriptStore } from "#src/native/session/transcript-types";
+import type { BackgroundCommandPort } from "#src/tools/bash-background";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
 import type { BackendInfo, SessionBackend } from "./session-backend.ts";
 import type { JSONSchema } from "./tool-descriptor.ts";
@@ -45,6 +46,8 @@ export interface AgentSessionHostPorts {
     readonly protectedPaths?: ProtectedPathsPolicy;
     readonly commandInterceptor?: CommandInterceptor;
     readonly commandShadow?: CommandShadow;
+    /** Opt in to host-owned background Bash commands. */
+    readonly backgroundCommands?: BackgroundCommandPort;
 }
 export interface CreateAgentSessionOptions {
     /** The driver: `nativeBackend({ model })`, or an ACP backend. Native-only options live on the backend. */

package/dist/session/native-backend-options.js

@@ -45,6 +45,9 @@ const OptionsSchema = z.strictObject({
         commandShadow: z
             .custom(hasMethods(["observe", "settle", "drain"]), "must implement observe, settle and drain")
             .optional(),
+        backgroundCommands: z
+            .custom(hasMethods(["adopt", "foreground"]), "must implement adopt and foreground")
+            .optional(),
         commandInterceptor: z.custom(hasMethods(["intercept"]), "must implement intercept").optional(),
     })
         .optional(),

package/dist/session/native-backend.js

@@ -4,6 +4,7 @@
  * with built-in and embedder tools, the NativeSessionAdapter, loop handlers
  * and the resume model check.
  */
+import { backgroundToolOptions } from "#src/coding-tools/coding-tool-extras";
 import { getLogger } from "#src/infra/agent-logger";
 import { errorMessage } from "#src/infra/errors";
 import { DEFAULT_SPIN_BREAKER_SETTINGS } from "#src/infra/spin-breaker/index";
@@ -85,6 +86,7 @@ async function openNative(resolved, ctx) {
         askOnUnsandboxed: posture.askOnUnsandboxed,
         askDiscoveredTools: posture.askDiscoveredTools,
         commandShadow: raw.hostPorts?.commandShadow,
+        ...backgroundToolOptions(raw.hostPorts),
         // US-003: the profile's validated opt-in, so an interactive "full" session
         // can offer Bash's per-call escape without turning the sandbox off.
         ...(allowUnsandboxedCommands ? { unsandboxedCommands: true } : {}),

package/dist/session/session-tool-support.d.ts

@@ -5,6 +5,7 @@ import type { BashApprovalMode } from "#src/config/bash-approval";
 import { type SandboxConfig } from "#src/config/schemas-sandbox";
 import type { AskResolver } from "#src/permissions/index";
 import type { CommandLauncher, SandboxState } from "#src/sandbox/index";
+import type { BackgroundCommandPort } from "#src/tools/bash-background";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
 import type { ResolvedProviderTools } from "#src/tools/provider-advertise";
 import type { CodingToolName, ToolGrant } from "#src/tools/types";
@@ -72,6 +73,7 @@ export interface SessionToolSupportArgs {
      * defaulting to off, so every existing caller keeps today's tool surface.
      */
     readonly unsandboxedCommands?: boolean;
+    readonly backgroundCommands?: BackgroundCommandPort;
     readonly providerTools?: ResolvedProviderTools;
     /**
      * Narrow the profile's built-in tools to these names; the universal scratchpad

package/dist/session/session-tool-support.js

@@ -4,7 +4,7 @@
  * buildCodingToolSupport takes, picks the embedder default protected-paths
  * policy, and enforces the sandbox floor for "full".
  */
-import { unsandboxedToolOptions } from "#src/coding-tools/coding-tool-extras";
+import { backgroundToolOptions, unsandboxedToolOptions } from "#src/coding-tools/coding-tool-extras";
 import { resolveSessionSandbox } from "#src/coding-tools/coding-tool-sandbox";
 import { buildCodingToolSupport } from "#src/coding-tools/coding-tool-support";
 import { UNIVERSAL_CODING_TOOLS } from "#src/coding-tools/universal-coding-tools";
@@ -148,6 +148,7 @@ export function buildSessionToolSupport(args) {
         ...(args.interceptor !== undefined ? { interceptor: args.interceptor } : {}),
         ...(args.launcher !== undefined ? { launcher: args.launcher } : {}),
         ...unsandboxedToolOptions(args),
+        ...backgroundToolOptions(args),
         ...postureToolOptions(args),
     });
     // Unreachable while the scratchpad trio is always declared and granted; kept for the type.

package/dist/tools/bash-background.d.ts

@@ -0,0 +1,74 @@
+import type { RunArgvOptions } from "#src/internal/argv-exec";
+export type BackgroundStream = "stdout" | "stderr";
+export interface BackgroundCommandEnd {
+    readonly exitCode: number;
+    readonly timedOut: boolean;
+    readonly aborted: boolean;
+    /** Present when the launch itself failed. */
+    readonly launchError?: string;
+}
+export interface BackgroundCommandHandle {
+    readonly command: string;
+    readonly description?: string;
+    readonly origin: "agent" | "moved";
+    /** Always resolves, including on launch failure. */
+    readonly ended: Promise<BackgroundCommandEnd>;
+    /** Immediately aborts the launch, SIGKILLing its process group. */
+    stop(): void;
+}
+export interface BackgroundCommandSink {
+    readonly id: string;
+    append(stream: BackgroundStream, chunk: Uint8Array): void;
+}
+export interface ForegroundCommand {
+    readonly command: string;
+    moveToBackground(): void;
+}
+export interface BackgroundCommandPort {
+    adopt(handle: BackgroundCommandHandle): BackgroundCommandSink;
+    /** Register a foreground call; the returned function unregisters it. */
+    foreground(call: ForegroundCommand): () => void;
+}
+export type BackgroundLaunchOptions = Pick<RunArgvOptions, "signal" | "releaseDeadline" | "onOutput">;
+/** The newest raw output retained while a foreground call can still be moved. */
+export declare const FOREGROUND_REPLAY_BYTES: number;
+type BackgroundResult = {
+    content: string;
+    isError: false;
+};
+interface LaunchResult {
+    readonly launched: {
+        readonly exitCode: number;
+        readonly timedOut: boolean;
+        readonly aborted?: boolean;
+    };
+}
+interface BashExecutionRequest<T extends LaunchResult> {
+    readonly port?: BackgroundCommandPort;
+    readonly runInBackground: unknown;
+    readonly command: string;
+    readonly description: unknown;
+    readonly signal?: AbortSignal;
+    readonly launch: (options?: BackgroundLaunchOptions, isForeground?: () => boolean) => Promise<T>;
+}
+/** Keep framing in Bash, but keep all ownership and early-return logic here. */
+export declare function runBashWithBackground<T extends LaunchResult>(request: BashExecutionRequest<T>): Promise<T | BackgroundResult>;
+export declare function withBackgroundSentence(description: string, port?: BackgroundCommandPort): string;
+/** Adopt before launching so even the first output chunk has a sink. */
+export declare function startBashBackground(request: {
+    readonly port?: BackgroundCommandPort;
+    readonly runInBackground: unknown;
+    readonly command: string;
+    readonly description: unknown;
+    readonly launch: (options: BackgroundLaunchOptions) => Promise<{
+        readonly launched: {
+            readonly exitCode: number;
+            readonly timedOut: boolean;
+            readonly aborted?: boolean;
+        };
+    }>;
+}): {
+    content: string;
+    isError: false;
+} | undefined;
+export {};

package/dist/tools/bash-background.js

@@ -0,0 +1,151 @@
+import { errorMessage } from "#src/infra/errors";
+/** The newest raw output retained while a foreground call can still be moved. */
+export const FOREGROUND_REPLAY_BYTES = 1024 * 1024;
+/** Keep framing in Bash, but keep all ownership and early-return logic here. */
+export async function runBashWithBackground(request) {
+    const background = startBashBackground(request);
+    if (background !== undefined)
+        return background;
+    if (request.port === undefined)
+        return request.launch();
+    return runMovableForeground({ ...request, port: request.port });
+}
+function outputReplay() {
+    let chunks = [];
+    let bytes = 0;
+    let sink;
+    let replaying = false;
+    return {
+        append(stream, chunk) {
+            if (sink !== undefined)
+                return sink.append(stream, chunk);
+            if (chunk.byteLength === 0)
+                return;
+            const tail = replaying ? chunk : chunk.subarray(-FOREGROUND_REPLAY_BYTES);
+            // Copy even Buffer inputs: Buffer.slice retains the original backing allocation.
+            chunks.push({ stream, chunk: Uint8Array.from(tail) });
+            bytes += tail.byteLength;
+            while (!replaying && bytes > FOREGROUND_REPLAY_BYTES) {
+                const first = chunks[0];
+                if (first === undefined)
+                    break;
+                const dropped = Math.min(first.chunk.byteLength, bytes - FOREGROUND_REPLAY_BYTES);
+                bytes -= dropped;
+                if (dropped === first.chunk.byteLength)
+                    chunks.shift();
+                else
+                    first.chunk = first.chunk.slice(dropped);
+            }
+        },
+        replay(target) {
+            // Drain before switching to live forwarding, including any reentrant appends.
+            replaying = true;
+            for (const item of chunks)
+                target.append(item.stream, item.chunk);
+            chunks = [];
+            bytes = 0;
+            sink = target;
+        },
+    };
+}
+function commandEnd(result) {
+    return {
+        exitCode: result.launched.exitCode,
+        timedOut: result.launched.timedOut,
+        aborted: result.launched.aborted === true,
+    };
+}
+function failedEnd(error) {
+    return { exitCode: -1, timedOut: false, aborted: false, launchError: errorMessage(error) };
+}
+function foregroundControl(request) {
+    const controller = new AbortController();
+    const releaseDeadline = new AbortController();
+    const released = Promise.withResolvers();
+    const ended = Promise.withResolvers();
+    const output = outputReplay();
+    let settled = false;
+    let moved = false;
+    const cancel = () => controller.abort();
+    const detach = () => request.signal?.removeEventListener("abort", cancel);
+    request.signal?.addEventListener("abort", cancel, { once: true });
+    if (request.signal?.aborted === true)
+        cancel();
+    const call = {
+        command: request.command,
+        moveToBackground() {
+            if (settled || moved)
+                return;
+            moved = true;
+            releaseDeadline.abort();
+            detach();
+            const sink = request.port.adopt({
+                command: request.command,
+                ...(typeof request.description === "string" ? { description: request.description } : {}),
+                origin: "moved",
+                ended: ended.promise,
+                stop: cancel,
+            });
+            output.replay(sink);
+            released.resolve({ content: `moved to the background as ${sink.id}`, isError: false });
+        },
+    };
+    return {
+        call,
+        released: released.promise,
+        options: { signal: controller.signal, releaseDeadline: releaseDeadline.signal, onOutput: output.append },
+        isForeground: () => !moved,
+        finish(end) {
+            settled = true;
+            ended.resolve(end);
+        },
+        detach,
+    };
+}
+async function runMovableForeground(request) {
+    const control = foregroundControl(request);
+    const unregister = request.port.foreground(control.call);
+    const launch = Promise.resolve().then(() => request.launch(control.options, control.isForeground));
+    // Observe both outcomes even after the race releases the foreground tool result.
+    void launch.then((result) => control.finish(commandEnd(result)), (error) => control.finish(failedEnd(error)));
+    try {
+        return await Promise.race([launch, control.released]);
+    }
+    finally {
+        control.detach();
+        unregister();
+    }
+}
+export function withBackgroundSentence(description, port) {
+    if (port === undefined)
+        return description;
+    const separator = description.endsWith(" ") ? "" : " ";
+    return `${description}${separator}Set "runInBackground": true to return at once with a task id; a notice arrives when the command ends.`;
+}
+/** Adopt before launching so even the first output chunk has a sink. */
+export function startBashBackground(request) {
+    if (request.port === undefined || request.runInBackground !== true)
+        return undefined;
+    const controller = new AbortController();
+    const completion = Promise.withResolvers();
+    const sink = request.port.adopt({
+        command: request.command,
+        ...(typeof request.description === "string" ? { description: request.description } : {}),
+        origin: "agent",
+        ended: completion.promise,
+        stop: () => controller.abort(),
+    });
+    // The promise boundary also settles synchronous launch failures without rejection.
+    void Promise.resolve()
+        .then(() => request.launch({
+        signal: controller.signal,
+        releaseDeadline: AbortSignal.abort(),
+        onOutput: (stream, chunk) => sink.append(stream, chunk),
+    }))
+        .then(({ launched }) => completion.resolve({
+        exitCode: launched.exitCode,
+        timedOut: launched.timedOut,
+        aborted: launched.aborted === true,
+    }), (error) => completion.resolve({ exitCode: -1, timedOut: false, aborted: false, launchError: errorMessage(error) }));
+    return { content: `started in the background as ${sink.id}`, isError: false };
+}

package/dist/tools/bash.d.ts

@@ -22,6 +22,7 @@
 import { runArgv } from "#src/internal/argv-exec";
 import type { BashApprovalMode } from "../config/bash-approval.ts";
 import { type CommandLauncher } from "../sandbox/index.ts";
+import { type BackgroundCommandPort } from "./bash-background.ts";
 import type { CodingTool } from "./registry.ts";
 /**
  * Deadline for a Bash spawn — the same ceiling the Exec branch uses
@@ -32,6 +33,7 @@ import type { CodingTool } from "./registry.ts";
 export declare const BASH_TIMEOUT_MS = 300000;
 export declare const DEFAULT_BASH_SHELL = "/bin/sh";
 export interface BashToolOptions {
+    readonly background?: BackgroundCommandPort;
     /** `quality.shell`. */
     readonly shell?: string;
     /** `quality.stripEnvVars` — secrets removed before the spawn. */

package/dist/tools/bash.js

@@ -24,6 +24,7 @@ import { agentOutputOverlay } from "#src/internal/agent-output-env";
 import { runArgv } from "#src/internal/argv-exec";
 import { formatExecBody } from "#src/internal/exec-framing";
 import { rawBashRefusalReason, sandboxSentence, unsandboxedSentence } from "../sandbox/index.js";
+import { runBashWithBackground, withBackgroundSentence, } from "./bash-background.js";
 import { cutToByteCap, READ_CEILING } from "./truncate.js";
 import { BASH_TOOL_NAME } from "./types.js";
 /**
@@ -179,7 +180,7 @@ function bashToolDescription(shell, opts) {
  * therefore never the string the policy judged, which is exactly why
  * `interceptShell` re-validates the provider's answer rather than trusting it.
  */
-async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, unwrapped, }) {
+async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, unwrapped, backgroundLaunch, isForeground, }) {
     // The run's interceptor arrives on the context (S1 spec port 7), immutable
     // for this call, so the launch below and `postProcess` see the same object.
     const interceptor = ctx.interceptor;
@@ -199,6 +200,7 @@ async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, unwrapp
         stripEnvVars: [...(opts.stripEnvVars ?? [])],
         ...(agentOverlay !== undefined ? { env: agentOverlay } : {}),
         ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+        ...backgroundLaunch,
     };
     const launched = opts.launcher !== undefined
         ? await opts.launcher.run({
@@ -210,8 +212,9 @@ async function launchIntercepted({ command, shell, opts, ctx, timeoutMs, unwrapp
             ...(unwrapped ? { unwrapped: true } : {}),
         })
         : { ...(await _bashToolDeps.runArgv({ argv: executed, ...common })), executed, sandbox: undefined };
-    if (!intercepted.rewritten)
+    if (!intercepted.rewritten || (backgroundLaunch !== undefined && isForeground?.() !== true)) {
         return { launched, stdout: launched.stdout };
+    }
     // The request describes the command the MODEL wrote — the same shape
     // `interceptShell` sent — so post-processing stays keyed to the original,
     // mirroring the Git site, which passes the original argv.
@@ -264,6 +267,7 @@ function bashToolInputSchema(opts) {
                 description: `Deadline in milliseconds (default and maximum ${BASH_TIMEOUT_MS}).`,
             },
             description: { type: "string", description: "One short line on what this command is for." },
+            ...(opts.background !== undefined ? { runInBackground: { type: "boolean" } } : {}),
             ...(opts.unsandboxedCommands === true
                 ? { unsandboxed: { type: "boolean" }, unsandboxedReason: { type: "string" } }
                 : {}),
@@ -279,7 +283,7 @@ export function createBashTool(opts = {}) {
         // not a fault worth an operator's attention — the same reason RunCommand
         // sets this.
         routineErrors: true,
-        description: withUnsandboxedSentence(bashToolDescription(shell, opts), opts),
+        description: withBackgroundSentence(withUnsandboxedSentence(bashToolDescription(shell, opts), opts), opts.background),
         inputSchema: bashToolInputSchema(opts),
         // `commandField` is what routes this call to the Bash branch of the policy
         // (src/tools/policy-bash.ts). No pathFields: the paths are inside the
@@ -301,7 +305,18 @@ export function createBashTool(opts = {}) {
                 // here: whether the argument is ADVERTISED is the option's business, and what a
                 // given call asked for is the call's.
                 const unwrapped = input.unsandboxed === true;
-                const { launched, stdout } = await launchIntercepted({ command, shell, opts, ctx, timeoutMs, unwrapped });
+                const request = { command, shell, opts, ctx, timeoutMs, unwrapped };
+                const result = await runBashWithBackground({
+                    port: opts.background,
+                    runInBackground: input.runInBackground,
+                    command,
+                    description: input.description,
+                    signal: ctx.signal,
+                    launch: (backgroundLaunch, isForeground) => launchIntercepted({ ...request, backgroundLaunch, isForeground }),
+                });
+                if ("content" in result)
+                    return result;
+                const { launched, stdout } = result;
                 // Same framing ladder as RunCommand (Exec) via the shared
                 // `formatExecBody`: an aborted call opens with the cancellation line
                 // and surfaces whatever partial output the readers captured before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.91.7-canary.7",
+  "version": "0.91.7-canary.8",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@nathapp/nax-ai": "0.91.7-canary.7",
+    "@nathapp/nax-ai": "0.91.7-canary.8",
     "zod": "^4.3.6"
   },
   "publishConfig": {