@armadra/agent 0.4.0 → 0.5.0

package/dist/skills/builtin.js

@@ -0,0 +1,109 @@
+/**
+ * 内置 Skill（替代把 ama 自身文档塞进系统提示）。
+ *
+ * 系统提示里只常驻索引的一条（名字 + 一句描述，约 60 token），正文按需读取。单文件 bundle 没有
+ * docs 目录，所以正文是内联的配置速查（≤ 3 KB），会话发现时写到 `<dataDir>/builtin/<名>.md`（路径短，进前缀）
+ * （内容不变不重写），模型用 read 读、用户用 `/skill:ama-docs` 调用都走现成路径。
+ *
+ * - 排在全部用户 / 项目 Skill 之后：同名时用户的优先，内置的静默让位（不报重名 warning）。
+ * - 路径只取决于数据目录，会话开始时确定、会话内不变，不影响前缀稳定（设计 §9.1）。
+ * - 写盘失败只记 warning 并跳过该内置 Skill。
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export const BUILTIN_SKILLS_DIR = "builtin";
+const AMA_DOCS_BODY = `# ama quick reference
+
+ama is the coding agent running this session. Docs: https://github.com/Owlbay/armadra-agent (README.md, docs/).
+
+## Files
+- User config dir \`~/.config/ama/\` (\`AMA_CONFIG_DIR\`; Windows \`%APPDATA%\\ama\`): \`config.json\`, \`auth.json\` (keys, 0600), \`hooks.json\`, \`keybindings.json\`, \`trust.json\`, \`AGENTS.md\`, \`skills/\`, \`prompts/\`.
+- Data dir \`~/.local/share/ama/\` (\`AMA_DATA_DIR\`): \`sessions/\` (JSONL), \`models-dev.json\`.
+- Project: \`AGENTS.md\` (found upward from cwd), \`.ama/config.json\` (can only tighten), \`.ama/hooks.json\`, \`.ama/skills/\`, \`.ama/prompts/\` (need trust).
+- Merge order: defaults < user < profile < project. \`ama config show\` prints effective values and sources; \`ama config path\`, \`ama config edit\`, \`ama doctor\`.
+
+## config.json (common keys)
+\`\`\`json
+{ "version": 1, "defaultModel": "provider/model-id", "thinkingLevel": "medium",
+  "permission": { "mode": "default", "allow": ["bash(git status*)"], "deny": ["write(**/.env*)"] },
+  "tools": { "preset": "default", "default": ["+task", "-glob"] }, "providers": {} }
+\`\`\`
+Other sections have defaults: compaction, retry, codemode, hooks, ui, skills, cache, request.
+
+## Providers and models
+- Zero config: set a standard key env var (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, ...). \`OPENAI_BASE_URL\` / \`ANTHROPIC_BASE_URL\` are honored.
+- Store a key: \`ama auth set <provider>\` (reads stdin), \`ama auth list\`, \`ama auth remove <provider>\`. Never put keys in config; use \`"apiKey": "$ENV_VAR"\` or \`"!command"\`.
+- Relay / custom endpoint: \`ama providers add <name> --base-url <url> --key-env VAR --probe\`; models may set \`"api"\`: openai-completions | openai-responses | anthropic-messages | google-generative-ai.
+- \`ama models list\`, \`ama models discover <provider>\`, \`ama models check provider/model\`. Model refs are \`provider/model[@channel]\`; switch with \`--model\` or \`/model\`.
+
+## Permissions
+Modes (\`--permission-mode\`, \`permission.mode\`, \`/permission\`, Shift+Tab): plan, default (ask for writes and commands), auto-edit, auto, full-auto, allowlist. Rules like \`bash(git push*)\`, \`write(src/**)\`; \`--allow\` / \`--deny\`. Dangerous commands always ask. Unattended runs (-p, RPC) treat "ask" as deny.
+
+## Tools
+Presets (\`--tools-preset\`, \`tools.preset\`): default, minimal, codemode-only, coordinator. \`/tools\` toggles tools; \`--codemode off|on|only\`.
+
+## Sessions and rewind
+- \`-c\` continues the latest session here, \`-r [id]\` resumes; \`/resume\`, \`/new\`, \`/fork\`, \`/tree\`, \`/compact\`.
+- \`/rewind\` (or Esc Esc when idle) returns to before a user message: both, conversation only, or code only (edit/write checkpoints).
+- \`ama sessions search|show|export\`, \`ama stats\`.
+
+## Skills and hooks
+Skills: \`<dir>/<name>/SKILL.md\` with \`name\` and \`description\` frontmatter in \`~/.config/ama/skills/\` or \`.ama/skills/\`; invoke with \`/skill:<name>\`. Hooks: \`hooks.json\` runs commands on PreToolUse, PostToolUse, UserPromptSubmit, Stop and more.
+`;
+export const BUILTIN_SKILLS = Object.freeze([
+    {
+        name: "ama-docs",
+        description: "How to configure and use ama itself.",
+        body: AMA_DOCS_BODY,
+    },
+]);
+export function builtinSkillPath(dataDir, name) {
+    return join(dataDir, BUILTIN_SKILLS_DIR, `${name}.md`);
+}
+/** 是否内置 Skill（启动头的「已加载」只数用户 / 项目的）。 */
+export function isBuiltinSkill(skill) {
+    return (BUILTIN_SKILLS.some((b) => b.name === skill.name) &&
+        skill.location.endsWith(join(BUILTIN_SKILLS_DIR, `${skill.name}.md`)));
+}
+export function builtinSkillText(skill) {
+    return `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\n${skill.body}`;
+}
+async function ensureFile(path, text) {
+    try {
+        if ((await readFile(path, "utf8")) === text)
+            return;
+    }
+    catch {
+        // 不存在：下面写
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, text, "utf8");
+}
+/** 在已发现的 Skill 之后追加内置 Skill（同名让位给已有的）；返回新数组与 warning。 */
+export async function withBuiltinSkills(skills, dataDir, builtins = BUILTIN_SKILLS) {
+    const out = [...skills];
+    const warnings = [];
+    const taken = new Set(skills.map((skill) => skill.name));
+    for (const builtin of builtins) {
+        if (taken.has(builtin.name))
+            continue;
+        const baseDir = join(dataDir, BUILTIN_SKILLS_DIR);
+        const location = builtinSkillPath(dataDir, builtin.name);
+        try {
+            await ensureFile(location, builtinSkillText(builtin));
+        }
+        catch (error) {
+            warnings.push(`内置 Skill ${builtin.name} 写入失败：${error.message}`);
+            continue;
+        }
+        out.push({
+            name: builtin.name,
+            description: builtin.description,
+            location,
+            baseDir,
+            disableModelInvocation: false,
+            scope: "builtin",
+        });
+    }
+    return { skills: out, warnings };
+}

package/dist/skills/discover.d.ts

@@ -10,7 +10,8 @@
  * frontmatter：`name`（≤ 64，`^[a-z0-9-]+$`，缺省取目录名）、`description`（必填，≤ 1024）、
  * `disable-model-invocation`、`allowed-tools`（只做提示）。
  */
-export type SkillScope = "cli" | "profile" | "config" | "user" | "project" | "ancestor";
+/** `builtin`：随 ama 分发的内置 Skill（builtin.ts），排在最后，同名让位。 */
+export type SkillScope = "cli" | "profile" | "config" | "user" | "project" | "ancestor" | "builtin";
 export interface SkillSource {
     dir: string;
     scope: SkillScope;

package/dist/skills/index-prompt.js

@@ -18,24 +18,21 @@ export function formatSkillIndex(skills, options) {
         return "";
     let how;
     if (options.hasSkillTool) {
-        how =
-            "Call the skill tool with a skill's name to load it when the task matches its description.";
+        how = "call the skill tool with its name";
     }
     else if (options.hasReadTool) {
-        how = "Use the read tool to load a skill's file when the task matches its description.";
+        how = "read its file";
     }
     else {
         return "";
     }
+    // 每个字都进缓存前缀（预算见 src/cli/prompt-budget.test.ts），说明保持一行。
     const lines = [
-        "The following skills provide specialized instructions for specific tasks.",
-        how,
-        "When a skill file references a relative path, resolve it against the skill's directory.",
-        "",
+        `Skills: when a task matches one, ${how} first; resolve its relative paths against its directory.`,
         "<available_skills>",
     ];
     for (const s of visible) {
-        lines.push("  <skill>", `    <name>${escapeXml(s.name)}</name>`, `    <description>${escapeXml(s.description)}</description>`, `    <location>${escapeXml(s.location)}</location>`, "  </skill>");
+        lines.push(`<skill name="${escapeXml(s.name)}" location="${escapeXml(s.location)}">${escapeXml(s.description)}</skill>`);
     }
     lines.push("</available_skills>");
     return lines.join("\n");

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

@@ -0,0 +1,71 @@
+/**
+ * 后台命令（docs/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
+ *
+ * - `start`：调用方（bash.ts）给出 `spawn(stdout)`——**进程只在 bash.ts 的 `spawnShell` 里创建**，
+ *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不
+ *   会因管道断开而 SIGPIPE）。POSIX 自成进程组并登记（进程退出时同步 SIGKILL 残留组）。
+ * - `wait(id, timeoutMs)`：等到退出或超时；`stop(id)`：杀整棵树（SIGTERM → 宽限 → SIGKILL）；
+ *   `output(id)`：读输出文件尾部（2000 行 / 50 KB）。
+ * - 生命周期事件经 `onChange` 发出（started / exited / stopped）；`takeExited()` 取走尚未通知的已退出
+ *   任务（提醒通道 reminders.ts 据此告诉模型「后台命令 jobId 已退出（码 N）」）。
+ * - 按会话 id 登记（`jobsForSession`）；`disposeSessionJobs` 在会话 dispose 时回收进程树。
+ */
+import type { ChildProcess } from "node:child_process";
+import { type ProcessDeps } from "./process-tree.js";
+import { type TruncateResult } from "./truncate.js";
+export type JobStatus = "running" | "exited" | "stopped";
+export interface Job {
+    id: string;
+    command: string;
+    cwd: string;
+    pid?: number;
+    outputPath: string;
+    startedAt: number;
+    status: JobStatus;
+    /** 退出码（信号退出为 128 + signo）；运行中 undefined。 */
+    exitCode?: number;
+    endedAt?: number;
+}
+export interface JobStartOptions {
+    cwd: string;
+    outputPath: string;
+    /** 用给定的输出文件描述符启动进程（bash.ts 的 spawnShell）。 */
+    spawn(outputFd: number): ChildProcess;
+    processDeps?: ProcessDeps;
+}
+export type JobChange = {
+    phase: "started" | "exited" | "stopped";
+    job: Job;
+};
+/** 后台 bash 的查询形状：`{ job, action: wait | stop | output }`，不带 command。 */
+export declare function isBackgroundJobQuery(toolName: string, input: unknown): boolean;
+export declare class BackgroundJobs {
+    private readonly entries;
+    private readonly listeners;
+    private seq;
+    start(command: string, options: JobStartOptions): Job;
+    get(id: string): Job | undefined;
+    list(): Job[];
+    /** 等到退出或超时（`signal` 可提前结束等待，不杀进程）。 */
+    wait(id: string, timeoutMs: number, signal?: AbortSignal): Promise<Job | undefined>;
+    stop(id: string): Promise<Job | undefined>;
+    /** 输出文件尾部（2000 行 / 50 KB）。 */
+    output(id: string): (TruncateResult & {
+        job: Job;
+    }) | undefined;
+    /** 取走已退出、尚未通知的任务（提醒通道用；wait 已看到退出的也算已知）。 */
+    takeExited(): Job[];
+    /** 标记为已知（模型已经通过 wait / output 看到了退出）。 */
+    markSeen(id: string): void;
+    onChange(listener: (change: JobChange) => void): () => void;
+    get running(): number;
+    /** 杀掉全部仍在运行的任务（会话 dispose）。 */
+    disposeAll(): Promise<void>;
+    private notify;
+}
+/** 会话的后台任务表（按会话 id，首次使用时建）。 */
+export declare function jobsForSession(sessionId: string): BackgroundJobs;
+/** 已有的任务表（不新建）。 */
+export declare function existingJobs(sessionId: string): BackgroundJobs | undefined;
+/** 会话 dispose：杀掉该会话仍在运行的后台任务并注销。 */
+export declare function disposeSessionJobs(sessionId: string): Promise<void>;

package/dist/tools/background-jobs.js

@@ -0,0 +1,198 @@
+/**
+ * 后台命令（docs/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
+ *
+ * - `start`：调用方（bash.ts）给出 `spawn(stdout)`——**进程只在 bash.ts 的 `spawnShell` 里创建**，
+ *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不
+ *   会因管道断开而 SIGPIPE）。POSIX 自成进程组并登记（进程退出时同步 SIGKILL 残留组）。
+ * - `wait(id, timeoutMs)`：等到退出或超时；`stop(id)`：杀整棵树（SIGTERM → 宽限 → SIGKILL）；
+ *   `output(id)`：读输出文件尾部（2000 行 / 50 KB）。
+ * - 生命周期事件经 `onChange` 发出（started / exited / stopped）；`takeExited()` 取走尚未通知的已退出
+ *   任务（提醒通道 reminders.ts 据此告诉模型「后台命令 jobId 已退出（码 N）」）。
+ * - 按会话 id 登记（`jobsForSession`）；`disposeSessionJobs` 在会话 dispose 时回收进程树。
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { exitCodeOf, isGroupAlive, killProcessTree, trackProcessGroup, untrackProcessGroup, } from "./process-tree.js";
+import { truncateTail } from "./truncate.js";
+/** 后台 bash 的查询形状：`{ job, action: wait | stop | output }`，不带 command。 */
+export function isBackgroundJobQuery(toolName, input) {
+    if (toolName !== "bash" || typeof input !== "object" || input === null)
+        return false;
+    const record = input;
+    return typeof record.job === "string" && record.command === undefined;
+}
+export class BackgroundJobs {
+    entries = new Map();
+    listeners = new Set();
+    seq = 0;
+    start(command, options) {
+        mkdirSync(dirname(options.outputPath), { recursive: true });
+        const fd = openSync(options.outputPath, "a");
+        let child;
+        try {
+            child = options.spawn(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const id = `bg${++this.seq}`;
+        const job = {
+            id,
+            command,
+            cwd: options.cwd,
+            outputPath: options.outputPath,
+            startedAt: Date.now(),
+            status: "running",
+        };
+        if (child.pid !== undefined)
+            job.pid = child.pid;
+        const isWindows = (options.processDeps?.platform ?? process.platform) === "win32";
+        if (job.pid !== undefined && !isWindows)
+            trackProcessGroup(job.pid);
+        const entry = {
+            job,
+            notified: false,
+            stopping: false,
+            processDeps: options.processDeps,
+            done: new Promise((resolve) => {
+                const finish = (code, signal) => {
+                    if (job.status !== "running")
+                        return resolve();
+                    job.exitCode = exitCodeOf(code, signal);
+                    job.endedAt = Date.now();
+                    job.status = entry.stopping ? "stopped" : "exited";
+                    const pid = job.pid;
+                    if (pid !== undefined && !isWindows && !isGroupAlive(pid, options.processDeps ?? {}))
+                        untrackProcessGroup(pid);
+                    this.notify({ phase: job.status === "stopped" ? "stopped" : "exited", job });
+                    resolve();
+                };
+                child.once("exit", finish);
+                child.once("error", () => finish(127, null));
+            }),
+        };
+        child.unref();
+        this.entries.set(id, entry);
+        this.notify({ phase: "started", job });
+        return job;
+    }
+    get(id) {
+        return this.entries.get(id)?.job;
+    }
+    list() {
+        return [...this.entries.values()].map((entry) => entry.job);
+    }
+    /** 等到退出或超时（`signal` 可提前结束等待，不杀进程）。 */
+    async wait(id, timeoutMs, signal) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return undefined;
+        if (entry.job.status !== "running")
+            return entry.job;
+        let timer;
+        let onAbort;
+        await Promise.race([
+            entry.done,
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, Math.max(0, timeoutMs));
+                onAbort = () => resolve();
+                signal?.addEventListener("abort", onAbort, { once: true });
+            }),
+        ]);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort !== undefined)
+            signal?.removeEventListener("abort", onAbort);
+        return entry.job;
+    }
+    async stop(id) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return undefined;
+        if (entry.job.status !== "running")
+            return entry.job;
+        entry.stopping = true;
+        // 已经由调用方知道结果：停止的任务不再经提醒通道通知
+        entry.notified = true;
+        if (entry.job.pid !== undefined)
+            await killProcessTree(entry.job.pid, entry.processDeps);
+        await entry.done;
+        return entry.job;
+    }
+    /** 输出文件尾部（2000 行 / 50 KB）。 */
+    output(id) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return undefined;
+        let text = "";
+        try {
+            if (statSync(entry.job.outputPath).size > 0)
+                text = readFileSync(entry.job.outputPath, "utf8");
+        }
+        catch {
+            // 输出文件被删：按空输出
+        }
+        return { ...truncateTail(text), job: entry.job };
+    }
+    /** 取走已退出、尚未通知的任务（提醒通道用；wait 已看到退出的也算已知）。 */
+    takeExited() {
+        const out = [];
+        for (const entry of this.entries.values()) {
+            if (entry.job.status === "running" || entry.notified)
+                continue;
+            entry.notified = true;
+            out.push(entry.job);
+        }
+        return out;
+    }
+    /** 标记为已知（模型已经通过 wait / output 看到了退出）。 */
+    markSeen(id) {
+        const entry = this.entries.get(id);
+        if (entry !== undefined && entry.job.status !== "running")
+            entry.notified = true;
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    get running() {
+        return this.list().filter((job) => job.status === "running").length;
+    }
+    /** 杀掉全部仍在运行的任务（会话 dispose）。 */
+    async disposeAll() {
+        await Promise.all([...this.entries.keys()].map((id) => this.stop(id).catch(() => undefined)));
+        this.listeners.clear();
+    }
+    notify(change) {
+        for (const listener of this.listeners) {
+            try {
+                listener(change);
+            }
+            catch {
+                // 监听器异常不影响任务
+            }
+        }
+    }
+}
+const registry = new Map();
+/** 会话的后台任务表（按会话 id，首次使用时建）。 */
+export function jobsForSession(sessionId) {
+    let jobs = registry.get(sessionId);
+    if (jobs === undefined) {
+        jobs = new BackgroundJobs();
+        registry.set(sessionId, jobs);
+    }
+    return jobs;
+}
+/** 已有的任务表（不新建）。 */
+export function existingJobs(sessionId) {
+    return registry.get(sessionId);
+}
+/** 会话 dispose：杀掉该会话仍在运行的后台任务并注销。 */
+export async function disposeSessionJobs(sessionId) {
+    const jobs = registry.get(sessionId);
+    if (jobs === undefined)
+        return;
+    registry.delete(sessionId);
+    await jobs.disposeAll();
+}

package/dist/tools/bash.d.ts

@@ -7,17 +7,43 @@
  * - 结构化结果 `{ output, exit_code, truncated, full_output_path?, wall_time_seconds }`；
  *   信号退出 `128 + signo`；非零退出码 → isError；
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
+ * - [W5-H2] 后台命令（§8.3 H6，不加新工具）：`{ command, background: true }` 立即返回
+ *   `{ jobId, outputPath, pid }`；`{ job, action: "wait" | "output" | "stop" }` 查询 / 结束
+ *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。
+ * - **进程只在 `spawnShell` 里创建**（前台与后台共用）。[S2] `sandbox.bash: auto` 且有能限制写入的
+ *   OS 沙箱时在这一处包一层（src/sandbox/bash.ts）；`sandbox: false` 不包装（权限管线照常审批）。
+ *   失败输出像是被沙箱拒绝时末尾追加一行说明。
  */
+import { type ChildProcess } from "node:child_process";
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 import { type ShellConfig } from "./shell.js";
 import { type ProcessDeps } from "./process-tree.js";
+import { type BackgroundJobs } from "./background-jobs.js";
+import { type BashCallPlace, type BashSandbox } from "../sandbox/bash.js";
 export declare const DEFAULT_BASH_TIMEOUT_MS = 120000;
 export declare const MAX_BASH_TIMEOUT_MS = 600000;
 export interface BashInput {
-    command: string;
+    /** 前台 / 后台命令；查询后台任务时不给。 */
+    command?: string;
     timeoutMs?: number;
     cwd?: string;
     description?: string;
+    /** [W5-H2] 后台运行：立即返回 jobId。 */
+    background?: boolean;
+    /** [W5-H2] 后台任务 id（与 action 一起用）。 */
+    job?: string;
+    action?: "wait" | "output" | "stop";
+    /** [S2] false：不经 OS 沙箱运行（走正常审批）。只在沙箱生效时出现在 schema 里。 */
+    sandbox?: boolean;
+}
+/** [W5-H2] `wait` 的缺省等待（毫秒）。 */
+export declare const DEFAULT_JOB_WAIT_MS = 30000;
+export interface BackgroundStart {
+    jobId: string;
+    outputPath: string;
+    pid?: number;
+    /** [S2] 经 OS 沙箱运行。 */
+    sandboxed?: true;
 }
 export interface BashStructured {
     output: string;
@@ -25,6 +51,8 @@ export interface BashStructured {
     truncated: boolean;
     full_output_path?: string;
     wall_time_seconds: number;
+    /** [S2] 经 OS 沙箱运行。 */
+    sandboxed?: true;
 }
 export interface BashDetails extends BashStructured {
     timedOut: boolean;
@@ -44,6 +72,30 @@ export interface BashToolOptions {
     processDeps?: ProcessDeps;
     /** 测试注入：基础环境，缺省 process.env。 */
     baseEnv?(): NodeJS.ProcessEnv;
+    /** 测试注入：会话的后台任务表，缺省按会话 id 登记（background-jobs.ts）。 */
+    jobs?(sessionId: string): BackgroundJobs;
+    /** [S2] bash 的 OS 沙箱设定（组装时算一次，会话内不变）；缺省不用沙箱。 */
+    sandbox?: BashSandbox;
+}
+export interface SpawnShellOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** POSIX 自成进程组（杀树用）；Windows 为 false。 */
+    detached: boolean;
+    /** 前台 `["ignore", "pipe", "pipe"]`；后台把输出文件描述符直接交给子进程。 */
+    stdio: ["ignore", "pipe" | number, "pipe" | number];
+    /** [S2] 经 OS 沙箱运行：设定与这次调用的位置（工作区、输出目录）。 */
+    sandbox?: {
+        settings: BashSandbox;
+        place: BashCallPlace;
+    };
 }
+/**
+ * bash 工具唯一的进程创建点（前台 / 后台共用）；[S2] 给了 `sandbox` 时经 OS 沙箱包装（包不上抛错，
+ * 不悄悄裸跑）。
+ */
+export declare function spawnShell(shell: ShellConfig, command: string, options: SpawnShellOptions): ChildProcess;
 export declare function executeBash(input: BashInput, ctx: ToolContext, options?: BashToolOptions): Promise<ToolResult>;
+/** [S2] 沙箱生效时追加到描述末尾的一句（会话内不变）。 */
+export declare function sandboxDescription(sandbox: BashSandbox | undefined): string;
 export declare function createBashTool(options?: BashToolOptions): ToolDefinition<BashInput>;