@trim21/personal-pi-extensions 0.1.585 → 0.1.587

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.585",
+  "version": "0.1.587",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/core.ts

@@ -134,6 +134,15 @@ export function resolveBwrap(config: BwrapConfig): ResolvedBwrap {
   }
 }
 
+/**
+ * 把配置文件形状（可缺省、容忍未知字段）补全成完整 BwrapConfig：合并默认值后走
+ * 同一套 schema 校验。与 loadBwrapConfig 的文件路径共用同一条补全语义，供
+ * frontmatter 等非文件来源的配置使用（配置的加载/构造与沙箱创建解耦）。
+ */
+export function completeBwrapConfig(file: BwrapConfigFile): BwrapConfig {
+  return Value.Parse(bwrapConfigSchema, deepMerge(DEFAULT_CONFIG, file));
+}
+
 function deepMerge(base: BwrapConfig, overrides: Partial<BwrapConfig>): BwrapConfig {
   return {
     mode: overrides.mode ?? base.mode,

package/src/bwrap/runtime.ts

@@ -23,6 +23,7 @@ import { type SelectAction, selectMultiple, selectWithOptionalInput } from "../l
 import { type ApprovalRule, evaluateBashApproval, matchRule } from "./approval-rules.js";
 import { commandPatternsFor } from "./approval-suggest.js";
 import {
+  type BwrapConfig,
   type BwrapMode,
   findBwrap,
   findMihomo,
@@ -308,12 +309,17 @@ const SANDBOX_ESCAPE_HATCH =
  * 命令没经沙箱（allow-all、审批通过的全权限、Windows）时返回 undefined：
  * 没有沙箱就没什么可提示的。
  */
-export function describeSandbox(resolved: ResolvedBwrap, unsandboxed: boolean): string | undefined {
+export function describeSandbox(
+  resolved: ResolvedBwrap,
+  unsandboxed: boolean,
+  fixed = false,
+): string | undefined {
   if (unsandboxed) return undefined;
   return [
     "<system-reminder>",
     `This command ran in a sandbox: ${describeLimits(resolved)}.`,
-    SANDBOX_ESCAPE_HATCH,
+    // 固定沙箱的提权请求会被直接拒绝，再提示 escape hatch 只会诱导无效请求
+    ...(fixed ? [] : [SANDBOX_ESCAPE_HATCH]),
     "</system-reminder>",
   ].join("\n");
 }
@@ -347,9 +353,16 @@ export class BwrapRuntime {
    * 独立入口各持一份、经 pi.events 同步。
    */
   private readonly policy: RequestPolicy;
+  /**
+   * 创建时传入的完整配置：加载配置与创建解耦——有它就不再读盘，且沙箱视为固定
+   * （不注册 /bwrap-* 命令、非沙盒请求一律拒绝）。undefined 表示从全局/项目
+   * bwrap.json 加载（主会话入口的现状行为）。
+   */
+  private readonly config: BwrapConfig | undefined;
 
-  constructor(policy: RequestPolicy) {
+  constructor(policy: RequestPolicy, config?: BwrapConfig) {
     this.policy = policy;
+    this.config = config;
   }
 
   setup(pi: ExtensionAPI): void {
@@ -394,11 +407,18 @@ export class BwrapRuntime {
     pi.on("before_agent_start", (event, ctx) => {
       const runtime = this.resolve(ctx);
       const isWindows = process.platform === "win32";
-      const modeText = ctx.hasUI
-        ? isWindows
-          ? "Every bash command requires user approval before it runs."
-          : `Current bwrap mode: **${runtime.mode}**. The bwrap runtime selects sandboxing and, when requested, user approval for unsandboxed execution.`
-        : `Current bwrap mode: **${runtime.mode}**. This headless session cannot ask for approval: commands that require user approval are denied.`;
+      let modeText: string;
+      if (ctx.hasUI) {
+        if (isWindows) {
+          modeText = "Every bash command requires user approval before it runs.";
+        } else if (this.config === undefined) {
+          modeText = `Current bwrap mode: **${runtime.mode}**. The bwrap runtime selects sandboxing and, when requested, user approval for unsandboxed execution.`;
+        } else {
+          modeText = `Current bwrap mode: **${runtime.mode}**, fixed by the agent's declared sandbox config. Unsandboxed execution requests are refused without approval.`;
+        }
+      } else {
+        modeText = `Current bwrap mode: **${runtime.mode}**. This headless session cannot ask for approval: commands that require user approval are denied.`;
+      }
       const unavailableText =
         !isWindows && this.bwrapUnavailable
           ? " bwrap is unavailable (binary not found): bash commands are refused unless the user explicitly approves unsandboxed execution."
@@ -414,11 +434,16 @@ export class BwrapRuntime {
       };
     });
 
-    this.registerCommands(pi);
+    // 固定沙箱（创建时显式传入配置）不注册 /bwrap-* 命令：切模式与恢复提权审批
+    // 都可能放宽声明的沙箱
+    if (this.config === undefined) this.registerCommands(pi);
   }
 
   setMode(cwd: string, mode: BwrapMode): ResolvedBwrap {
-    this.resolved = loadSandboxConfig({ workspace: cwd, mode });
+    this.resolved =
+      this.config === undefined
+        ? loadSandboxConfig({ workspace: cwd, mode })
+        : resolveBwrap({ ...this.config, mode });
     return this.resolved;
   }
 
@@ -453,9 +478,13 @@ export class BwrapRuntime {
     // 用户在审批框选「Run this in sandbox」拒绝提权：命令降级为沙盒内执行
     let userChoseSandbox = false;
     if (needsApproval && runtime.bwrapEnabled) {
-      // /bwrap-deny-request：非沙盒请求直接拒绝——审批规则与审批框都不再参与，
-      // 拒绝文案与用户点 Deny 相同，直到用户用 /bwrap-allow-request 恢复审批。
-      if (request.requestFullAccess === true && this.policy.deniesRequests()) {
+      // /bwrap-deny-request 与固定沙箱（创建时显式传入配置）：非沙盒请求直接
+      // 拒绝——审批规则与审批框都不再参与，拒绝文案与用户点 Deny 相同
+      // （deny-request 可用 /bwrap-allow-request 恢复审批，固定沙箱不可恢复）。
+      if (
+        request.requestFullAccess === true &&
+        (this.config !== undefined || this.policy.deniesRequests())
+      ) {
         throw new Error(UNSANDBOXED_DENIED);
       }
       // 先按 approvalRules 自动判定：allow 直接放行，deny 直接拒绝，未命中才弹框
@@ -484,7 +513,9 @@ export class BwrapRuntime {
     }
     // 命令失败时附带的沙箱状态（写边界 + 网络层级），由上层拼进错误文本。
     // 用户选「Run this in sandbox」时不附：沙箱作用域改由 sandboxReminder 说明
-    const sandboxHint = userChoseSandbox ? undefined : describeSandbox(runtime, local);
+    const sandboxHint = userChoseSandbox
+      ? undefined
+      : describeSandbox(runtime, local, this.config !== undefined);
     // 提权被拒、命令在沙盒内执行的系统提醒：成功与失败都由上层附上
     const sandboxReminder = userChoseSandbox ? describeSandboxChoice(runtime) : undefined;
     // 计时起点放在审批之后：审批弹窗的等待时长属于用户 UI 操作，不是命令运行时间
@@ -592,8 +623,7 @@ export class BwrapRuntime {
   }
 
   private resolve(ctx: Pick<ExtensionContext, "cwd">): ResolvedBwrap {
-    const config = loadBwrapConfig(ctx.cwd);
-    if (!this.resolved) this.resolved = resolveBwrap(config);
+    if (!this.resolved) this.resolved = resolveBwrap(this.config ?? loadBwrapConfig(ctx.cwd));
     return this.resolved;
   }
 
@@ -960,7 +990,15 @@ export class BwrapRuntime {
   }
 }
 
-/** 缺省自建一份不跨入口同步的策略；入口通常显式传入 `createRequestPolicy(pi.events)`。 */
-export function createBwrapRuntime(policy: RequestPolicy = createRequestPolicy()): BwrapRuntime {
-  return new BwrapRuntime(policy);
+/**
+ * 缺省自建一份不跨入口同步的策略；入口通常显式传入 `createRequestPolicy(pi.events)`。
+ * config 为完整配置（completeBwrapConfig 的产物）：加载配置与创建解耦，传入后不再
+ * 读盘，且沙箱固定（不注册 /bwrap-* 命令、非沙盒请求直接拒绝）。缺省从全局/项目
+ * bwrap.json 加载。
+ */
+export function createBwrapRuntime(
+  policy: RequestPolicy = createRequestPolicy(),
+  config?: BwrapConfig,
+): BwrapRuntime {
+  return new BwrapRuntime(policy, config);
 }

package/src/spawn-agent-agents.ts

@@ -16,6 +16,10 @@
  *   provider: openai           # optional; overrides the global default
  *   model: claude-haiku-4-5     # optional; overrides the global default
  *   thinkingLevel: high         # optional; overrides the global default
+ *   sandbox:                    # optional; fixed bwrap sandbox for the bash tool
+ *     mode: readonly
+ *     extraWritablePaths:
+ *       - /tmp
  *   ---
  *   System prompt for the agent goes here.
  *
@@ -24,6 +28,16 @@
  * omitted, the subagent runs with the read-only default toolset from the
  * spawn-agent config (read/grep/find/ls) unless overridden there.
  *
+ * `sandbox` is a complete bwrap config (same shape as bwrap.json) that becomes
+ * the bash tool's fixed sandbox: it is parsed here and passed to the subagent's
+ * bwrap runtime directly (config loading is decoupled from sandbox creation),
+ * so the user's bwrap.json is not consulted for that agent. Unsandboxed
+ * execution requests are refused and /bwrap-* mode commands are not registered.
+ * Fields are optional and fall back to the standard bwrap defaults (e.g.
+ * `sandbox: {mode: readonly}` alone is enough for a read-only shell);
+ * `extraWritablePaths` is the writable escape hatch under a read-only mode.
+ * Without `sandbox`, the subagent's bash follows the user bwrap config.
+ *
  * Global defaults for provider/model/thinkingLevel come from
  * `~/.pi/agent/spawn-agent.json` (see loadSpawnAgentConfig); frontmatter
  * fields take precedence over them, which in turn take precedence over the
@@ -38,6 +52,8 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { type BwrapConfig, bwrapConfigFileSchema, completeBwrapConfig } from "./bwrap/core.js";
+
 /**
  * Valid thinking levels, mirroring pi's CLI --thinking validation
  * (VALID_THINKING_LEVELS). "off" disables thinking; "max" is deliberately
@@ -52,6 +68,7 @@ const agentFrontmatterSchema = Type.Object({
   provider: Type.Optional(Type.String()),
   model: Type.Optional(Type.String()),
   thinkingLevel: Type.Optional(Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)))),
+  sandbox: Type.Optional(bwrapConfigFileSchema),
 });
 
 function parseAgentFrontmatter(frontmatter: unknown) {
@@ -71,6 +88,8 @@ export interface AgentConfig {
   model?: string;
   /** Thinking level, applied via --thinking. */
   thinkingLevel?: (typeof THINKING_LEVELS)[number];
+  /** bash 的完整沙箱配置（bwrap.json 同构）；undefined 表示跟随用户 bwrap 配置。 */
+  sandbox?: BwrapConfig;
   systemPrompt: string;
   filePath: string;
 }
@@ -118,6 +137,7 @@ export function discoverAgents(dir = join(getAgentDir(), "agents")): AgentConfig
       provider: fm.provider,
       model: fm.model,
       thinkingLevel: fm.thinkingLevel,
+      sandbox: fm.sandbox ? completeBwrapConfig(fm.sandbox) : undefined,
       systemPrompt: body,
       filePath,
     });

package/src/spawn-agent.ts

@@ -26,6 +26,10 @@
  *
  * Security default: without an explicit `tools:` in the frontmatter, the
  * subagent only gets read-only tools (read/grep/find/ls) — no bash/write/edit.
+ * A frontmatter `sandbox:` gives the bash tool a fixed bwrap sandbox config
+ * (bwrap.json shape, e.g. mode readonly): it is passed to the subagent's bwrap
+ * runtime as the complete config, unsandboxed execution requests are refused,
+ * and /bwrap-* mode commands are not registered (see spawn-agent-agents.ts).
  */
 
 import { existsSync } from "node:fs";
@@ -42,6 +46,7 @@ import {
   type ExtensionAPI,
   type ExtensionUIContext,
   getAgentDir,
+  type InlineExtension,
   ModelRuntime,
   type PromptOptions,
   SessionManager,
@@ -51,7 +56,11 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { type BwrapRuntime, createBwrapRuntime } from "./bwrap/runtime.js";
+import { registerShellTools } from "./claude-code/shell.js";
 import { type ToolPendant } from "./lib/pendant.js";
+import { createRequestPolicy } from "./lib/request-policy.js";
+import opencodeBash from "./opencode/bash.js";
 import {
   type AgentConfig,
   applyAgentDefaults,
@@ -87,10 +96,11 @@ const SETTINGS_PATH = join(getAgentDir(), "settings.json");
  * `additionalExtensionPaths` so the subagent uses the enhanced implementation
  * instead of the built-in one.
  *
- * The bash override also carries the bwrap sandbox: opencode/bash.ts creates
- * its own bwrap runtime instance and runs commands through runtime.execute(),
- * so agents that declare the bash tool get sandboxing automatically. Agents
- * without bash need no bwrap setup (there are no commands to sandbox).
+ * `bash` (opencode) and `Bash` (claude-code) are deliberately not in this map:
+ * they are injected via an inline extension factory (subagentShellExtension)
+ * instead, because their bwrap runtime carries the agent's declared sandbox
+ * config — a path-based override has no channel to pass per-agent config
+ * (see createSubagentSession).
  * (Workspace write protection is embedded in the opencode write/edit tools.)
  *
  * Claude Code style tools (capitalized names) map to their claude-code
@@ -111,7 +121,6 @@ const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
   read: "opencode/files.ts",
   edit: "opencode/files.ts",
   write: "opencode/files.ts",
-  bash: "opencode/bash.ts",
   grep: "opencode/grep.ts",
   glob: "opencode/glob.ts",
   Grep: "claude-code/grep.ts",
@@ -139,7 +148,8 @@ interface UsageStats {
   turns: number;
 }
 
-interface SubagentDetails {
+/** 子 agent 的一次运行结果：runAgent 的返回值，也是 details.result 的内容。 */
+interface SubagentResult {
   agent: string;
   task: string;
   exitCode: number;
@@ -149,6 +159,11 @@ interface SubagentDetails {
   model?: string;
   stopReason?: string;
   errorMessage?: string;
+}
+
+interface SubagentDetails {
+  /** 子 agent 运行结果（除 pendant 外的字段都收在这里）。 */
+  result: SubagentResult;
   /** 折叠 markdown 面板：父 agent 的 prompt 与父 agent 看到的子 agent 结果。 */
   pendant?: ToolPendant;
 }
@@ -172,7 +187,7 @@ function getFinalOutput(messages: AgentMessage[]): string {
  * stderr 截断到尾部（错误信息通常在最后）。全空时保底 "(no output)"，
  * 避免只回一个 exit code。
  */
-export function formatSubagentError(result: SubagentDetails): { reason: string; message: string } {
+export function formatSubagentError(result: SubagentResult): { reason: string; message: string } {
   const reason =
     result.stopReason ?? (result.exitCode === 0 ? "failed" : `exit ${result.exitCode}`);
   const parts: string[] = [];
@@ -265,6 +280,20 @@ export function overrideExtensionPaths(tools: string[]): string[] {
   return paths;
 }
 
+/**
+ * bash 类工具（opencode `bash` / cc `Bash`）的内联扩展工厂：bwrap runtime 随闭包
+ * 携带该 agent 的完整沙箱配置（frontmatter `sandbox`，已在 discoverAgents 补全成
+ * BwrapConfig）。路径式 override（additionalExtensionPaths）没有 per-agent 配置
+ * 通道，extensionFactories 的工厂闭包是 SDK 提供的唯一注入点。agent.sandbox 为
+ * undefined 时与各注册函数的默认构造完全一致（跟随用户 bwrap 配置）。
+ */
+export function subagentShellExtension(
+  agent: AgentConfig,
+  register: (pi: ExtensionAPI, runtime: BwrapRuntime) => void,
+): InlineExtension {
+  return (pi) => register(pi, createBwrapRuntime(createRequestPolicy(pi.events), agent.sandbox));
+}
+
 /**
  * Resolve the frontmatter model to a runtime Model. A "provider/model" string
  * carries its own provider; a bare model id uses the declared provider, then
@@ -322,13 +351,18 @@ export async function createSubagentSession(
   cwd: string,
   parentUI: ExtensionUIContext | undefined,
 ): Promise<AgentSession> {
+  const tools = agent.tools ?? DEFAULT_TOOLS;
   const settingsManager = SettingsManager.create(cwd, getAgentDir());
   const loader = new DefaultResourceLoader({
     cwd,
     agentDir: getAgentDir(),
     settingsManager,
     noExtensions: true,
-    additionalExtensionPaths: overrideExtensionPaths(agent.tools ?? DEFAULT_TOOLS),
+    additionalExtensionPaths: overrideExtensionPaths(tools),
+    extensionFactories: [
+      ...(tools.includes("bash") ? [subagentShellExtension(agent, opencodeBash)] : []),
+      ...(tools.includes("Bash") ? [subagentShellExtension(agent, registerShellTools)] : []),
+    ],
     appendSystemPrompt: agent.systemPrompt ? [agent.systemPrompt] : undefined,
   });
   await loader.reload();
@@ -338,7 +372,7 @@ export async function createSubagentSession(
     cwd,
     model: resolveModel(modelRuntime, agent, settingsManager),
     thinkingLevel: agent.thinkingLevel,
-    tools: agent.tools ?? DEFAULT_TOOLS,
+    tools,
     sessionManager: SessionManager.inMemory(cwd),
     settingsManager,
     resourceLoader: loader,
@@ -356,8 +390,8 @@ export async function runAgent(
   onUpdate: OnUpdateCallback | undefined,
   parentUI?: ExtensionUIContext,
   createSession: SessionFactory = createSubagentSession,
-): Promise<SubagentDetails> {
-  const result: SubagentDetails = {
+): Promise<SubagentResult> {
+  const result: SubagentResult = {
     agent: agent.name,
     task,
     exitCode: 0,
@@ -431,7 +465,7 @@ export async function runAgent(
     const footer = usageLine ? `\`${name}\` ${usageLine}` : `\`${name}\``;
     onUpdate?.({
       content: [{ type: "text", text: [...logLines, footer].join("\n") }],
-      details: { ...result },
+      details: { result: { ...result } },
     });
   };
 
@@ -558,15 +592,17 @@ export default function spawnAgent(pi: ExtensionAPI) {
             },
           ],
           details: {
-            agent: params.agent,
-            task: params.task,
-            exitCode: 1,
-            messages: [],
-            stderr: "",
-            usage: {
-              cost: 0,
-              contextTokens: 0,
-              turns: 0,
+            result: {
+              agent: params.agent,
+              task: params.task,
+              exitCode: 1,
+              messages: [],
+              stderr: "",
+              usage: {
+                cost: 0,
+                contextTokens: 0,
+                turns: 0,
+              },
             },
           },
           isError: true,
@@ -591,7 +627,7 @@ export default function spawnAgent(pi: ExtensionAPI) {
             { type: "text", text: `Subagent "${result.agent}" failed (${reason}):\n${message}` },
           ],
           details: {
-            ...result,
+            result,
             pendant: {
               subtitle: result.agent,
               markdown: formatPendantMarkdown(params.task, message),
@@ -609,7 +645,7 @@ export default function spawnAgent(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text }],
         details: {
-          ...result,
+          result,
           pendant: {
             subtitle: result.agent,
             markdown: formatPendantMarkdown(params.task, text),
@@ -631,7 +667,7 @@ export default function spawnAgent(pi: ExtensionAPI) {
     },
 
     renderResult(result, { expanded }, theme) {
-      const details = result.details;
+      const details = result.details.result;
       const isError =
         details.exitCode !== 0 ||
         details.stopReason === "error" ||