@armadra/agent 0.7.6 → 0.8.1

package/dist/drivers/catalog.d.ts

@@ -1,5 +1,5 @@
 /**
- * 内置驱动表（数据，docs/wave5-plan.md §5.1 catalog.ts，D14）。[W5-E]
+ * 内置驱动表（数据，docs/history/wave5-plan.md §5.1 catalog.ts，D14）。[W5-E]
  *
  * agentId → 候选链；按 D14 的优先级排：原生 ACP > 已装 ACP 适配器 > 原生结构化协议 > 一次性打印。
  * 探测时取第一个已安装的候选。`verified` 是实测过的版本区间：越界仍可用，但发一条 warn 提示
@@ -24,6 +24,8 @@ export interface CatalogCandidate {
     modes?: Partial<Record<PermissionMode, string>>;
     permissions?: DriverCapabilities["permissions"];
     usage?: DriverCapabilities["usage"];
+    /** `session/prompt` 答复的 usage 是会话累计（缺省按本回合）。 */
+    acpUsage?: "session";
     /** 一次性打印模式的方言。 */
     oneshot?: "claude" | "codex" | "gemini";
 }

package/dist/drivers/catalog.js

@@ -1,5 +1,5 @@
 /**
- * 内置驱动表（数据，docs/wave5-plan.md §5.1 catalog.ts，D14）。[W5-E]
+ * 内置驱动表（数据，docs/history/wave5-plan.md §5.1 catalog.ts，D14）。[W5-E]
  *
  * agentId → 候选链；按 D14 的优先级排：原生 ACP > 已装 ACP 适配器 > 原生结构化协议 > 一次性打印。
  * 探测时取第一个已安装的候选。`verified` 是实测过的版本区间：越界仍可用，但发一条 warn 提示
@@ -17,12 +17,55 @@ const ALL_MODES = [
     "auto",
     "full-auto",
 ];
+/**
+ * 模式 id 与 ama 不同名的 ACP Agent 的映射（2026-10 实测）。没有映射时 ama 会留在 Agent 自己的当前模式，
+ * 而它可能比 ama 宽（如用户把 Claude 的缺省设成 bypassPermissions），所以已知的 Agent 一律写全。
+ * 从不映射到放开全部权限的模式（Claude `bypassPermissions`、Codex `agent-full-access`、Copilot autopilot）。
+ */
+const CLAUDE_ACP_MODES = {
+    plan: "plan",
+    default: "default",
+    "auto-edit": "acceptEdits",
+    auto: "auto",
+    "full-auto": "auto",
+};
+/** codex-acp：`read-only` 是只读沙箱、写操作要审批（等同 app-server 的 on-request / read-only）。 */
+const CODEX_ACP_MODES = {
+    plan: "read-only",
+    default: "read-only",
+    "auto-edit": "workspace-write",
+    auto: "agent",
+    "full-auto": "agent",
+};
+const COPILOT_MODE = "https://agentclientprotocol.com/protocol/session-modes#";
+const COPILOT_MODES = {
+    plan: `${COPILOT_MODE}plan`,
+    default: `${COPILOT_MODE}agent`,
+    "auto-edit": `${COPILOT_MODE}agent`,
+    auto: `${COPILOT_MODE}agent`,
+    "full-auto": `${COPILOT_MODE}agent`,
+};
+/** Cursor CLI（官方 ACP 文档）：`plan` 只读，`agent` 是完整工具权限（需要授权的仍发 request_permission）。 */
+const CURSOR_MODES = {
+    plan: "plan",
+    default: "agent",
+    "auto-edit": "agent",
+    auto: "agent",
+    "full-auto": "agent",
+};
 export const DRIVER_CATALOG = [
     {
         agentId: "claude",
         label: "Claude Code",
         candidates: [
-            { kind: "acp-adapter", program: "claude-agent-acp", args: [], usage: "usd" },
+            {
+                kind: "acp-adapter",
+                program: "claude-agent-acp",
+                args: [],
+                verified: ">=0.89.0 <1.0.0",
+                usage: "usd",
+                modes: CLAUDE_ACP_MODES,
+            },
             {
                 kind: "claude-stream",
                 program: "claude",
@@ -37,7 +80,14 @@ export const DRIVER_CATALOG = [
         agentId: "codex",
         label: "Codex",
         candidates: [
-            { kind: "acp-adapter", program: "codex-acp", args: [], usage: "tokens" },
+            {
+                kind: "acp-adapter",
+                program: "codex-acp",
+                args: [],
+                verified: ">=2.2.0 <3.0.0",
+                usage: "tokens",
+                modes: CODEX_ACP_MODES,
+            },
             {
                 kind: "codex-app-server",
                 program: "codex",
@@ -70,15 +120,44 @@ export const DRIVER_CATALOG = [
     {
         agentId: "opencode",
         label: "OpenCode",
-        candidates: [{ kind: "acp", program: "opencode", args: ["acp"] }],
+        candidates: [{ kind: "acp", program: "opencode", args: ["acp"], verified: ">=1.18.0 <2.0.0" }],
     },
     {
         agentId: "copilot",
         label: "GitHub Copilot CLI",
         candidates: [
-            { kind: "acp", program: "copilot", args: ["--acp", "--stdio"], usage: "requests" },
+            {
+                kind: "acp",
+                program: "copilot",
+                args: ["--acp", "--stdio"],
+                verified: ">=1.0.95 <2.0.0",
+                usage: "requests",
+                modes: COPILOT_MODES,
+                acpUsage: "session",
+            },
         ],
     },
+    {
+        agentId: "pi",
+        label: "Pi",
+        // 社区 ACP 适配器 pi-acp 不发 request_permission（pi 没有审批通道），会让工具不经人直接执行，不收录
+        candidates: [
+            {
+                kind: "pi-rpc",
+                program: "pi",
+                args: ["--mode", "rpc"],
+                verified: ">=1.1.0 <2.0.0",
+                usage: "usd",
+            },
+        ],
+    },
+    {
+        agentId: "cursor",
+        label: "Cursor CLI",
+        // 未实测（本机未装）：按官方文档 `cursor-agent acp`，模式 agent / plan / ask；`cursor/ask_question`
+        // 等阻塞式扩展方法 ama 不实现（回 method not found，不代答）
+        candidates: [{ kind: "acp", program: "cursor-agent", args: ["acp"], modes: CURSOR_MODES }],
+    },
     {
         agentId: "goose",
         label: "Goose",
@@ -142,6 +221,17 @@ export function candidateCapabilities(c) {
                 usage: "tokens",
                 images: false,
             };
+        case "pi-rpc":
+            // 审批经 ama 加载的审批闸扩展交给人（native/pi-gate.ts）
+            return {
+                resume: "resume",
+                list: false,
+                permissions: "interactive",
+                steer: true,
+                modes: ALL_MODES,
+                usage: "usd",
+                images: true,
+            };
         case "oneshot":
             return {
                 resume: c.oneshot === "gemini" ? "none" : "resume",

package/dist/drivers/env.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 子进程环境清理（docs/wave5-plan.md §5.4，D16）。[W5-E]
+ * 外部 Agent 子进程环境清理（docs/history/wave5-plan.md §5.4，D16）。[W5-E]
  *
  * ama 分不清「用户 shell 本来就有」与「为 ama 设的」变量，所以缺省全剥、显式放回：
  * - 删：`BUILTIN_PROVIDERS[].envKeys`（各家 API key）、`*_BASE_URL`、`AMA_*`、`CODEX_API_KEY`、

package/dist/drivers/env.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 子进程环境清理（docs/wave5-plan.md §5.4，D16）。[W5-E]
+ * 外部 Agent 子进程环境清理（docs/history/wave5-plan.md §5.4，D16）。[W5-E]
  *
  * ama 分不清「用户 shell 本来就有」与「为 ama 设的」变量，所以缺省全剥、显式放回：
  * - 删：`BUILTIN_PROVIDERS[].envKeys`（各家 API key）、`*_BASE_URL`、`AMA_*`、`CODEX_API_KEY`、

package/dist/drivers/host-runners.d.ts

@@ -1,5 +1,5 @@
 /**
- * 宿主注入的 runner（`HostApi.runners.provide` 的底座，docs/wave5-plan.md §5.5，D17）。[W5-E → W5-EG]
+ * 宿主注入的 runner（`HostApi.runners.provide` 的底座，docs/history/wave5-plan.md §5.5，D17）。[W5-E → W5-EG]
  *
  * 一个宿主适配器一份（host/api-impl.ts 建，经 {@link ExternalAgents} 的 `hostRunners` 选项交给每个
  * 主会话）：宿主可以在 `create()` 里或之后任何时候 `provide`，同名替换；返回的函数注销。

package/dist/drivers/host-runners.js

@@ -1,5 +1,5 @@
 /**
- * 宿主注入的 runner（`HostApi.runners.provide` 的底座，docs/wave5-plan.md §5.5，D17）。[W5-E → W5-EG]
+ * 宿主注入的 runner（`HostApi.runners.provide` 的底座，docs/history/wave5-plan.md §5.5，D17）。[W5-E → W5-EG]
  *
  * 一个宿主适配器一份（host/api-impl.ts 建，经 {@link ExternalAgents} 的 `hostRunners` 选项交给每个
  * 主会话）：宿主可以在 `create()` 里或之后任何时候 `provide`，同名替换；返回的函数注销。

package/dist/drivers/jsonrpc.d.ts

@@ -1,5 +1,5 @@
 /**
- * JSON-RPC 2.0 over NDJSON 的对等端（docs/wave5-plan.md §5.1）。[W5-E]
+ * JSON-RPC 2.0 over NDJSON 的对等端（docs/history/wave5-plan.md §5.1）。[W5-E]
  *
  * ACP 客户端 / 服务端与 Codex app-server 驱动共用：
  * - 分帧复用 `modes/rpc/jsonl.ts`（只按 `\n` 切行、64 KiB 分片写、背压等 drain），写入串行；

package/dist/drivers/jsonrpc.js

@@ -1,5 +1,5 @@
 /**
- * JSON-RPC 2.0 over NDJSON 的对等端（docs/wave5-plan.md §5.1）。[W5-E]
+ * JSON-RPC 2.0 over NDJSON 的对等端（docs/history/wave5-plan.md §5.1）。[W5-E]
  *
  * ACP 客户端 / 服务端与 Codex app-server 驱动共用：
  * - 分帧复用 `modes/rpc/jsonl.ts`（只按 `\n` 切行、64 KiB 分片写、背压等 drain），写入串行；

package/dist/drivers/native/claude-normalize.d.ts

@@ -1,5 +1,5 @@
 /**
- * Claude Code stream-json → DriverEvent 的映射表（docs/wave5-plan.md §5.1 normalize，R2 §3.2）。[W5-E]
+ * Claude Code stream-json → DriverEvent 的映射表（docs/history/wave5-plan.md §5.1 normalize，R2 §3.2）。[W5-E]
  *
  * 线上形状按 Claude Code 2.1.x 的 `--output-format stream-json`（Agent SDK 所用的同一协议；
  * 官方称其不是公开的 CLI 接口，R3），只读用到的字段，其余忽略。
@@ -39,7 +39,15 @@ export interface ClaudeResult {
         tool_name?: string;
     }[];
     errors?: string[];
+    /** 进程内累计，按模型分；`contextWindow` 是该模型的上下文窗口（2.1.x 起）。 */
+    modelUsage?: Record<string, {
+        contextWindow?: number;
+    }>;
 }
+/** 一条主线 assistant 消息的用量 = 这次请求后的上下文占用（输入 + 缓存读写 + 输出）。 */
+export declare function claudeContextTokens(usage: unknown): number | undefined;
+/** result.modelUsage 里某模型（缺省取最大）的上下文窗口。 */
+export declare function claudeContextWindow(result: ClaudeResult, model: string | undefined): number | undefined;
 /** result.subtype → 回合结束原因；`undefined` 表示执行出错（调用方按错误处理）。 */
 export declare function claudeStopReason(result: ClaudeResult, interrupted: boolean): "end_turn" | "max_turn_requests" | "cancelled" | undefined;
 /** 只保留会话范围的权限建议（`localSettings` 等会改用户 / 项目配置文件，不能替人写）。 */

package/dist/drivers/native/claude-normalize.js

@@ -1,5 +1,5 @@
 /**
- * Claude Code stream-json → DriverEvent 的映射表（docs/wave5-plan.md §5.1 normalize，R2 §3.2）。[W5-E]
+ * Claude Code stream-json → DriverEvent 的映射表（docs/history/wave5-plan.md §5.1 normalize，R2 §3.2）。[W5-E]
  *
  * 线上形状按 Claude Code 2.1.x 的 `--output-format stream-json`（Agent SDK 所用的同一协议；
  * 官方称其不是公开的 CLI 接口，R3），只读用到的字段，其余忽略。
@@ -81,6 +81,33 @@ export function claudePermissionMode(mode, manualName) {
 }
 /** 只能由人回答的提问类工具（ama 不代答）。 */
 export const CLAUDE_QUESTION_TOOLS = new Set(["AskUserQuestion"]);
+/** 一条主线 assistant 消息的用量 = 这次请求后的上下文占用（输入 + 缓存读写 + 输出）。 */
+export function claudeContextTokens(usage) {
+    if (typeof usage !== "object" || usage === null)
+        return undefined;
+    const u = usage;
+    let total = 0;
+    for (const key of [
+        "input_tokens",
+        "cache_read_input_tokens",
+        "cache_creation_input_tokens",
+        "output_tokens",
+    ])
+        if (typeof u[key] === "number")
+            total += u[key];
+    return total > 0 ? total : undefined;
+}
+/** result.modelUsage 里某模型（缺省取最大）的上下文窗口。 */
+export function claudeContextWindow(result, model) {
+    const entries = result.modelUsage ?? {};
+    const hit = model !== undefined ? entries[model]?.contextWindow : undefined;
+    if (typeof hit === "number" && hit > 0)
+        return hit;
+    const windows = Object.values(entries)
+        .map((e) => e.contextWindow)
+        .filter((w) => typeof w === "number" && w > 0);
+    return windows.length > 0 ? Math.max(...windows) : undefined;
+}
 /** result.subtype → 回合结束原因；`undefined` 表示执行出错（调用方按错误处理）。 */
 export function claudeStopReason(result, interrupted) {
     if (interrupted)

package/dist/drivers/native/claude-stream.d.ts

@@ -1,5 +1,5 @@
 /**
- * Claude Code 原生驱动：stream-json 长驻进程（docs/wave5-plan.md §5.1，R2 §1.2）。[W5-E]
+ * Claude Code 原生驱动：stream-json 长驻进程（docs/history/wave5-plan.md §5.1，R2 §1.2）。[W5-E]
  *
  * `claude -p --input-format stream-json --output-format stream-json --verbose
  *  --include-partial-messages --permission-prompt-tool stdio --permission-mode <m> --session-id <uuid>`

package/dist/drivers/native/claude-stream.js

@@ -1,5 +1,5 @@
 /**
- * Claude Code 原生驱动：stream-json 长驻进程（docs/wave5-plan.md §5.1，R2 §1.2）。[W5-E]
+ * Claude Code 原生驱动：stream-json 长驻进程（docs/history/wave5-plan.md §5.1，R2 §1.2）。[W5-E]
  *
  * `claude -p --input-format stream-json --output-format stream-json --verbose
  *  --include-partial-messages --permission-prompt-tool stdio --permission-mode <m> --session-id <uuid>`
@@ -20,7 +20,7 @@ import { createLineReader } from "../../modes/rpc/jsonl.js";
 import { armCancelWatchdog, probeCandidate, spawnOf } from "../base.js";
 import { stderrHint } from "../process.js";
 import { TurnCollector, oneLine } from "../turn.js";
-import { CLAUDE_QUESTION_TOOLS, claudePermissionMode, claudeStopReason, claudeTodos, claudeToolKind, claudeToolLocations, claudeToolTitle, sessionScopedSuggestions, } from "./claude-normalize.js";
+import { CLAUDE_QUESTION_TOOLS, claudeContextTokens, claudeContextWindow, claudePermissionMode, claudeStopReason, claudeTodos, claudeToolKind, claudeToolLocations, claudeToolTitle, sessionScopedSuggestions, } from "./claude-normalize.js";
 import { msg as messages } from "../../i18n/index.js";
 export function claudeArgs(options, sessionId, manualName = "manual") {
     const args = [
@@ -116,6 +116,8 @@ class ClaudeStreamSession {
     interrupted = false;
     sawPartialText = false;
     lastTotalCost = 0;
+    /** 最近一条主线 assistant 消息的上下文占用与模型（result 里查窗口用）。 */
+    context = {};
     closed = false;
     exited = false;
     constructor(agentId, id, transport, deps) {
@@ -218,6 +220,13 @@ class ClaudeStreamSession {
             ...(u.cache_read_input_tokens !== undefined ? { cacheRead: u.cache_read_input_tokens } : {}),
             ...(cost !== undefined ? { costUsd: cost } : {}),
         });
+        const window = claudeContextWindow(result, this.context.model);
+        if (this.context.tokens !== undefined || window !== undefined)
+            turn.push({
+                type: "usage",
+                ...(this.context.tokens !== undefined ? { contextTokens: this.context.tokens } : {}),
+                ...(window !== undefined ? { contextWindow: window } : {}),
+            });
         if (typeof result.result === "string" && result.result !== "")
             turn.setFinalText(result.result);
         const denials = result.permission_denials?.length ?? 0;
@@ -337,6 +346,12 @@ class ClaudeStreamSession {
             return;
         // 子 Agent（Task）内部的消息不进最终文本
         const nested = typeof parent === "string" && parent !== "";
+        const tokens = nested ? undefined : claudeContextTokens(message["usage"]);
+        if (tokens !== undefined)
+            this.context = {
+                tokens,
+                ...(typeof message["model"] === "string" ? { model: message["model"] } : {}),
+            };
         for (const block of message["content"]) {
             if (block["type"] === "text" &&
                 !nested &&

package/dist/drivers/native/codex-app-server.d.ts

@@ -1,5 +1,5 @@
 /**
- * Codex 原生驱动：`codex app-server`（stdio JSON-RPC，docs/wave5-plan.md §5.1，R2 §1.3）。[W5-E]
+ * Codex 原生驱动：`codex app-server`（stdio JSON-RPC，docs/history/wave5-plan.md §5.1，R2 §1.3）。[W5-E]
  *
  * - `initialize{clientInfo}` → `initialized` 通知 → `thread/start`（或 `thread/resume`，带
  *   `excludeTurns` 不回放）→ 每回合 `turn/start`，以对应 turn 的 `turn/completed` 结束；

package/dist/drivers/native/codex-app-server.js

@@ -1,5 +1,5 @@
 /**
- * Codex 原生驱动：`codex app-server`（stdio JSON-RPC，docs/wave5-plan.md §5.1，R2 §1.3）。[W5-E]
+ * Codex 原生驱动：`codex app-server`（stdio JSON-RPC，docs/history/wave5-plan.md §5.1，R2 §1.3）。[W5-E]
  *
  * - `initialize{clientInfo}` → `initialized` 通知 → `thread/start`（或 `thread/resume`，带
  *   `excludeTurns` 不回放）→ 每回合 `turn/start`，以对应 turn 的 `turn/completed` 结束；
@@ -231,11 +231,13 @@ class CodexSession {
         const start = this.tokensAtStart;
         const end = this.tokensTotal;
         if (end !== undefined) {
+            // Codex 的 inputTokens 含缓存命中部分；ama 的 input 不含（与 cacheRead 相加才是总输入）
+            const cacheRead = end.cachedInputTokens - (start?.cachedInputTokens ?? 0);
             turn.push({
                 type: "usage",
-                input: end.inputTokens - (start?.inputTokens ?? 0),
+                input: end.inputTokens - (start?.inputTokens ?? 0) - cacheRead,
                 output: end.outputTokens - (start?.outputTokens ?? 0),
-                cacheRead: end.cachedInputTokens - (start?.cachedInputTokens ?? 0),
+                cacheRead,
                 ...(this.contextTokens !== undefined ? { contextTokens: this.contextTokens } : {}),
                 ...(this.contextWindow !== undefined ? { contextWindow: this.contextWindow } : {}),
             });

package/dist/drivers/native/codex-normalize.d.ts

@@ -1,5 +1,5 @@
 /**
- * Codex app-server（0.160.x，`[experimental]`）↔ ama 的映射（docs/wave5-plan.md §5.1 normalize，
+ * Codex app-server（0.160.x，`[experimental]`）↔ ama 的映射（docs/history/wave5-plan.md §5.1 normalize，
  * R2 §1.3）。[W5-E]
  *
  * 只依赖 `test/fixtures/drivers/codex-schema/shapes.json` 锁住的方法与字段（12 个方法 + 5 类审批

package/dist/drivers/native/codex-normalize.js

@@ -1,5 +1,5 @@
 /**
- * Codex app-server（0.160.x，`[experimental]`）↔ ama 的映射（docs/wave5-plan.md §5.1 normalize，
+ * Codex app-server（0.160.x，`[experimental]`）↔ ama 的映射（docs/history/wave5-plan.md §5.1 normalize，
  * R2 §1.3）。[W5-E]
  *
  * 只依赖 `test/fixtures/drivers/codex-schema/shapes.json` 锁住的方法与字段（12 个方法 + 5 类审批

package/dist/drivers/native/oneshot.d.ts

@@ -1,5 +1,5 @@
 /**
- * 一次性打印模式兜底（docs/wave5-plan.md §5.1 oneshot.ts）。[W5-E]
+ * 一次性打印模式兜底（docs/history/wave5-plan.md §5.1 oneshot.ts）。[W5-E]
  *
  * `claude -p --output-format json`、`codex exec --json`、`gemini -p --output-format stream-json`：
  * **不能审批**（能力 `permissions: "none"`），所以只在只读任务下用——open 时模式不是

package/dist/drivers/native/oneshot.js

@@ -1,5 +1,5 @@
 /**
- * 一次性打印模式兜底（docs/wave5-plan.md §5.1 oneshot.ts）。[W5-E]
+ * 一次性打印模式兜底（docs/history/wave5-plan.md §5.1 oneshot.ts）。[W5-E]
  *
  * `claude -p --output-format json`、`codex exec --json`、`gemini -p --output-format stream-json`：
  * **不能审批**（能力 `permissions: "none"`），所以只在只读任务下用——open 时模式不是
@@ -36,7 +36,15 @@ export function oneshotArgs(dialect, options, session, prompt) {
             return args;
         }
         case "codex": {
-            const common = ["--json", "-c", 'sandbox_mode="read-only"', "-c", 'approval_policy="never"'];
+            // ama 只在自己已信任的目录里起外部 Agent：跳过 codex 自己的 git 仓库检查（非 git 目录否则直接失败）
+            const common = [
+                "--json",
+                "--skip-git-repo-check",
+                "-c",
+                'sandbox_mode="read-only"',
+                "-c",
+                'approval_policy="never"',
+            ];
             if (options.model !== undefined)
                 common.push("-m", options.model);
             return session.resume
@@ -243,9 +251,11 @@ class OneshotSession {
             }
             case "turn.completed": {
                 const u = (msg["usage"] ?? {});
+                // input_tokens 含缓存命中部分；ama 的 input 不含
+                const input = u["input_tokens"];
                 turn.push({
                     type: "usage",
-                    ...(u["input_tokens"] !== undefined ? { input: u["input_tokens"] } : {}),
+                    ...(input !== undefined ? { input: input - (u["cached_input_tokens"] ?? 0) } : {}),
                     ...(u["output_tokens"] !== undefined ? { output: u["output_tokens"] } : {}),
                     ...(u["cached_input_tokens"] !== undefined
                         ? { cacheRead: u["cached_input_tokens"] }

package/dist/drivers/native/pi-gate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * pi 的审批闸（#198）：pi 自己没有审批通道，ama 以 `-e <文件>` 给这一次运行加载一个最小扩展，
+ * 把只读内置工具以外的每次工具调用经 RPC 的扩展对话框（`extension_ui_request{method: confirm}`）
+ * 交给 ama——ama 再按模式决定直接拒绝、直接放行（auto-edit 下的文件编辑）或交给人。
+ *
+ * 扩展文件写在每个会话自己的临时目录（`mkdtemp`，只有当前用户可写），会话关闭时删除；
+ * 不写 pi 的配置目录，不改用户的扩展设置。
+ */
+/** 对话框标题：ama 只认这个标题的 confirm，其它扩展的对话框一律取消（不代答）。 */
+export declare const PI_GATE_TITLE = "ama-approval";
+/** pi 不经审批就放行的内置只读工具（也用于只读模式的 `--tools`）。 */
+export declare const PI_READ_ONLY_TOOLS: readonly string[];
+/** 扩展源码（pi 用 jiti 加载 TypeScript；这里只用纯 JS 语法）。 */
+export declare const PI_GATE_SOURCE: string;
+/** 写一份闸扩展，返回路径与清理函数。 */
+export declare function writePiGate(): {
+    path: string;
+    dispose(): void;
+};

package/dist/drivers/native/pi-gate.js

@@ -0,0 +1,39 @@
+/**
+ * pi 的审批闸（#198）：pi 自己没有审批通道，ama 以 `-e <文件>` 给这一次运行加载一个最小扩展，
+ * 把只读内置工具以外的每次工具调用经 RPC 的扩展对话框（`extension_ui_request{method: confirm}`）
+ * 交给 ama——ama 再按模式决定直接拒绝、直接放行（auto-edit 下的文件编辑）或交给人。
+ *
+ * 扩展文件写在每个会话自己的临时目录（`mkdtemp`，只有当前用户可写），会话关闭时删除；
+ * 不写 pi 的配置目录，不改用户的扩展设置。
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** 对话框标题：ama 只认这个标题的 confirm，其它扩展的对话框一律取消（不代答）。 */
+export const PI_GATE_TITLE = "ama-approval";
+/** pi 不经审批就放行的内置只读工具（也用于只读模式的 `--tools`）。 */
+export const PI_READ_ONLY_TOOLS = ["read", "grep", "find", "ls"];
+/** 扩展源码（pi 用 jiti 加载 TypeScript；这里只用纯 JS 语法）。 */
+export const PI_GATE_SOURCE = `// Generated by ama for one pi run: routes non-read-only tool calls to ama for approval.
+const READ_ONLY = new Set(${JSON.stringify(PI_READ_ONLY_TOOLS)});
+export default function (pi) {
+  pi.on("tool_call", async (event, ctx) => {
+    if (READ_ONLY.has(event.toolName)) return undefined;
+    const ok = await ctx.ui.confirm(
+      ${JSON.stringify(PI_GATE_TITLE)},
+      JSON.stringify({ id: event.toolCallId, tool: event.toolName, input: event.input }),
+    );
+    return ok ? undefined : { block: true, reason: event.toolName + " was not approved by the user" };
+  });
+}
+`;
+/** 写一份闸扩展，返回路径与清理函数。 */
+export function writePiGate() {
+    const dir = mkdtempSync(join(tmpdir(), "ama-pi-"));
+    const path = join(dir, "ama-approval-gate.ts");
+    writeFileSync(path, PI_GATE_SOURCE, { mode: 0o600 });
+    return {
+        path,
+        dispose: () => rmSync(dir, { recursive: true, force: true }),
+    };
+}

package/dist/drivers/native/pi-rpc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * pi 原生驱动：`pi --mode rpc` 长驻进程（stdin 命令 / stdout 响应与事件，严格按 LF 分帧）。[#198]
+ *
+ * `pi --mode rpc --session-id <uuid> [--model <m>] -e <审批闸> [--tools read,grep,find,ls]`
+ * （新会话与续聊都用 `--session-id`：pi 找到同 id 的项目会话就续上，否则新建）。
+ *
+ * - 回合：`prompt` → 响应 `disposition`（`handled` 时没有运行，直接结束）→ 事件流 → `agent_settled`
+ *   结束（`aborted` 为真即中断）；运行中追加用 `steer`；中断 `abort`（15 s 看门狗）。
+ * - 审批：pi 自己不问人，ama 以 `-e` 加载审批闸（{@link PI_GATE_SOURCE}），只读内置工具以外的调用
+ *   经 `extension_ui_request{confirm, title: "ama-approval"}` 到这里：plan / allowlist 直接拒绝（并以
+ *   `--tools` 只开只读工具），auto-edit / auto / full-auto 放行 `edit` / `write`，其余交给人（只交给人，
+ *   不代答）。其它扩展的对话框（select / input / editor / 别的 confirm）一律取消并提示。
+ * - 用量：assistant `message_end` 的 usage 累加（input 不含缓存命中，cost.total 是 pi 按价目表的估算）；
+ *   回合结束后 `get_session_stats` 的 `contextUsage` 记上下文占用与窗口。
+ */
+import { type DriverDeps } from "../base.js";
+import type { CatalogCandidate } from "../catalog.js";
+import type { AcpToolKind, AgentDriver, DriverOpenOptions, DriverProbe, DriverSession } from "../types.js";
+export declare function piArgs(options: Pick<DriverOpenOptions, "mode" | "model">, sessionId: string, gatePath: string): string[];
+export declare function piToolKind(tool: string): AcpToolKind;
+export declare class PiRpcDriver implements AgentDriver {
+    readonly agentId: string;
+    private readonly candidate;
+    private readonly deps;
+    readonly kind: "pi-rpc";
+    constructor(agentId: string, candidate: CatalogCandidate, deps?: DriverDeps);
+    probe(): Promise<DriverProbe>;
+    open(options: DriverOpenOptions): Promise<DriverSession>;
+}