@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/tools/bash-tool.js

@@ -1,59 +1,150 @@
 /**
- * bash tool — run a shell command at full permission (spec §3.6).
+ * bash tool — run a shell command at full permission (spec §3.6), and, since
+ * background-service-supervision, supervise the ones that do not exit.
  *
  * Shell selection: Windows uses `process.env.ComSpec` (cmd.exe by default);
  * POSIX uses `/bin/sh -c`. The command's stdout+stderr and exit code are
  * captured. The `timeout?` param can only SHRINK within the executor ceiling
  * (the core ToolExecutor owns the real timeout + 100 KB truncation — R4), so
  * this tool does not re-implement an output cap.
+ *
+ * I-1 — THIS TOOL NEVER LEAVES ITS PROMISE PENDING. Every exit path goes through
+ * `settle`, and `settle` is reachable from FIVE places: `'error'`, `'close'`,
+ * `'exit'` plus a drain timer, an abort plus a kill grace, and the `timeout`
+ * param plus the same grace. That is the whole of W1, and each of the five
+ * closes a way the old implementation could hang:
+ *
+ *   1. It settled on `'close'`, which fires only when the process has exited AND
+ *      every stdio stream is closed. A child that spawns a detached grandchild
+ *      inheriting the pipe — `Start-Process`, `&`, `nohup`, and every
+ *      `npm run dev` that re-execs — keeps that pipe open after the shell is
+ *      long gone. The shell exited; the promise did not.
+ *   2. `stdio` defaulted to `'pipe'` for stdin, so a command that PROMPTS —
+ *      `npm init`, a package manager asking to install something, `sudo`, a git
+ *      credential prompt — blocked on a read that could never be satisfied.
+ *   3. An abort killed the tree and then went on waiting for a `'close'` that a
+ *      detached grandchild was still holding.
+ *
+ * The happy path is BYTE-IDENTICAL to the pre-change build: `$ cmd\n<output>\n
+ * [exit code N]`, same truncation, same footer. That is what keeps the existing
+ * `bash` assertions meaningful rather than rewritten.
  */
 import { spawn } from 'node:child_process';
 import process from 'node:process';
 import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
+import { looksLongRunning } from '../proc/classify.js';
+import { killTree } from '../proc/kill-tree.js';
+import { PROC_LIMITS } from '../proc/limits.js';
 /**
- * Kill the whole process tree. With `shell:true` the direct child is the shell
- * wrapper, so on Windows we must `taskkill /t` to reach the grandchild; a plain
- * `child.kill()` would orphan it (leaving pipes open and cwd locked).
+ * The two sentences appended to the tool description when background launches
+ * are available.
+ *
+ * MODEL-FACING POLICY, so their wording is versioned with the prompt block in
+ * `proc/prompt.ts` rather than treated as a comment. They are appended
+ * CONDITIONALLY, which is half of what keeps I-2 true: with the feature off the
+ * description — and therefore the system prompt's tool list — is the pre-feature
+ * string, byte for byte.
  */
-function killTree(child) {
-    if (child.pid === undefined)
-        return;
-    if (process.platform === 'win32') {
-        try {
-            spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true });
-        }
-        catch {
-            try {
-                child.kill('SIGKILL');
-            }
-            catch {
-                /* ignore */
-            }
-        }
+const BACKGROUND_DESCRIPTION = ' Set `background: true` for anything that does not exit on its own - dev ' +
+    'servers, watchers, `docker compose up`. Never use `Start-Process`, `&`, ' +
+    '`nohup` or `screen` to detach a command yourself; the runtime supervises ' +
+    'background commands, and a self-detached process cannot be reported on or ' +
+    'stopped.';
+/**
+ * The settle window used when a supervisor is supplied WITHOUT one.
+ *
+ * Only reachable from a test that builds the tool by hand: `AgentController`
+ * always passes `cfg.bash.startupSettleMs`. It mirrors `DEFAULT_BASH_CONFIG`
+ * rather than importing it, because nothing in `tools/` imports `config/` — a
+ * tool takes its policy through the closures below, which is what
+ * `startupSettleMs` is. It is NOT expressed in terms of `PROC_LIMITS`: those are
+ * structural bounds, this is policy, and a multiple of `killGraceMs` that
+ * happens to equal the default today would silently move if that bound ever did.
+ */
+const FALLBACK_STARTUP_SETTLE_MS = 4000;
+/**
+ * The foreground registry a `bash` child registers with, so `forceStop()` can
+ * reach it. `undefined` on the paths that build tools without a supervisor
+ * (every existing test), which is what keeps those byte-identical.
+ */
+function trackForeground(supervisor, pid) {
+    return supervisor ? supervisor.trackForeground(pid) : () => { };
+}
+/** Render a background launch's result block for the model (§3.5). */
+function renderServiceResult(service, opts) {
+    const lines = [`$ ${service.command}`];
+    lines.push(`[background] service ${service.id} started (pid ${service.pid ?? '?'})`);
+    const elapsed = ((service.readyAt ?? service.endedAt ?? Date.now()) - service.startedAt) / 1000;
+    if (service.status === 'ready') {
+        const how = service.detectedBy === 'probe' ? 'port probe' : 'output';
+        const where = service.url ?? (service.port ? `port ${service.port}` : '');
+        lines.push(`[ready] ${where}  (detected from ${how} after ${elapsed.toFixed(1)}s)`);
+    }
+    else if (service.status === 'running') {
+        lines.push(`[running] still alive, nothing to connect to (a watcher, most likely)`);
+    }
+    else if (service.status === 'exited' || service.status === 'failed') {
+        const code = service.exitCode === null ? `signal ${service.signal}` : `code ${service.exitCode}`;
+        lines.push(`[exited] ${code} after ${elapsed.toFixed(1)}s`);
     }
     else {
-        try {
-            child.kill('SIGKILL');
-        }
-        catch {
-            /* ignore */
-        }
+        lines.push(`[starting] not ready yet after ${elapsed.toFixed(1)}s - still coming up`);
+    }
+    if (service.portPreoccupied && service.port !== undefined) {
+        lines.push(`[note] port ${service.port} was already in use before start`);
+    }
+    if (service.rows.length > 0) {
+        lines.push('[log tail]');
+        for (const row of service.rows)
+            lines.push(`  ${row}`);
+    }
+    if (opts.ephemeral) {
+        // D-15 / P1-8: headless has no user who could keep it alive, and saying so
+        // is the difference between a surprise and a documented behaviour.
+        lines.push('[note] this service will be stopped when the run ends.');
     }
+    lines.push(`Read more with bash_output({ service: "${service.id}" }); ` +
+        `stop it with bash_kill({ service: "${service.id}" }).`);
+    const body = lines.join('\n');
+    // A service that DIED is an error result, so the model treats it as one: this
+    // is the failure the user actually cares about, reported in 400 ms instead of
+    // three minutes of stall (G1).
+    return service.status === 'exited' && service.exitCode !== 0
+        ? errorResult(body)
+        : service.status === 'failed'
+            ? errorResult(body)
+            : textResult(body);
 }
-export function makeBash(deps) {
+export function makeBash(deps, options = {}) {
+    const supervisor = options.supervisor;
+    const backgroundAvailable = supervisor !== undefined;
     return defineTool({
         name: 'bash',
         label: 'Shell',
         description: 'Run a shell command at full permission and return its combined ' +
             'stdout+stderr and exit code. `timeout` (ms) may only shrink within the ' +
             'agent tool-timeout ceiling; `cwd` defaults to the working directory. ' +
-            'Emit shell syntax compatible with the OS/shell stated in the system prompt.',
+            'Emit shell syntax compatible with the OS/shell stated in the system prompt.' +
+            (backgroundAvailable ? BACKGROUND_DESCRIPTION : ''),
         parameters: {
             type: 'object',
             properties: {
                 command: { type: 'string', description: 'The shell command to run.' },
                 timeout: { type: 'number', description: 'Optional timeout in milliseconds (shrinks within the ceiling).' },
                 cwd: { type: 'string', description: 'Working directory for this command.' },
+                // SPREAD CONDITIONALLY. With the feature off the schema is the object it
+                // is today, which is what `buildSystemPrompt`'s byte-identity claim (I-2)
+                // is measured against.
+                ...(backgroundAvailable
+                    ? {
+                        background: {
+                            type: 'boolean',
+                            description: 'true = supervise this command and return immediately with a ' +
+                                'service id. false = never background it. Omit to let the ' +
+                                'runtime decide from the command.',
+                        },
+                    }
+                    : {}),
             },
             required: ['command'],
         },
@@ -63,6 +154,25 @@ export function makeBash(deps) {
             const params = rawParams;
             const command = params.command;
             const cwd = params.cwd ? params.cwd : deps.getCwd();
+            // --- The three-valued background decision (D-2 / §3.5) ----------------
+            //
+            // `true`  -> background, always.
+            // `false` -> foreground, always. The escape hatch; nothing overrides it.
+            // absent  -> the classifier, and only where a card can be rendered.
+            if (supervisor && params.background !== false) {
+                const auto = options.interactive !== false &&
+                    options.autoBackground?.() !== false &&
+                    looksLongRunning(command);
+                if (params.background === true || auto) {
+                    return runBackground(supervisor, {
+                        command,
+                        cwd,
+                        toolCallId: id,
+                        settleMs: options.startupSettleMs?.() ?? FALLBACK_STARTUP_SETTLE_MS,
+                        ephemeral: options.interactive === false,
+                    });
+                }
+            }
             return new Promise((resolvePromise) => {
                 let child;
                 try {
@@ -74,40 +184,144 @@ export function makeBash(deps) {
                         cwd,
                         env: process.env,
                         windowsHide: true,
+                        // W1.2 — NO UNANSWERABLE READ. `spawn` defaults every descriptor to
+                        // a pipe, so a command that prompts blocks on a read nobody will
+                        // ever satisfy and the promise never settles. `'ignore'` turns that
+                        // into an EOF the command can react to.
+                        stdio: ['ignore', 'pipe', 'pipe'],
                     });
                 }
                 catch (err) {
                     resolvePromise(errorResult(err instanceof Error ? err.message : String(err)));
                     return;
                 }
+                const releaseForeground = trackForeground(supervisor, child.pid);
                 let output = '';
-                let killedByTimeout = false;
                 let settled = false;
-                const finish = (fn) => {
+                let drainTimer;
+                let graceTimer;
+                let selfTimer;
+                /**
+                 * WHY the child is being killed, when it is.
+                 *
+                 * THE FLAG OUTRANKS `'close'`, AND THAT ORDERING IS THE WHOLE POINT.
+                 * Killing a tree usually DOES produce a prompt `'close'`, so a `'close'`
+                 * handler that rendered the ordinary `[signal SIGTERM]` body would win
+                 * the race in the common case and the honest footer would only ever be
+                 * seen in the rare one - the model would be told "the command was
+                 * signalled" instead of "the command was still running when the ceiling
+                 * fired, re-run it in the background", which is precisely the sentence
+                 * that stops it reaching for `Start-Process`. The pre-change build made
+                 * the same choice for its `killedByTimeout` flag, for the same reason.
+                 */
+                let killReason;
+                /**
+                 * The result body, from whatever is known at settle time.
+                 *
+                 * ONE BUILDER FOR ALL FIVE SETTLE PATHS, so a footer can never depend on
+                 * WHICH of them got there first - the property that makes the abort and
+                 * timeout wordings deterministic rather than a race.
+                 */
+                const buildBody = (opts) => {
+                    const body = captured();
+                    if (killReason === 'timeout') {
+                        // BYTE-IDENTICAL TO THE PRE-CHANGE BUILD for the `timeout` param.
+                        return errorResult(`Command timed out after ${params.timeout}ms.\n${body}`);
+                    }
+                    if (killReason === 'abort') {
+                        // P1-5. The captured output is the evidence the model needs, and
+                        // `ctx.abortCause` is what separates "the ceiling fired" (which earns
+                        // the advice) from "the user pressed Esc" (which does not - they did
+                        // not ask for a workaround).
+                        const footer = ctx.abortCause === 'timeout'
+                            ? '[aborted - the command was still running]\n' +
+                                'It does not look like this command terminates on its own. ' +
+                                'Re-run it with `background: true` if it is a server or a watcher.'
+                            : '[aborted]';
+                        return errorResult(`$ ${command}\n${body}\n${footer}`);
+                    }
+                    const status = opts.code === null ? `signal ${opts.signalName}` : `exit code ${opts.code}`;
+                    const note = opts.note
+                        ? '[note] the command exited but a background child is still holding its ' +
+                            'output stream.\n'
+                        : '';
+                    const text = `$ ${command}\n${body}\n${note}[${status}]`;
+                    return opts.code === 0 ? textResult(text) : errorResult(text);
+                };
+                /**
+                 * THE ONE FUNNEL. Idempotent, clears every timer, removes the abort
+                 * listener and releases the foreground registration. Five call sites;
+                 * see the module header for which ways of hanging each one closes.
+                 */
+                const settle = (build) => {
                     if (settled)
                         return;
                     settled = true;
-                    cleanup();
-                    resolvePromise(fn());
+                    if (drainTimer)
+                        clearTimeout(drainTimer);
+                    if (graceTimer)
+                        clearTimeout(graceTimer);
+                    if (selfTimer)
+                        clearTimeout(selfTimer);
+                    ctx.signal?.removeEventListener('abort', onAbort);
+                    releaseForeground();
+                    resolvePromise(build());
+                };
+                const captured = () => (output.length > 0 ? output : '(no output)');
+                /**
+                 * Arm the post-kill force-settle. AT MOST ONCE.
+                 *
+                 * Both kill paths reach it and the executor's ceiling aborts through
+                 * `ctx.signal` a moment after the tool's own timer fires, so a plain
+                 * assignment would overwrite a pending timer with a second one — and
+                 * `settle` clears only the reference it can see, leaving the orphan to
+                 * hold the loop for another `killGraceMs` after the promise resolved.
+                 */
+                const armGrace = () => {
+                    if (graceTimer)
+                        return;
+                    graceTimer = setTimeout(() => {
+                        settle(() => buildBody({ code: null, signalName: null }));
+                    }, PROC_LIMITS.killGraceMs);
                 };
                 // Self-timer for the `timeout` param (shrinks within the executor ceiling).
-                let timer;
                 if (params.timeout && params.timeout > 0) {
-                    timer = setTimeout(() => {
-                        killedByTimeout = true;
-                        killTree(child);
+                    selfTimer = setTimeout(() => {
+                        killReason = 'timeout';
+                        killTree(child.pid, 'SIGKILL');
+                        // THE SAME GRACE THE ABORT PATH USES. Killing is not settling: a
+                        // detached grandchild can hold the pipe open past the kill, and the
+                        // old build then waited for a `'close'` that never came.
+                        armGrace();
                     }, params.timeout);
                 }
-                // Cooperative cancellation via the executor/agent AbortSignal.
+                /**
+                 * Cooperative cancellation via the executor/agent AbortSignal.
+                 *
+                 * THE FORCE-SETTLED BODY CARRIES THE CAPTURED OUTPUT AND NAMES THE CAUSE
+                 * (P1-5), and that is not a nicety. Today an abort kills the tree,
+                 * `'close'` fires, and the model receives `$ cmd`, everything printed,
+                 * and `[signal SIGTERM]`. The executor's own ceiling
+                 * (`DEFAULT_TOOL_TIMEOUT_MS`) aborts through this SAME signal — so a bare
+                 * `Command aborted.` would hand the model three words and no evidence at
+                 * exactly the moment it needs to learn that the command does not
+                 * terminate, which is the evidence that makes it reach for
+                 * `background: true` instead of `Start-Process`.
+                 *
+                 * `ctx.abortCause` is what separates the two: `'timeout'` earns the
+                 * advice, `'external'` (an Esc) does not — the user did not ask the model
+                 * for a workaround.
+                 */
                 const onAbort = () => {
-                    killTree(child);
+                    // NOT OVERWRITTEN when a `timeout` kill is already in force: the
+                    // executor's ceiling aborts through this same signal a moment after
+                    // the tool's own timer fired, and the `timeout` wording is the more
+                    // specific of the two.
+                    killReason ??= 'abort';
+                    killTree(child.pid, 'SIGKILL');
+                    armGrace();
                 };
                 ctx.signal?.addEventListener('abort', onAbort, { once: true });
-                function cleanup() {
-                    if (timer)
-                        clearTimeout(timer);
-                    ctx.signal?.removeEventListener('abort', onAbort);
-                }
                 // `output` IS UNTOUCHED BY THE RECORDER, and that is what makes AC-30
                 // checkable by comparison rather than by inspection: the string the
                 // model receives, its truncation and the `[exit code N]` footer are all
@@ -129,19 +343,75 @@ export function makeBash(deps) {
                     deps.recordOutput?.(id, s);
                 });
                 child.on('error', (err) => {
-                    finish(() => errorResult(`Failed to run command: ${err.message}`));
+                    settle(() => errorResult(`Failed to run command: ${err.message}`));
                 });
-                child.on('close', (code, signalName) => {
-                    const trimmed = output.length > 0 ? output : '(no output)';
-                    if (killedByTimeout) {
-                        finish(() => errorResult(`Command timed out after ${params.timeout}ms.\n${trimmed}`));
+                /**
+                 * DEFENCE 1. `'exit'` fires when the PROCESS ends; `'close'` waits for
+                 * every stdio stream, which a detached grandchild can hold open forever.
+                 * So `'exit'` starts a short drain and `'close'` — if it arrives — wins
+                 * the race and produces the byte-identical happy-path body.
+                 */
+                child.on('exit', (code, signalName) => {
+                    if (settled || drainTimer)
                         return;
-                    }
-                    const status = code === null ? `signal ${signalName}` : `exit code ${code}`;
-                    const body = `$ ${command}\n${trimmed}\n[${status}]`;
-                    finish(() => (code === 0 ? textResult(body) : errorResult(body)));
+                    drainTimer = setTimeout(() => {
+                        settle(() => buildBody({ code, signalName, note: true }));
+                    }, PROC_LIMITS.drainMs);
+                });
+                child.on('close', (code, signalName) => {
+                    settle(() => buildBody({ code, signalName }));
                 });
             });
         },
     });
 }
+/**
+ * Start a supervised service and return as soon as there is something true to
+ * say (D-3).
+ *
+ * THE FIRST OF THREE: ready, exit, or `startupSettleMs`. Never later. A 400 ms
+ * crash is reported in 400 ms with the stack in the tool result, and a slow
+ * server never costs more than the settle window of turn time.
+ *
+ * IT DOES NOT CALL `deps.recordOutput` (P2-9). The tool call settles within the
+ * window and `tool_execution_end` then clears the live-output slot, so a tail
+ * written there would flash and vanish; the `ServiceCard` owns this service's
+ * output for its whole life and is the only surface that can keep it.
+ */
+async function runBackground(supervisor, args) {
+    const started = await supervisor.start({
+        command: args.command,
+        cwd: args.cwd,
+        toolCallId: args.toolCallId,
+    });
+    if (!started.ok || !started.service) {
+        return errorResult(started.error ?? 'Could not start the background service.');
+    }
+    const id = started.service.id;
+    const settled = await new Promise((resolve) => {
+        let done = false;
+        const finish = (snapshot) => {
+            if (done)
+                return;
+            done = true;
+            unsubscribe();
+            clearTimeout(timer);
+            resolve(snapshot);
+        };
+        const unsubscribe = supervisor.subscribe((event) => {
+            if (event.service.id !== id)
+                return;
+            if (event.type === 'ready' || event.type === 'exited' || event.type === 'stopped') {
+                finish(event.service);
+            }
+        });
+        const timer = setTimeout(() => finish(supervisor.get(id) ?? started.service), args.settleMs);
+        timer.unref?.();
+        // A service that finished between `start()` and this subscription (a crash
+        // inside 1 ms is not hypothetical) would otherwise wait out the whole window.
+        const now = supervisor.get(id);
+        if (now && now.status !== 'starting')
+            finish(now);
+    });
+    return renderServiceResult(settled, { ephemeral: args.ephemeral });
+}

package/dist/tools/fs-tools.d.ts

@@ -8,6 +8,7 @@
  */
 import { type AgentTool } from '@aragon-agent/core';
 import { type FilePatch } from './patch.js';
+import type { ProcSupervisorPort } from '../proc/types.js';
 export interface ToolDeps {
     getCwd: () => string;
     /**
@@ -35,6 +36,22 @@ export interface ToolDeps {
      * name, so a future long-running tool costs one call site.
      */
     recordOutput?: (toolCallId: string, chunk: string) => void;
+    /**
+     * The process supervisor, when background launches are on for this session
+     * (background-service-supervision §3.5).
+     *
+     * THE TWO-INTERFACE RULE ABOVE APPLIES VERBATIM, and this package has already
+     * made that mistake twice (`recordChange` in round 1, `recordOutput` in round
+     * 2): adding the field HERE alone type-checks and forwards nothing, so `bash`
+     * never sees a supervisor, every long-running command runs in the foreground
+     * exactly as it does today, and NOTHING ANYWHERE ERRORS. It must be added here
+     * AND forwarded in `tools/index.ts`.
+     *
+     * OPTIONAL: omitting it leaves `bash` byte-identical to the pre-feature build —
+     * no `background` property in its schema, no supervisor call, and the
+     * pre-feature description string (I-2).
+     */
+    procs?: ProcSupervisorPort;
 }
 export declare function makeReadFile(deps: ToolDeps): AgentTool;
 export declare function makeWriteFile(deps: ToolDeps): AgentTool;

package/dist/tools/index.d.ts

@@ -12,6 +12,7 @@ import { type AgentTool, type ToolPolicyDecision, type ToolPolicyVerdict } from
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { ToolPermission } from '../exec/permission.js';
 import type { FilePatch } from './patch.js';
+import type { ProcSupervisorPort } from '../proc/types.js';
 export interface ConfirmRequest {
     tool: string;
     summary: string;
@@ -151,6 +152,58 @@ export interface BuiltinToolsOptions {
      * `--no-skills` is.
      */
     teamTools?: AgentTool[];
+    /**
+     * The process supervisor (background-service-supervision §3.5).
+     *
+     * THE TWO-INTERFACE RULE: it is declared on `ToolDeps` as well, and adding it
+     * to only one of the two type-checks and forwards nothing — `bash` never sees
+     * a supervisor and every long-running command keeps hanging, with nothing
+     * anywhere erroring. Both, or neither.
+     *
+     * The conditional spread below is what makes I-2 true at this layer: with
+     * background services off the controller passes no key, so no property is
+     * added and `deps` is the object it is today.
+     */
+    procs?: ProcSupervisorPort;
+    /**
+     * `bash_output` / `bash_kill`, appended verbatim.
+     *
+     * THROUGH THE FACTORY FOR THE REASON `teamTools` AND `todoTools` EACH RECORD
+     * IN CAPITALS (P0-2): `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals
+     * what this factory PRODUCES, so appending these two in `AgentController`
+     * after the factory returned would turn C7 red with a message about two lists
+     * of names that says nothing about background services.
+     *
+     * An empty array (`bash.background: false`) leaves the tool list
+     * byte-identical to the pre-feature build — I-2, provable by object identity
+     * exactly as `--no-skills` and `--no-team` are.
+     */
+    procTools?: AgentTool[];
+    /**
+     * `cfg.bash.autoBackground`, READ AT CALL TIME.
+     *
+     * Never cached: `aragon config set bash.autoBackground false` takes effect in
+     * the running session, and a cached `true` would go on backgrounding commands
+     * the user just told it not to.
+     */
+    autoBackground?: () => boolean;
+    /** `cfg.bash.startupSettleMs`, read at call time for the same reason. */
+    startupSettleMs?: () => number;
+    /**
+     * Whether this session can render a service card and keep a service alive
+     * (D-15 / P1-8).
+     *
+     * FALSE UNDER `aragon exec` AND `-p`. It suppresses only the CLASSIFIER: an
+     * explicit `background: true` is still honoured, and its result then says the
+     * service dies with the run. Without it `aragon -p "npm run dev"` would
+     * background a server, return in `startupSettleMs`, and reap it at process
+     * exit with nothing anywhere saying so.
+     *
+     * It is the SAME SIGNAL `planTools` already uses to decide that no overlay can
+     * be rendered, so this costs one boolean rather than a new capability probe.
+     * Absent means interactive, which is what every existing caller is.
+     */
+    interactive?: boolean;
     /**
      * Tool names that skip the CEILING wrapper only (never the plan gate, never
      * confirmation).
@@ -199,7 +252,7 @@ export interface BuiltinToolsOptions {
  * is the whole of what this mechanism is worth, and saying so plainly beats
  * implying it covers more.
  */
-export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task", "todo_write"];
+export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task", "todo_write", "bash_output"];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
  * within `HOST_TOOL_NAMES` — "the five that change something", the set this file
@@ -232,5 +285,5 @@ export declare const PLAN_MODE_BLOCKED_TOOLS: ReadonlySet<string>;
  * declaration MEANS, and that reading must not change with how the CLI was
  * started.
  */
-export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "task"];
+export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "bash_output", "bash_kill", "task"];
 export declare function createBuiltinTools(options: BuiltinToolsOptions): AgentTool[];

package/dist/tools/index.js

@@ -59,6 +59,12 @@ export const SKILL_TOOL_FLOOR = [
     // inside that skill's frame — the identical dead end that put `ask_user` /
     // `submit_plan` / `task` here.
     'todo_write',
+    // `bash_output` joins the FLOOR rather than the blocked set (D-12), and the
+    // partition test below is what forces that choice to be conscious. It READS A
+    // BUFFER: it cannot write to disk or run a shell, which is the floor's stated
+    // membership test. Blocking it in plan mode would also let the agent start a
+    // service it then could not read — the dead end the floor exists to prevent.
+    'bash_output',
 ];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
@@ -77,6 +83,11 @@ export const PLAN_MODE_BLOCKED_TOOLS = new Set([
     'bash',
     'skill_install',
     'skill_create',
+    // `bash_kill` joins the BLOCKED set (D-12). It TERMINATES A PROCESS, which is
+    // a mutation of the world and the complement's stated membership test. Nothing
+    // is dead-ended by it: `Ctrl+C` and `/bg stop` both remain available to the
+    // USER in plan mode, so the person can always stop what the agent started.
+    'bash_kill',
 ]);
 /**
  * Every tool name this host CAN register (7 built-ins + 4 skill tools).
@@ -113,6 +124,13 @@ export const HOST_TOOL_NAMES = [
     'ask_user',
     'submit_plan',
     'todo_write',
+    // Both names are here even though `bash.background: false` registers NEITHER,
+    // and that is the constant's documented meaning rather than an inconsistency:
+    // it is the SUPERSET of what this host CAN register, answering "can a skill's
+    // `allowed-tools` declaration ever take effect?" — the same relationship
+    // `skills doctor` already has with `--no-skills`.
+    'bash_output',
+    'bash_kill',
     // `team_send` / `team_wait` are DELIBERATELY ABSENT (P2-5). This constant
     // answers "can a skill's `allowed-tools` declaration ever take effect?", and
     // those two are never registered on a lead — so a skill naming them genuinely
@@ -221,6 +239,10 @@ export function createBuiltinTools(options) {
         ...(options.recordChange ? { recordChange: options.recordChange } : {}),
         // Added in the same shape and for the same reason (P1-1).
         ...(options.recordOutput ? { recordOutput: options.recordOutput } : {}),
+        // And the third, in the same shape and for the same reason. The FORWARD half
+        // of the two-interface note on `procs` above: without this line the field is
+        // on both interfaces, nothing errors, and `bash` still hangs.
+        ...(options.procs ? { procs: options.procs } : {}),
     };
     let tools = [
         makeReadFile(deps),
@@ -229,7 +251,18 @@ export function createBuiltinTools(options) {
         makeListDir(deps),
         makeGlob(deps),
         makeGrep(deps),
-        makeBash(deps),
+        // The second argument is spread CONDITIONALLY on the supervisor being
+        // present, so with background services off `makeBash` receives its default
+        // `{}` and produces the pre-feature tool: no `background` property in the
+        // schema, the pre-feature description string, no supervisor call (I-2).
+        makeBash(deps, options.procs
+            ? {
+                supervisor: options.procs,
+                ...(options.autoBackground ? { autoBackground: options.autoBackground } : {}),
+                ...(options.startupSettleMs ? { startupSettleMs: options.startupSettleMs } : {}),
+                ...(options.interactive !== undefined ? { interactive: options.interactive } : {}),
+            }
+            : {}),
     ];
     if (options.confirmTools && options.confirm) {
         const confirm = options.confirm;
@@ -246,6 +279,11 @@ export function createBuiltinTools(options) {
     if (options.todoTools && options.todoTools.length > 0) {
         tools = [...tools, ...options.todoTools];
     }
+    // AFTER `todoTools`, BEFORE `teamTools`, so a lead's `task` stays last and
+    // `HOST_TOOL_NAMES` changes by two insertions rather than a reshuffle.
+    if (options.procTools && options.procTools.length > 0) {
+        tools = [...tools, ...options.procTools];
+    }
     // BEFORE both wrappers, so the lead's `task` is covered by the plan gate and
     // the ceiling like everything else, and a child's comm tools are covered by
     // everything except the ceiling (see `policyExempt`).