autoclaw 1.3.4 → 1.3.6

package/README.zh-CN.md

@@ -4,6 +4,7 @@
 [![NPM Downloads](https://img.shields.io/npm/dm/autoclaw.svg?style=flat-square)](https://www.npmjs.com/package/autoclaw)
 [![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github&style=flat-square)](https://github.com/tsingliuwin/autoclaw)
 [![License](https://img.shields.io/npm/l/autoclaw.svg?style=flat-square)](https://github.com/tsingliuwin/autoclaw/blob/main/LICENSE)
+[![Safety](https://img.shields.io/badge/Safety-Notice-yellow?style=flat-square)](./SAFETY.md)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 
 **稳定、高工程化、易规模化：专为无界面系统设计的高效自动化 Agent 框架。**
@@ -34,11 +35,14 @@ AutoClaw 是一款针对 **“无界面系统” (Headless Systems)** 的高稳
 - 📜 **无头执行 (Headless Execution)**: 无需图形界面，纯终端运行。核心流程仅依赖 Shell 与文件操作；可选的网页工具在无头 Chromium 中运行。
 - 🤖 **非交互模式**: 支持自动化标志（`-y`, `--no-interactive`），完美适配零干预的自动化流程。
 - 📂 **全方位控制 (Universal Control)**: 从基础的文件 I/O 到复杂的系统管理。
-- 🛡️ **防失控保护**: 单任务步数上限、API 指数退避重试、Shell 命令超时、工具输出截断，保证模型上下文不被撑爆。
+- 🖥️ **后台进程**: 后台启动长期命令(开发服务器、watcher)并轮询输出,不阻塞任务运行。
+- 🛡️ **安全护栏**: 破坏性命令闸、凭据文件防线、步数上限、墙钟超时与 API 重试——为没有人看着的机器而设计。
 - 🧠 **上下文感知 (Context Aware)**: 提供精确的操作系统与时间上下文，正确处理"今天"、"下周一"等相对时间。
 - 🌐 **网页搜索**: 集成 Tavily，支持实时信息检索。
 - 🌍 **网页阅读与截图**: 提取文章正文、截取页面图片（需先执行 `npx playwright install chromium`）。
 - 🎨 **图像生成**: 通过任意 OpenAI 兼容的图像接口生成图片（兼容 DALL-E）。
+- 🖼️ **确定性图像渲染** (`render_image`): HTML + Tailwind 模板直接渲染为 PNG/JPEG/WebP/SVG,并支持动图(由 CSS `@keyframes` 采样的动画 WebP/GIF/APNG)。完全离线、无浏览器、毫秒级渲染——适合 OG 分享卡、横幅、徽章、数据卡片等对文字与排版精度有要求的场景。
+- 📄 **PDF 渲染** (`render_pdf`): HTML 模板直接渲染为分页 PDF，文字可选中、页眉页脚逐页重复、支持页码计数。完全离线、无浏览器——适合发票、报表、证书等结构化文档。
 - 🕒 **时间精准**: 内置工具获取精确系统日期和时间，确保正确的时间上下文。
 - 📧 **通讯能力**: 自动发送电子邮件并将通知推送至聊天群组。
 
@@ -49,6 +53,7 @@ AutoClaw 是一款针对 **“无界面系统” (Headless Systems)** 的高稳
 - **UI**: Inquirer (交互), Chalk (样式), Ora (加载动画)
 - **AI**: OpenAI SDK（任意 OpenAI 兼容端点：DeepSeek、Kimi、Qwen、GLM、Ollama 等）
 - **网页工具**: Playwright（无头 Chromium，用于 `read_website` / `take_screenshot`）
+- **渲染引擎**: Takumi（Rust 引擎，经原生绑定驱动 `render_image` / `render_pdf`，无需浏览器）
 
 ## 安装
 
@@ -131,6 +136,22 @@ autoclaw batch big.jsonl -y -c 4            # 最多 4 个任务并行
 
 AutoClaw 同时会自动给提示词瘦身：可选工具（网页搜索、邮件、群通知、图像生成）只在凭据配置后才会注册进工具定义；长循环中较早的工具结果会被替换为短摘要。
 
+### 技能（可移植能力包）
+AutoClaw 支持 `SKILL.md` 技能包——与 WorkBuddy 技能商店相同的格式，一份技能包既能在 AutoClaw 内运行，也能发布到其它平台。system prompt 里每个技能只占一行清单；任务匹配时 agent 才去读取该技能的 `SKILL.md` 并照做，全程走普通的文件与 shell 工具。技能没有特权运行时：脚本同样经过破坏性命令闸、沙箱与步数上限。
+
+作用域（同名后者遮蔽前者）：内置 `skills/`（随 npm 包发布）→ `~/.autoclaw/skills/` → `.autoclaw/skills/`。
+
+```bash
+autoclaw skill list                     # 列出发现的技能(含作用域与版本)
+autoclaw skill install <zip|目录|https地址>  # 安装到 ~/.autoclaw/skills/(含 zip-slip 防护)
+autoclaw skill remove <name>            # 移除用户级技能(内置技能受保护)
+autoclaw skill pack <目录>               # 打包为商店上传 zip(zip 根为 skills/<name>/)
+```
+
+安装兼容任意 SKILL.md 格式的第三方包：本地目录、本地 zip 或 https 下载地址均可。对第三方布局差异做了容错（SKILL.md 位于 zip 根部、普通文件夹、`skills/<name>/` 包装、macOS 的 `__MACOSX`/`.DS_Store` 垃圾文件），并且始终按技能 frontmatter 的 `name` 安装，保证发现与清单的一致性。
+
+内置三个技能，分层协作：[`code2media`](skills/code2media/SKILL.md)（代码转多媒体）是通用渲染引擎——独立 Node 脚本把任意 HTML 变成图片/SVG/分页 PDF/动图；[`poster-maker`](skills/poster-maker/SKILL.md)（海报生成器）与 [`invoice-maker`](skills/invoice-maker/SKILL.md)（发票生成器）是独立优化的场景技能，各自沉淀了平台尺寸表、票据版式规范与质量清单。同一个 zip 可直接发布到任何兼容 SKILL.md 的商店。技能与 batch 模式天然组合：清单里一行 `{"id":"cert-042","task":"用 invoice-maker 技能根据 orders-042.json 生成发票 invoices/042.pdf"}` 就能让一个隔离的 swarm worker 跑同一个技能。
+
 ### 实战配方
 
 Linux 定时巡检（crontab）：
@@ -170,6 +191,14 @@ autoclaw "将 src/index.ts 重构为使用 ES 模块" -y
 
 ### 诊断
 `autoclaw doctor` 无头完成全面自检,逐项打印 ✓/✗:配置文件、解析出的 provider/baseUrl/model、API key、真实连接测试、解析出的 shell、已注册工具、playwright 浏览器状态。退出 `0` = 就绪,`1` = 有关键项失败(会打印是哪项)。适合 CI 或新机器。
+
+### 沙箱
+命令执行可通过 `config.sandbox` / `AUTOCLOW_SANDBOX` 加以约束(词汇借鉴自 DeepSeek Harness):
+- `danger-full-access`(默认):命令不受约束地运行。
+- `workspace-write`:命令只能在当前工作目录和 `/tmp` 内写入。
+- `read-only`:命令无法在任何位置写入。
+
+后端:Linux 使用 bubblewrap(`apt install bubblewrap`),macOS 使用 `sandbox-exec`。**Windows 暂无后端**——非默认模式会"失败关闭"(直接拒绝命令并给出明确错误),而不是假装约束;在 Windows 上请暂用 `danger-full-access`。此词汇不约束读取与网络。
 - `--json`: 在 stdout 输出 NDJSON 事件流 (供编排器使用,配合 `-n`)。
 
 ### Provider 预设
@@ -197,6 +226,8 @@ AutoClaw 使用层级配置系统。
 - `maxSteps`: 单任务最大 LLM 轮数，超出后自动停止 (默认: `25`)。
 - `shellTimeout`: Shell 命令超时时间（毫秒）(默认: `120000`)。
 - `taskTimeoutMs`: 单任务整体墙钟超时（毫秒，默认关闭；会中断进行中的 API 调用并以 `timeout` 状态停止）。
+- `sandbox`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`；默认 `danger-full-access`）。
+- `skillsEnabled`: 设为 `false` 关闭技能系统（默认开启）。
 - `shell`: 强制 `execute_shell_command` 使用的 shell (`bash`、`powershell`、`cmd`、`sh`；默认自动检测——Windows 上优先 Git Bash > PowerShell > cmd)。
 - `tavilyApiKey`: Tavily 网页搜索的 API 密钥。
 - `smtpHost`, `smtpPort`, `smtpUser`, `smtpPass`, `smtpFrom`: SMTP 邮件设置。
@@ -218,6 +249,7 @@ AutoClaw 使用层级配置系统。
 - `AUTOCLOW_PROVIDER`: 未传 `-P` 时使用的 provider 预设。
 - `AUTOCLOW_MAX_STEPS`, `AUTOCLOW_SHELL_TIMEOUT`: 稳定性限制（单任务最大轮数；Shell 超时毫秒数）。
 - `AUTOCLOW_TASK_TIMEOUT_MS`: 单任务整体墙钟超时（毫秒）。
+- `AUTOCLOW_SANDBOX`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`）。
 - `AUTOCLOW_SHELL`: 强制 shell 命令使用的 shell (`bash`、`powershell`、`cmd`、`sh`)。
 - `AUTOCLOW_INCLUDE_USAGE`: 设为 `1`/`true` 时向 API 请求 token 用量（可选开启）。
 - `TAVILY_API_KEY`, `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASS`, `FEISHU_WEBHOOK`/`FEISHU_KEYWORD`, `DINGTALK_WEBHOOK`/`DINGTALK_KEYWORD`, `WECOM_WEBHOOK`/`WECOM_KEYWORD`: 工具凭据，可作为 setup 的替代方式。
@@ -240,6 +272,39 @@ AutoClaw 使用层级配置系统。
 内置工具为 Agent 提供当前系统时间，确保准确处理相对时间请求。
 - **示例**: "今天是几号？" 或 "提醒我下周一检查日志。"
 
+### 确定性渲染 (Takumi)
+`render_image` 将 HTML 模板渲染为精确的图像——PNG、JPEG、WebP 或矢量 SVG——全程离线，不依赖浏览器或 AI 模型。`render_pdf` 将 HTML 模板渲染为分页 PDF，文字可选中，页眉/页脚逐页重复，并支持 `<span class="pageNumber">` / `<span class="totalPages">` 页码计数。模板样式支持内联 CSS、`<style>` 块，或通过 `tw` 属性使用 Tailwind v4 工具类（`<div tw="w-full h-full bg-blue-500">`）；普通 `class` 属性仅匹配常规 CSS 选择器。两个工具都会自动探测常见系统字体（含中日韩与 Emoji）；也可通过 `font_paths` 注册指定字体文件。
+
+典型工作流——用自然语言描述任务，模板由 agent 自己编写：
+
+```bash
+# 博客 SEO:为每篇文章生成 OG 分享图
+autoclaw "读取 content/posts/ 下每篇 .md 的标题和摘要,为每篇文章渲染一张 OG 分享图(1200x630)到 public/og/" -y -n
+
+# 财务/电商:从订单表批量生成 PDF 发票并邮件发送
+autoclaw "读取 orders.csv,为每个订单生成 PDF 发票保存到 invoices/(A4,页脚带页码),然后把每张发票邮件发送给该行记录的客户邮箱" -y
+
+# 培训/HR:为学员名单批量生成结业证书
+autoclaw "读取 attendees.json,为每位学员渲染一张结业证书(1414x1000)保存到 certs/,编号从 AC-2026-0001 起" -y -n
+
+# cron/CI 定时报告:输出确定——相同输入得到完全相同的 PDF,可做校验
+autoclaw "汇总本周 nginx 访问日志,生成一页 A4 的 PDF 流量周报(含指标表格),保存为 report.pdf" -y -n
+```
+
+集群规模用 batch 模式——每个任务在隔立的 agent 中渲染:
+
+```bash
+cat > render-jobs.jsonl <<'EOF'
+{"id": "og-001", "task": "为 post-001.md 渲染 OG 分享图到 public/og/001.png"}
+{"id": "og-002", "task": "为 post-002.md 渲染 OG 分享图到 public/og/002.png"}
+EOF
+autoclaw batch render-jobs.jsonl -y -c 4
+```
+
+选型提示:需要精确文字、排版与品牌一致性(卡片、横幅、徽章、文档)时用 `render_image` / `render_pdf`;艺术创作、照片类图像用 `generate_image`。模板中的 Emoji 默认从 Twemoji CDN 在线获取,完全离线的环境请让模板保持纯文本。
+
+可运行案例与渲染效果预览:[examples/render](examples/render/README.zh-CN.md)(OG 分享卡、社媒海报、KPI 指标卡、周报 PDF、SVG 徽章、证书、动图、多页采购订单——`agent-run/` 下还有一次真实 agent 无头运行的产物)。同一能力也打包成了可移植的 [WorkBuddy 技能](skills/code2media/SKILL.md)(`code2media-skill.zip`):一个独立 Node 脚本,任何装有 Node >= 20.19 的机器都能把 HTML 渲染成图片/SVG/PDF/动图。
+
 ## Docker 支持
 
 ### 构建与运行
@@ -250,10 +315,10 @@ docker run --rm -v "$PWD":/workspace -w /workspace -e OPENAI_API_KEY=sk-... auto
 ```
 注意：默认镜像中未内置浏览器，基于浏览器的工具（`read_website` / `take_screenshot`）不可用——它们会返回友好的安装提示，而不是报错崩溃。
 
-### 截图中的中文显示问题
-在 Docker 容器（尤其是 Alpine 或 Debian Slim）中运行时，网页截图中的中文可能会显示为方块（"豆腐块"）。表情符号（如 🔥）也可能显示为方块。
+### 截图与渲染输出中的中文显示问题
+在 Docker 容器（尤其是 Alpine 或 Debian Slim）中运行时，网页截图中的中文可能会显示为方块（"豆腐块"）。表情符号（如 🔥）也可能显示为方块。`render_image` / `render_pdf` 输出中包含中日韩文字时同样受影响。
 
-**解决方案:** 在容器中安装 CJK（中日韩）和 Emoji 字体。
+**解决方案:** 在容器中安装 CJK（中日韩）和 Emoji 字体。渲染工具会自动探测同一批字体路径，因此安装这些字体包可以同时修复截图与渲染输出的中文显示。
 
 **Debian/Ubuntu:**
 ```bash

package/dist/agent.js

@@ -9,8 +9,24 @@ import { getToolDefinitions, executeToolHandler, listUnavailableTools } from './
 import { withRetry } from './retry.js';
 import { truncateOutput } from './truncate.js';
 import { buildShellInfo, resolveShellType } from './shell.js';
+import { buildSkillsManifest } from './skills.js';
 const DEFAULT_MAX_STEPS = 25;
 const TOOL_RESULT_TRIM_MARKER = 'older tool output trimmed';
+// Canonical JSON: sorted object keys, so equivalent arguments from
+// different model turns map to the same repeat signature.
+function canonicalArgs(args) {
+    try {
+        return JSON.stringify(args, (_key, value) => {
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                return Object.keys(value).sort().reduce((acc, k) => { acc[k] = value[k]; return acc; }, {});
+            }
+            return value;
+        });
+    }
+    catch {
+        return String(args);
+    }
+}
 export class Agent {
     client;
     messages;
@@ -51,12 +67,24 @@ System Information:
             has('web_search') ? '- Web: web_search — real-time information lookup' : null,
             has('read_website') ? '- Web: read_website — extract article content from a URL' : null,
             has('take_screenshot') ? '- Web: take_screenshot — capture page visuals' : null,
+            has('start_background_process') ? '- Processes: start_background_process / check_background_process / stop_background_process — run long-lived commands (servers, watchers) in the background and poll their output' : null,
             has('send_email') ? '- Communication: send_email — SMTP email delivery' : null,
             has('send_notification') ? '- Communication: send_notification — push to Feishu/DingTalk/WeCom' : null,
             has('generate_image') ? '- Creation: generate_image — AI image generation (DALL-E compatible)' : null,
             has('optimize_prompt') ? '- Creation: optimize_prompt — refine raw prompts for creative/complex tasks (recommended before creative work)' : null,
             '- Utility: get_current_datetime — accurate system time for temporal reasoning'
         ].filter((line) => line !== null).join('\n');
+        // Skills ride along as one-line manifest entries; the body is only read
+        // (via read_file) when a task actually matches. Never break startup on
+        // a malformed skill directory.
+        let skillsManifest = null;
+        try {
+            skillsManifest = buildSkillsManifest(config);
+        }
+        catch {
+            skillsManifest = null;
+        }
+        const skillsBlock = skillsManifest ? `\n${skillsManifest}\n` : '';
         this.messages = [
             {
                 role: "system",
@@ -68,7 +96,7 @@ ${systemInfo}
 
 WHAT YOU CAN DO:
 ${capabilities}
-
+${skillsBlock}
 RULES OF ENGAGEMENT:
 1. One shot, not one chat. Produce working results, not conversation. Be terse.
 2. Use the right tool for the job. Shell for system ops. Files for content. Web tools for external info.
@@ -116,6 +144,8 @@ RULES OF ENGAGEMENT:
         let status = 'completed';
         let errorMessage;
         let lastContent = null;
+        let lastToolSignature = null;
+        let consecutiveRepeats = 0;
         const totalUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
         let sawUsage = false;
         this.emitEvent({ event: 'run_start', model: this.model, task: userInput });
@@ -334,6 +364,21 @@ RULES OF ENGAGEMENT:
                     const truncation = truncateOutput(toolResult);
                     const boundedResult = truncation.content;
                     const resultLines = boundedResult.split('\n');
+                    // Loop hygiene (idea from dsh repeat-tool-reminder): identical
+                    // consecutive calls get an escalating reminder so the model changes
+                    // approach early instead of burning turns until the step cap.
+                    const signature = `${functionName}:${canonicalArgs(functionArgs)}`;
+                    if (signature === lastToolSignature)
+                        consecutiveRepeats++;
+                    else {
+                        consecutiveRepeats = 1;
+                        lastToolSignature = signature;
+                    }
+                    const repeatSuffix = consecutiveRepeats < 3
+                        ? ''
+                        : consecutiveRepeats < 5
+                            ? `\n[AutoClaw] Note: this is the ${consecutiveRepeats}th identical ${functionName} call in a row. If it keeps returning the same result, change approach instead of repeating it.`
+                            : `\n[AutoClaw] You have now made the identical ${functionName} call ${consecutiveRepeats} times in a row (arguments: ${JSON.stringify(functionArgs).slice(0, 120)}). This exact call keeps returning the same result. Stop retrying it: change approach, fix the underlying problem, or finish the task with what you already have.`;
                     let outputFile = null;
                     if (resultLines.length > MAX_PREVIEW_LINES || truncation.truncated) {
                         outputFile = await this.saveOutput(functionName, toolResult);
@@ -366,7 +411,7 @@ RULES OF ENGAGEMENT:
                     this.messages.push({
                         role: "tool",
                         tool_call_id: toolCall.id,
-                        content: boundedResult
+                        content: boundedResult + repeatSuffix
                     });
                 }
             }

package/dist/index.js

@@ -8,6 +8,7 @@ import { parseManifest, runBatch } from './batch.js';
 import { PROVIDER_PRESETS, providerNames, resolveProvider } from './providers.js';
 import { fetchModelIds, normalizeBaseUrl, testConnection } from './setup.js';
 import { collectDoctorChecks } from './doctor.js';
+import { defaultSkillScopes, discoverSkills, installSkill, installSkillFromUrl, packSkill, removeSkill } from './skills.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -46,7 +47,7 @@ dotenv.config({ path: GLOBAL_ENV_FILE });
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // In dist/index.js, package.json is usually up one level in the root
 const pkgPath = path.join(__dirname, '..', 'package.json');
-let version = '1.3.4';
+let version = '1.3.6';
 try {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     version = pkg.version;
@@ -90,6 +91,79 @@ program
     const options = program.opts();
     await runBatchCommand(manifest, options, cmdOptions);
 });
+const skillCmd = program
+    .command('skill')
+    .description('Manage skill packages (SKILL.md format, WorkBuddy-store compatible)');
+skillCmd
+    .command('list')
+    .description('List discovered skills across builtin / user / project scopes')
+    .action(() => {
+    const { skills, warnings } = discoverSkills(defaultSkillScopes());
+    for (const w of warnings)
+        console.log(chalk.dim(`  ! ${w}`));
+    if (skills.length === 0) {
+        console.log('No skills found. Install one with: autoclaw skill install <zip-or-dir>');
+        return;
+    }
+    console.log(chalk.bold.cyan(`Skills (${skills.length}):\n`));
+    for (const s of skills) {
+        const desc = s.descriptionZh || s.descriptionEn || s.description;
+        console.log(`  ${chalk.bold(s.name)}${s.version ? chalk.dim(` v${s.version}`) : ''} ${chalk.dim(`[${s.source}]`)}`);
+        console.log(`    ${desc.replace(/\s+/g, ' ').slice(0, 100)}${desc.length > 100 ? '…' : ''}`);
+        console.log(`    ${chalk.dim(s.dir)}`);
+    }
+    console.log(chalk.dim('\nSkills run inside chat/batch automatically: the agent sees a skill list and reads a matched SKILL.md on demand.'));
+});
+skillCmd
+    .command('install <target>')
+    .description('Install a skill from an https .zip URL, a local .zip, or a directory (into ~/.autoclaw/skills/)')
+    .action(async (target) => {
+    try {
+        const result = /^https:\/\//.test(target)
+            ? await installSkillFromUrl(target)
+            : installSkill(target);
+        console.log(chalk.green(`Installed skill '${result.name}' (${result.files} files) -> ${result.dir}`));
+        console.log(chalk.dim('Verify with: autoclaw skill list'));
+    }
+    catch (err) {
+        console.error(chalk.red(`Error: ${err?.message || err}`));
+        process.exitCode = 1;
+    }
+});
+skillCmd
+    .command('remove <name>')
+    .description('Remove a user-installed skill (~/.autoclaw/skills/)')
+    .action((name) => {
+    const result = removeSkill(name);
+    if (result === 'removed')
+        console.log(chalk.green(`Removed skill '${name}'.`));
+    else if (result === 'builtin') {
+        console.error(chalk.red(`'${name}' is a built-in skill and cannot be removed.`));
+        process.exitCode = 1;
+    }
+    else if (result === 'project') {
+        console.error(chalk.red(`'${name}' lives in .autoclaw/skills/ — delete it manually.`));
+        process.exitCode = 1;
+    }
+    else {
+        console.error(chalk.red(`Skill '${name}' not found.`));
+        process.exitCode = 1;
+    }
+});
+skillCmd
+    .command('pack <dir>')
+    .description('Package a skill directory into a store-upload zip (skills/<name>/ at zip root)')
+    .option('-o, --output <file>', 'Output zip path (default: <name>-skill.zip in cwd)')
+    .action((dir, cmdOptions) => {
+    try {
+        const result = packSkill(dir, cmdOptions.output);
+        console.log(chalk.green(`Packed '${result.name}' (${result.fileCount} files) -> ${result.zipPath}`));
+    }
+    catch (err) {
+        console.error(chalk.red(`Error: ${err?.message || err}`));
+        process.exitCode = 1;
+    }
+});
 program
     .command('doctor')
     .description('Diagnose configuration and environment (headless)')

package/dist/sandbox.js

@@ -0,0 +1,94 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { shellInvocation } from './shell.js';
+export function resolveSandboxMode(config) {
+    const requested = String(config?.sandbox || process.env.AUTOCLOW_SANDBOX || 'danger-full-access').toLowerCase();
+    if (requested === 'read-only' || requested === 'workspace-write' || requested === 'danger-full-access') {
+        return requested;
+    }
+    return 'danger-full-access';
+}
+export function sandboxBackend(platform = process.platform) {
+    if (platform === 'linux') {
+        const available = hasExecutable('bwrap');
+        return {
+            backend: 'bwrap',
+            available,
+            detail: available
+                ? 'bubblewrap found'
+                : 'bubblewrap (bwrap) not found — install it (e.g. apt install bubblewrap) or set sandbox to danger-full-access'
+        };
+    }
+    if (platform === 'darwin') {
+        const available = fs.existsSync('/usr/bin/sandbox-exec');
+        return {
+            backend: 'sandbox-exec',
+            available,
+            detail: available ? 'sandbox-exec found' : 'sandbox-exec missing (unexpected on macOS)'
+        };
+    }
+    return {
+        backend: 'none',
+        available: false,
+        detail: 'no sandbox backend on this platform yet (Windows restricted-token rung is planned). Set sandbox to danger-full-access to run unrestricted.'
+    };
+}
+function hasExecutable(name) {
+    for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+        try {
+            if (fs.existsSync(path.join(dir, name)))
+                return true;
+        }
+        catch {
+            // skip unreadable PATH entries
+        }
+    }
+    return false;
+}
+// Pure shape builder: wraps the platform shell invocation so the command can
+// only write where the mode allows. danger-full-access returns the command
+// unchanged; read-only/workspace-write require the platform backend, which
+// the caller checks with sandboxBackend() first (fail-closed otherwise).
+export function sandboxedInvocation(command, mode, workspace, platform = process.platform) {
+    const base = shellInvocation(command);
+    if (mode === 'danger-full-access')
+        return base;
+    if (platform === 'linux') {
+        if (mode === 'read-only') {
+            return {
+                file: 'bwrap',
+                args: ['--ro-bind', '/', '/', '--dev-bind', '/dev', '/dev', '--proc', '/proc', '--', base.file, ...base.args]
+            };
+        }
+        return {
+            file: 'bwrap',
+            args: [
+                '--ro-bind', '/', '/',
+                '--bind', workspace, workspace,
+                '--dev-bind', '/dev', '/dev',
+                '--proc', '/proc',
+                '--tmpfs', '/tmp',
+                '--', base.file, ...base.args
+            ]
+        };
+    }
+    if (platform === 'darwin') {
+        const ws = workspace.replace(/"/g, '\\"');
+        if (mode === 'read-only') {
+            return {
+                file: '/usr/bin/sandbox-exec',
+                args: ['-p', '(version 1)(allow default)(deny file-write*)', base.file, ...base.args]
+            };
+        }
+        return {
+            file: '/usr/bin/sandbox-exec',
+            args: [
+                '-p',
+                `(version 1)(allow default)(deny file-write*)(allow file-write* (subpath "${ws}") (subpath "/private/tmp") (regex #"^/private/var/folders/"))`,
+                base.file,
+                ...base.args
+            ]
+        };
+    }
+    return { blocked: true, detail: sandboxBackend(platform).detail };
+}

package/dist/shell.js

@@ -1,5 +1,6 @@
 import { spawn, execSync } from 'child_process';
 import * as fs from 'fs';
+import * as path from 'path';
 const GIT_BASH_CANDIDATES = [
     'C:\\Program Files\\Git\\bin\\bash.exe',
     'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
@@ -7,6 +8,7 @@ const GIT_BASH_CANDIDATES = [
 ];
 let cachedType = null;
 let cachedBashPath;
+let cachedBashEnv = null;
 function findBashPath() {
     if (process.platform === 'win32') {
         for (const candidate of GIT_BASH_CANDIDATES) {
@@ -31,6 +33,26 @@ export function getBashPath() {
         cachedBashPath = findBashPath();
     return cachedBashPath;
 }
+// A login shell (-l) would source the profile to put Git's /usr/bin on
+// PATH, but that costs ~450ms per command. Prepending the directories to
+// the child PATH achieves the same tool resolution at spawn speed.
+export function spawnEnv() {
+    if (process.platform !== 'win32')
+        return process.env;
+    if (cachedBashEnv)
+        return cachedBashEnv;
+    const env = { ...process.env };
+    const bp = getBashPath();
+    if (bp) {
+        const usrBin = path.dirname(bp);
+        const gitRoot = path.resolve(usrBin, '..', '..');
+        const extra = [usrBin, path.join(gitRoot, 'mingw64', 'bin'), path.join(gitRoot, 'cmd')]
+            .filter(p => fs.existsSync(p));
+        env.PATH = `${extra.join(path.delimiter)}${path.delimiter}${env.PATH ?? ''}`;
+    }
+    cachedBashEnv = env;
+    return env;
+}
 export function resolveShellType(config) {
     const requested = String(config?.shell || process.env.AUTOCLOW_SHELL || 'auto').toLowerCase();
     if (requested === 'bash' || requested === 'powershell' || requested === 'cmd' || requested === 'sh') {
@@ -57,28 +79,42 @@ export function smartDecode(buf) {
         }
     }
 }
-export function execShellCommand(command, opts) {
+export function shellInvocation(command) {
     const type = resolveShellType();
-    let file;
-    let args;
     if (type === 'bash') {
-        // -l sources the profile so Git Bash's /usr/bin lands on PATH and Unix
-        // tools (ls, grep, ...) actually resolve.
-        file = getBashPath();
-        args = ['-l', '-c', command];
+        // --noprofile/--norc: profile loading costs ~450ms per command; PATH is
+        // handled by spawnEnv() instead.
+        return { file: getBashPath(), args: ['--noprofile', '--norc', '-c', command] };
     }
-    else if (type === 'powershell') {
-        file = 'powershell.exe';
-        args = ['-NoProfile', '-Command', command];
+    if (type === 'powershell') {
+        return { file: 'powershell.exe', args: ['-NoProfile', '-Command', command] };
     }
-    else if (type === 'cmd') {
-        file = process.env.ComSpec || 'cmd.exe';
-        args = ['/d', '/s', '/c', command];
+    if (type === 'cmd') {
+        return { file: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', command] };
     }
-    else {
-        file = '/bin/sh';
-        args = ['-c', command];
+    return { file: '/bin/sh', args: ['-c', command] };
+}
+export function killProcessTree(pid) {
+    if (process.platform !== 'win32') {
+        // The negative pid targets the detached process group.
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }
+        return;
     }
+    spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+}
+export function execShellCommand(command, opts) {
+    const type = resolveShellType();
+    const { file, args } = opts.sandboxed ?? shellInvocation(command);
     return new Promise(resolve => {
         const stdout = [];
         const stderr = [];
@@ -87,7 +123,7 @@ export function execShellCommand(command, opts) {
         let truncated = false;
         let settled = false;
         const posix = process.platform !== 'win32';
-        const child = spawn(file, args, { windowsHide: true, detached: posix });
+        const child = spawn(file, args, { windowsHide: true, detached: posix, env: spawnEnv() });
         const finish = () => {
             if (settled)
                 return;
@@ -101,21 +137,8 @@ export function execShellCommand(command, opts) {
             });
         };
         const killTree = () => {
-            if (!child.pid)
-                return;
-            if (posix) {
-                try {
-                    process.kill(-child.pid, 'SIGKILL');
-                }
-                catch {
-                    child.kill('SIGKILL');
-                }
-            }
-            else {
-                // Terminating the shell alone would orphan grandchildren, whose
-                // inherited stdio pipes keep 'close' pending — kill the whole tree.
-                spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
-            }
+            if (child.pid)
+                killProcessTree(child.pid);
         };
         const timer = setTimeout(() => {
             timedOut = true;