@armadra/agent 0.3.0 → 0.5.0

package/dist/agent/tool-runner.js

@@ -7,24 +7,34 @@
  * `tool_execution_end` 按完成顺序发；toolResult 消息按原序发 `message_start/end`（入转录）。
  * `terminate` 要整批都为真才提前结束。`stopReason: "length"` 且有工具调用 → 整批判失败不执行。
  * abort：未开始的调用直接给 `aborted by user` 错误结果；执行中的工具收到 signal，超过宽限期仍未结束
- * 则不再等待、记 `aborted by user`。结果超 `maxToolResultChars` 截断并把全文写到 `outputDir`。
+ * 则不再等待、记 `aborted by user`。结果超 `maxToolResultChars` 截断并把全文写到 `outputDir`：
+ * [W5-H2] 保留头 70% + 尾 30%，中间 `[… N 字符已省略，全文 <path>]`（tools/truncate.ts）。
  *
  * 嵌套调用（`ToolContext.tools.executeTool`，codemode 脚本里的 `tools.*`）走 `runSingleToolCall`：
  * 同一套校验与门禁，按**全部未禁用工具**查找（codemode only 模式下活动集只有 codemode），
  * 发带 `parentToolCallId` 的 `tool_execution_start / update / end`（不入转录），门禁与 PostToolUse
  * 拿到 `parent`（Hook 输入的 `viaCodemode / parentToolCallId`）；结果给脚本而不是模型，截断上限放宽到
  * `NESTED_MAX_RESULT_CHARS`。
+ *
+ * [W5-H2] 重复调用检测（loop-guard.ts）只看顶层调用：同 run 同名同参第 3、4 次在结果末尾追加提醒，
+ * 第 5 次不执行、给错误结果，整批返回 `stop: "repeated_tool_call"`（循环据此结束 run）。
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { REPEATED_TOOL_CALL, guardFor, loopReminderText, loopStopText, } from "./loop-guard.js";
 import { formatSchemaErrors, validateSchema } from "./schema.js";
 import { CODEMODE_TOOL } from "../tools/presets.js";
 import { executionModeOf } from "../tools/registry.js";
+import { truncateMiddle } from "../tools/truncate.js";
 export const ABORTED_TOOL_TEXT = "aborted by user";
 export const DEFAULT_MAX_TOOL_RESULT_CHARS = 30_000;
 export const DEFAULT_ABORT_GRACE_MS = 3000;
 /** 嵌套调用结果的截断上限（给脚本，不进上下文）。 */
 export const NESTED_MAX_RESULT_CHARS = 1024 * 1024;
+/** 门禁给出的 auto 判定，随 tool_execution_end 发出（按调用对象记，调用结束后随之回收）。 */
+const autoDecisions = new WeakMap();
+/** 门禁拒绝（gate.block）而没有执行的调用：tool_execution_end 带 `denied`。 */
+const deniedCalls = new WeakSet();
 export function errorResult(text) {
     return { content: text, isError: true };
 }
@@ -80,9 +90,12 @@ async function prepare(call, assistant, options, signal, parent) {
     try {
         const gateContext = parent === undefined ? { signal, assistant, tool } : { signal, assistant, tool, parent };
         const gate = await options.beforeToolCall(call, gateContext);
+        if (gate.autoDecision !== undefined)
+            autoDecisions.set(call, gate.autoDecision);
         if (signal.aborted)
             return { kind: "immediate", call, result: errorResult(ABORTED_TOOL_TEXT) };
         if (gate.block === true) {
+            deniedCalls.add(call);
             return {
                 kind: "immediate",
                 call,
@@ -132,10 +145,10 @@ function truncateResult(call, result, options, nested = false) {
     const images = typeof result.content === "string"
         ? []
         : result.content.filter((block) => block.type === "image");
-    const head = `${text.slice(0, limit)}\n\n[输出过长已截断：共 ${text.length} 字符，${where}]`;
+    const { content } = truncateMiddle(text, limit, (omitted) => `[… ${omitted} 字符已省略（输出过长已截断：共 ${text.length} 字符，${where}）]`);
     return {
         ...result,
-        content: images.length > 0 ? [{ type: "text", text: head }, ...images] : head,
+        content: images.length > 0 ? [{ type: "text", text: content }, ...images] : content,
     };
 }
 async function execute(prepared, options, signal, emit, parent) {
@@ -193,13 +206,19 @@ async function execute(prepared, options, signal, emit, parent) {
     return truncateResult(call, result, options, parent !== undefined);
 }
 async function emitEnd(call, result, emit) {
-    await emit({
+    const event = {
         type: "tool_execution_end",
         toolCallId: call.id,
         toolName: call.name,
         result,
         isError: result.isError === true,
-    });
+    };
+    const auto = autoDecisions.get(call);
+    if (auto !== undefined)
+        event.autoDecision = auto;
+    if (deniedCalls.has(call))
+        event.denied = true;
+    await emit(event);
 }
 async function emitResultMessages(finalized, emit) {
     const messages = [];
@@ -214,6 +233,9 @@ async function emitResultMessages(finalized, emit) {
 export async function runToolBatch(assistant, options, signal, emit) {
     const calls = toolCallsOf(assistant);
     const preparedList = [];
+    const guard = guardFor(signal);
+    const verdicts = new Map();
+    let stop;
     for (const call of calls) {
         await emit({
             type: "tool_execution_start",
@@ -221,6 +243,15 @@ export async function runToolBatch(assistant, options, signal, emit) {
             toolName: call.name,
             args: call.arguments,
         });
+        const verdict = guard.observe(call, options.getTool(call.name));
+        verdicts.set(call, verdict);
+        if (verdict === "stop") {
+            stop = REPEATED_TOOL_CALL;
+            const result = errorResult(loopStopText(call.name, guard.count(call)));
+            await emitEnd(call, result, emit);
+            preparedList.push({ kind: "immediate", call, result });
+            continue;
+        }
         const prepared = await prepare(call, assistant, options, signal);
         if (prepared.kind === "immediate")
             await emitEnd(call, prepared.result, emit);
@@ -249,9 +280,44 @@ export async function runToolBatch(assistant, options, signal, emit) {
         }));
         finalized.push(...results);
     }
+    appendBatchSuffix(finalized, signal, stop);
+    for (const item of finalized) {
+        if (verdicts.get(item.call) === "remind")
+            item.result = withReminder(item.result, loopReminderText(item.call.name, guard.count(item.call)));
+    }
     const messages = await emitResultMessages(finalized, emit);
     const terminate = finalized.length > 0 && finalized.every(({ result }) => result.terminate === true);
-    return { messages, terminate };
+    return stop === undefined ? { messages, terminate } : { messages, terminate, stop };
+}
+/**
+ * [W5-H2] 本 run 的「批次尾部提醒」来源（reminders.ts 在 agent_start 时以 run 的 signal 登记）：
+ * 每个工具批次结束时取一次，非空就追加在本批**最后一条**结果末尾——run 进行中的提醒（todo 复述、
+ * 文件改动、上下文用量、预算、后台命令退出）由此进上下文，只改新结果、不碰前缀。
+ */
+const batchSuffixSources = new WeakMap();
+export function setBatchSuffixSource(signal, source) {
+    batchSuffixSources.set(signal, source);
+}
+function appendBatchSuffix(finalized, signal, stop) {
+    const last = finalized.at(-1);
+    if (last === undefined || stop !== undefined || signal.aborted)
+        return;
+    let suffix;
+    try {
+        suffix = batchSuffixSources.get(signal)?.();
+    }
+    catch {
+        suffix = undefined;
+    }
+    if (suffix !== undefined && suffix !== "")
+        last.result = withReminder(last.result, suffix);
+}
+/** 在结果末尾追加一段文本（字符串结果拼接，块数组追加 text 块）。 */
+function withReminder(result, text) {
+    const content = typeof result.content === "string"
+        ? `${result.content}\n\n${text}`
+        : [...result.content, { type: "text", text }];
+    return { ...result, content };
 }
 /** `length` 截断的助手消息：整批判失败，不执行。 */
 export async function failTruncatedBatch(assistant, emit) {

package/dist/agent/types-w5.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 第五波会话契约（docs/wave5-plan.md §1.3、§5.4、§6.3、§6.5、§7.5、§8.3；[W5-C0]）。
+ *
+ * 这里放新增事件的载荷与 `SessionStats` 的扩展形状，由 agent/types.ts 并入 `SessionEvent` /
+ * `SessionStats` 并再导出（agent/types.ts 已接近 600 行）。全部是新增事件与可选字段：
+ * `RpcEvent` 由 `SessionEvent` 派生，新事件自动上线；`RPC_PROTOCOL_VERSION` 不变。
+ * 实现归各批次：遥测 W5-A、子 Agent W5-G（外部 runner W5-E）、计划 / todo W5-F、
+ * 预算 / 回退 / 后台命令 W5-H2。
+ */
+import type { ModelRef, Usage } from "../ai/types.js";
+import type { PermissionMode } from "../permissions/types.js";
+import type { SubagentStatus } from "../tools/types.js";
+export type { SubagentStatus } from "../tools/types.js";
+/** 一次 `purpose: "turn"` 请求的速率数据。 */
+export interface RequestTelemetry {
+    requestAt: number;
+    /** 首个 text_delta / thinking_delta / toolcall_start。 */
+    firstTokenAt?: number;
+    doneAt?: number;
+    /** usage.output（含 reasoning）；流式期间用增量字符估算。 */
+    outputTokens?: number;
+    /** outputTokens / (doneAt − firstTokenAt)。 */
+    tps?: number;
+    ttftMs?: number;
+}
+export interface SessionTelemetry {
+    /** 最近一次 turn 请求。 */
+    last?: RequestTelemetry;
+    /** 流式中（2 s 滑动窗口）。 */
+    live?: {
+        tps: number;
+        outputTokens: number;
+        elapsedMs: number;
+    };
+    /** 会话内全部 turn 请求的 Σoutput / Σ(done − firstToken)。 */
+    avgTps?: number;
+    /** 本进程打开该会话的时刻（不是会话文件创建时间）。 */
+    sessionStartedAt: number;
+}
+/** 外部 Agent 的用量单位（Codex 订阅 token、Copilot premium request 等不换算美元）。 */
+export type ExternalUsageUnit = "usd" | "tokens" | "requests";
+export interface SubagentStartEvent {
+    type: "subagent_start";
+    taskId: string;
+    parentToolCallId: string;
+    /** 子 Agent 类型（`general` / `explore` / 定义文件名 / 外部 Agent id）。 */
+    agent: string;
+    /** `ama` | `claude` | `codex` | `acp:<program>` | 宿主 runner id。 */
+    runner: string;
+    description: string;
+    background: boolean;
+    model?: string;
+    sessionFile?: string;
+    cwd: string;
+}
+export interface SubagentUpdateEvent {
+    type: "subagent_update";
+    taskId: string;
+    kind: "tool" | "text" | "turn";
+    toolName?: string;
+    /** 文本增量（节流 ≥ 250 ms 合并）。 */
+    textDelta?: string;
+    turn: number;
+    usage?: Usage;
+}
+export interface SubagentEndEvent {
+    type: "subagent_end";
+    taskId: string;
+    status: SubagentStatus;
+    /** 外部 runner 可能拿不到 token 用量。 */
+    usage?: Usage;
+    cache?: {
+        hitRate?: number;
+        reBilledTokens: number;
+    };
+    /** 全文结果（> 50 KB 截断时）。 */
+    outputFile?: string;
+    worktree?: {
+        branch: string;
+        changed: boolean;
+    };
+}
+export interface PlanStep {
+    /** `S1`、`S2` …；编号列表时按序号生成。 */
+    id: string;
+    text: string;
+    dependsOn?: string[];
+    /** 建议执行者（`[agent: codex]`）。 */
+    agent?: string;
+}
+/** `custom{customType:"ama.plan"}` 的 data，也是 RPC `get_plan` 的返回。 */
+export interface PlanData {
+    id: string;
+    version: number;
+    status: "proposed" | "approved" | "rejected" | "superseded";
+    markdown: string;
+    steps: PlanStep[];
+    sourceEntryId: string;
+    filePath?: string;
+}
+/** `custom{customType:"ama.plan_state"}` 的 data（resume 回到 plan 模式）。 */
+export interface PlanStateData {
+    active: boolean;
+    prePlanMode: PermissionMode;
+    planId?: string;
+}
+/** 审批四选项 + 拒绝（Esc）。 */
+export type PlanDecisionKind = "approve" | "approve_fresh" | "revise" | "reject";
+export interface PlanProposedEvent {
+    type: "plan_proposed";
+    planId: string;
+    version: number;
+    markdown: string;
+    steps: PlanStep[];
+    filePath?: string;
+}
+export interface PlanResolvedEvent {
+    type: "plan_resolved";
+    planId: string;
+    decision: PlanDecisionKind;
+    /** `approve` 时指定的执行模式（缺省回到进入 plan 前的模式）。 */
+    mode?: PermissionMode;
+}
+/** todo 条目的线上形状（与 `tools/todo.ts` 的 `TodoItem` 结构兼容；`planStep` 由 W5-F 加）。 */
+export interface TodoItemView {
+    id: string;
+    text: string;
+    status: "pending" | "in_progress" | "done";
+    planStep?: string;
+}
+export interface TodoUpdatedEvent {
+    type: "todo_updated";
+    items: TodoItemView[];
+}
+export type LimitKind = "turns" | "cost";
+/** `--max-turns` / `--max-cost` / `limits.*` 到限；`-p` 下以退出码 7 结束。 */
+export interface LimitReachedEvent {
+    type: "limit_reached";
+    kind: LimitKind;
+    /** 到限时的值（回合数或美元）。 */
+    value: number;
+    limit: number;
+}
+export interface ModelFallbackEvent {
+    type: "model_fallback";
+    from: ModelRef;
+    to: ModelRef;
+    /** 触发原因（`overloaded` / 重试用尽的错误文本）。 */
+    reason: string;
+}
+export interface BackgroundJobEvent {
+    type: "background_job";
+    jobId: string;
+    phase: "started" | "exited" | "stopped";
+    command: string;
+    pid?: number;
+    outputPath?: string;
+    exitCode?: number | null;
+}
+export type SessionEventW5 = 
+/** 流式中 ≤ 2 Hz（`ui.animation: false` 时不发）；数据从 `getStats().telemetry` 取。 */
+{
+    type: "telemetry_tick";
+} | SubagentStartEvent | SubagentUpdateEvent | SubagentEndEvent | PlanProposedEvent | PlanResolvedEvent | TodoUpdatedEvent | LimitReachedEvent | ModelFallbackEvent | BackgroundJobEvent;
+/** 外部 Agent 记账（`custom{ama.agent-usage}` 汇总，§5.4）。 */
+export interface ExternalAgentStats {
+    byAgent: Record<string, {
+        runs: number;
+        unit: ExternalUsageUnit;
+        amount: number;
+        tokens?: number;
+    }>;
+}
+/** 子 Agent 任务注册表的汇总（`/session` 与 `get_session_stats`）。 */
+export interface SessionTaskStats {
+    total: number;
+    running: number;
+    byStatus: Partial<Record<SubagentStatus, number>>;
+}
+export interface SessionStatsW5 {
+    /** [W5-A] 速率与会话时长；遥测扩展未装配时缺省。 */
+    telemetry?: SessionTelemetry;
+    /** [W5-E] 外部 Agent 用量；没有外部运行时缺省。 */
+    external?: ExternalAgentStats;
+    /** [W5-G] 子 Agent 任务；没有任务时缺省。 */
+    tasks?: SessionTaskStats;
+}
+/** `limits` 选项（`--max-turns` / `--max-cost` / config `limits.*`），W5-H2 实现。 */
+export interface SessionLimits {
+    maxTurns?: number;
+    maxCostUsd?: number;
+}

package/dist/agent/types-w5.js

@@ -0,0 +1,10 @@
+/**
+ * 第五波会话契约（docs/wave5-plan.md §1.3、§5.4、§6.3、§6.5、§7.5、§8.3；[W5-C0]）。
+ *
+ * 这里放新增事件的载荷与 `SessionStats` 的扩展形状，由 agent/types.ts 并入 `SessionEvent` /
+ * `SessionStats` 并再导出（agent/types.ts 已接近 600 行）。全部是新增事件与可选字段：
+ * `RpcEvent` 由 `SessionEvent` 派生，新事件自动上线；`RPC_PROTOCOL_VERSION` 不变。
+ * 实现归各批次：遥测 W5-A、子 Agent W5-G（外部 runner W5-E）、计划 / todo W5-F、
+ * 预算 / 回退 / 后台命令 W5-H2。
+ */
+export {};

package/dist/agent/types.d.ts

@@ -17,13 +17,18 @@
  * - （W3-C0）缓存可观测性（第三波 §1.10）：`SessionEvent` 加 `cache_miss` / `cache_warm` /
  *   `context_pressure`，`SessionStats.cache`（可选，C1b 填）；`CacheSettings` 是
  *   `SessionCacheController` 的解析后设置（来自 config `cache` 段与环境变量）。
+ * - （W5-C0）第五波事件与统计（遥测、子 Agent、计划 / todo、预算、回退、后台命令）定义在
+ *   agent/types-w5.ts，这里并入 `SessionEvent` / `SessionStats` 并再导出。
  */
 import type { AssistantEvent, AssistantMessage, CacheRetention, ImageBlock, Message, MessageOrigin, Model, ModelRef, ModelThinkingLevel, ToolCallBlock, ToolResultMessage, TranscriptContext, Usage } from "../ai/types.js";
 import type { CacheMiss, CacheMissReason, CacheReporting, WarmerStatus, WarmingMode } from "../ai/cache/types.js";
 import type { HookEvent } from "../hooks/types.js";
-import type { ActionPreview, ApprovalDecision, ApprovalReason, PermissionMode } from "../permissions/types.js";
-import type { AgentMessage, SessionEntry } from "../session/types.js";
+import type { ActionPreview, ApprovalDecision, ApprovalReason, AutoDecision, PermissionMode, PermissionRequestContext } from "../permissions/types.js";
+import type { AgentMessage, BranchSummaryEntry, SessionEntry } from "../session/types.js";
+import type { RewindMode, RewindPoint, RewindRequest, RewindResult, RewindSkipReason } from "../checkpoints/types.js";
 import type { ToolDefinition, ToolResult } from "../tools/types.js";
+import type { SessionEventW5, SessionStatsW5 } from "./types-w5.js";
+export type * from "./types-w5.js";
 export type { AssistantContentBlock, AssistantMessage, ContentBlock, ImageBlock, Message, StopReason, SystemMessage, TextBlock, ThinkingBlock, ToolCallBlock, ToolResultMessage, Usage, UserMessage, } from "../ai/types.js";
 export type { AgentMessage, BranchSummaryMessage, CompactionSummaryMessage, CustomMessage, } from "../session/types.js";
 export type ToolCall = ToolCallBlock;
@@ -56,6 +61,8 @@ export interface ToolCallGate {
     reason?: string;
     /** Hook 的 updatedInput 替换后的输入。 */
     input?: unknown;
+    /** auto 权限模式的判定（随 tool_execution_end 发出）。 */
+    autoDecision?: AutoDecision;
 }
 export interface LoopHooks {
     /** 档一裁剪、Hook 的 additionalContext 注入。 */
@@ -175,6 +182,10 @@ export type SessionEvent = {
     result: ToolResult;
     isError: boolean;
     parentToolCallId?: string;
+    /** auto 权限模式下这次调用的判定（层、结论、原因）；其它模式缺省。 */
+    autoDecision?: AutoDecision;
+    /** 被拒（权限管线、PreToolUse Hook、审批或无人值守）而没有执行；原因是 `result` 的文本。 */
+    denied?: true;
 } | {
     type: "queue_update";
     steering: string[];
@@ -210,6 +221,13 @@ export type SessionEvent = {
     timeoutMs: number;
     /** [W3-C0] 执行前预览（同 `ApprovalRequest.preview`）。 */
     preview?: ActionPreview;
+    /** auto 权限模式下为什么询问（同 `ApprovalRequest.autoDecision`）。 */
+    autoDecision?: AutoDecision;
+    /**
+     * [W5-EG] 发起方：`depth > 0` 来自 task 子 Agent、`taskId` 来源任务、`origin` 外部 Agent 的
+     * 权限请求（对话框标 `[claude · 会话 abc1]`）。主会话自己的调用不带。
+     */
+    context?: PermissionRequestContext;
 } | {
     type: "permission_resolved";
     requestId: string;
@@ -230,6 +248,19 @@ export type SessionEvent = {
     type: "session_changed";
     sessionId: string;
     sessionFile?: string;
+}
+/** [RW-B] 回滚完成（rewind-plan §5）：dryRun 不发；仅对话时文件清单为空。 */
+ | {
+    type: "session_rewound";
+    entryId: string;
+    mode: RewindMode;
+    restored: string[];
+    deleted: string[];
+    conflicts: string[];
+    skipped: {
+        path: string;
+        reason: RewindSkipReason;
+    }[];
 } | {
     type: "model_changed";
     model: ModelRef;
@@ -259,7 +290,9 @@ export type SessionEvent = {
     remainingTokens?: number;
     /** 按最近 5 回合均值估算。 */
     estimatedTurnsLeft?: number;
-};
+}
+/** [W5-C0] 第五波事件（agent/types-w5.ts）。 */
+ | SessionEventW5;
 export type SessionEventType = SessionEvent["type"];
 export type PromptDisposition = "started" | "queued" | "handled";
 export interface PromptOptions {
@@ -291,7 +324,8 @@ export interface SessionState {
     autoCompaction: boolean;
     autoRetry: boolean;
 }
-export interface SessionStats {
+/** [W5-C0] `telemetry? / external? / tasks?` 见 `SessionStatsW5`。 */
+export interface SessionStats extends SessionStatsW5 {
     sessionId: string;
     sessionFile: string | undefined;
     userMessages: number;
@@ -374,5 +408,22 @@ export interface AgentSession {
     readonly entries: readonly SessionEntry[];
     getLastAssistantText(): string | null;
     getStats(): SessionStats;
+    /** [RW-B] 活动路径上开启新回合的用户消息，从旧到新（rewind-plan §3.1）。 */
+    rewindPoints(): RewindPoint[];
+    /** [RW-B] 运行中 → busy；全部失败且无一恢复 → rewind_failed。 */
+    rewind(request: RewindRequest): Promise<RewindResult>;
+    /** [RW-B] 「从这里摘要」：回到该消息之前并为离开的分支写摘要，返回原消息草稿。 */
+    summarizeFrom(entryId: string, instructions?: string): Promise<{
+        leafId: string | null;
+        draft: RewindDraftText;
+        summary?: BranchSummaryEntry;
+    }>;
+    /** [RW-B] 「摘要到这里」：以该消息为切点压缩之前的上下文，停在末尾。 */
+    summarizeUpTo(entryId: string, instructions?: string): Promise<CompactionResult>;
     dispose(): Promise<void>;
 }
+/** [RW-B] 回滚回填的原消息。 */
+export type RewindDraftText = {
+    text: string;
+    images?: ImageBlock[];
+};

package/dist/agent/types.js

@@ -17,5 +17,7 @@
  * - （W3-C0）缓存可观测性（第三波 §1.10）：`SessionEvent` 加 `cache_miss` / `cache_warm` /
  *   `context_pressure`，`SessionStats.cache`（可选，C1b 填）；`CacheSettings` 是
  *   `SessionCacheController` 的解析后设置（来自 config `cache` 段与环境变量）。
+ * - （W5-C0）第五波事件与统计（遥测、子 Agent、计划 / todo、预算、回退、后台命令）定义在
+ *   agent/types-w5.ts，这里并入 `SessionEvent` / `SessionStats` 并再导出。
  */
 export {};

package/dist/agent/worktree.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 子 Agent 的 git worktree 隔离（docs/wave5-plan.md §7.4，D24）。[W5-G]
+ *
+ * - `git worktree add -b ama/task-<taskId> <repo>/.ama/worktrees/<taskId> HEAD`；子会话 cwd 指向
+ *   worktree 里与父 cwd 对应的子目录；
+ * - 结束时没有改动（工作区干净且 HEAD 未动）→ `git worktree remove --force` 并删分支；有改动则保留，
+ *   结果里给分支名与 `git diff --stat`；
+ * - 非 git 目录直接报错，不回落到共享目录；`.ama/worktrees/.gitignore` 写 `*`，父会话的 git 与
+ *   grep / glob（读嵌套 .gitignore）都看不到这些目录；
+ * - worktree 不保证可运行：依赖（node_modules 等）不共享。
+ */
+export interface Worktree {
+    /** worktree 根目录。 */
+    path: string;
+    /** 子会话 cwd（worktree 里与父 cwd 对应的目录）。 */
+    cwd: string;
+    branch: string;
+    /** 创建时的提交（判断有无新提交）。 */
+    base: string;
+    repo: string;
+}
+export interface WorktreeOutcome {
+    branch: string;
+    changed: boolean;
+    /** 有改动时：`git diff --stat <base>` 与未跟踪文件。 */
+    diffStat?: string;
+    /** 保留时的路径。 */
+    path?: string;
+}
+export type GitRunner = (args: readonly string[], cwd: string) => Promise<string>;
+export declare const runGit: GitRunner;
+export declare function worktreeBranch(taskId: string): string;
+/** 在父 cwd 所在仓库里为任务建 worktree；非 git 目录抛错。 */
+export declare function createWorktree(cwd: string, taskId: string, git?: GitRunner): Promise<Worktree>;
+/** 运行结束：无改动删除 worktree 与分支；有改动保留并给 diff 摘要。 */
+export declare function finishWorktree(tree: Worktree, git?: GitRunner): Promise<WorktreeOutcome>;

package/dist/agent/worktree.js

@@ -0,0 +1,86 @@
+/**
+ * 子 Agent 的 git worktree 隔离（docs/wave5-plan.md §7.4，D24）。[W5-G]
+ *
+ * - `git worktree add -b ama/task-<taskId> <repo>/.ama/worktrees/<taskId> HEAD`；子会话 cwd 指向
+ *   worktree 里与父 cwd 对应的子目录；
+ * - 结束时没有改动（工作区干净且 HEAD 未动）→ `git worktree remove --force` 并删分支；有改动则保留，
+ *   结果里给分支名与 `git diff --stat`；
+ * - 非 git 目录直接报错，不回落到共享目录；`.ama/worktrees/.gitignore` 写 `*`，父会话的 git 与
+ *   grep / glob（读嵌套 .gitignore）都看不到这些目录；
+ * - worktree 不保证可运行：依赖（node_modules 等）不共享。
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+const TIMEOUT_MS = 30_000;
+export const runGit = (args, cwd) => new Promise((resolve, reject) => {
+    execFile("git", [...args], { cwd, timeout: TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+        if (error)
+            reject(new Error(String(stderr).trim() || error.message));
+        else
+            resolve(String(stdout));
+    });
+});
+/**
+ * 两边都取系统的真实路径再比：git 给的是真实路径（macOS 的 /var → /private/var；Windows 是长文件名、
+ * 正斜杠），而 cwd 可能是 8.3 短名（RUNNER~1）或符号链接。
+ */
+function realPath(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return path;
+    }
+}
+export function worktreeBranch(taskId) {
+    return `ama/task-${taskId}`;
+}
+/** 在父 cwd 所在仓库里为任务建 worktree；非 git 目录抛错。 */
+export async function createWorktree(cwd, taskId, git = runGit) {
+    let repo;
+    try {
+        repo = realPath((await git(["rev-parse", "--show-toplevel"], cwd)).trim());
+    }
+    catch {
+        throw new Error(`isolation "worktree" needs a git repository; ${cwd} is not inside one`);
+    }
+    const base = (await git(["rev-parse", "HEAD"], repo)).trim();
+    const root = join(repo, ".ama", "worktrees");
+    mkdirSync(root, { recursive: true });
+    const ignore = join(root, ".gitignore");
+    if (!existsSync(ignore))
+        writeFileSync(ignore, "*\n");
+    const path = join(root, taskId);
+    const branch = worktreeBranch(taskId);
+    if (!existsSync(path))
+        await git(["worktree", "add", "-b", branch, path, base], repo);
+    const sub = relative(repo, realPath(cwd));
+    const childCwd = sub === "" || sub.startsWith("..") ? path : join(path, sub);
+    mkdirSync(childCwd, { recursive: true });
+    return { path, cwd: childCwd, branch, base, repo };
+}
+/** 运行结束：无改动删除 worktree 与分支；有改动保留并给 diff 摘要。 */
+export async function finishWorktree(tree, git = runGit) {
+    const status = (await git(["status", "--porcelain"], tree.path)).trim();
+    const head = (await git(["rev-parse", "HEAD"], tree.path)).trim();
+    if (status === "" && head === tree.base) {
+        await git(["worktree", "remove", "--force", tree.path], tree.repo);
+        await git(["branch", "-D", tree.branch], tree.repo).catch(() => "");
+        return { branch: tree.branch, changed: false };
+    }
+    const stat = (await git(["diff", "--stat", tree.base], tree.path).catch(() => "")).trim();
+    const untracked = status
+        .split("\n")
+        .filter((line) => line.startsWith("??"))
+        .map((line) => line.slice(3));
+    const parts = [stat];
+    if (untracked.length > 0)
+        parts.push(`untracked: ${untracked.join(", ")}`);
+    return {
+        branch: tree.branch,
+        changed: true,
+        diffStat: parts.filter((part) => part !== "").join("\n"),
+        path: tree.path,
+    };
+}

package/dist/agents/builtin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 内置子 Agent 类型（docs/wave5-plan.md §7.2，D22–D23）。[W5-G]
+ *
+ * 三个类型都用父会话的活动工具集（工具表与父字节一致，缓存前缀可复用）；只读靠权限层：
+ * `explore` / `plan` 的 `permissionMode: "plan"` 让子会话用 plan 模式的管线，写类工具与非只读 bash
+ * 被拒绝且不弹审批（session-subagent.ts）。正文是追加到子会话系统提示末尾的角色说明（`role` 节）。
+ */
+import type { AgentDefinition } from "./types.js";
+/** 所有 ama 子会话共有的角色说明（类型正文追加在它后面）。 */
+export declare const SUBAGENT_ROLE_PREAMBLE: string;
+export declare const BUILTIN_AGENTS: readonly AgentDefinition[];
+export declare const DEFAULT_AGENT = "general";
+/** 子会话系统提示 `role` 节：通用说明 + 类型正文。 */
+export declare function agentRole(agent: Pick<AgentDefinition, "prompt">): string;

package/dist/agents/builtin.js

@@ -0,0 +1,39 @@
+/**
+ * 内置子 Agent 类型（docs/wave5-plan.md §7.2，D22–D23）。[W5-G]
+ *
+ * 三个类型都用父会话的活动工具集（工具表与父字节一致，缓存前缀可复用）；只读靠权限层：
+ * `explore` / `plan` 的 `permissionMode: "plan"` 让子会话用 plan 模式的管线，写类工具与非只读 bash
+ * 被拒绝且不弹审批（session-subagent.ts）。正文是追加到子会话系统提示末尾的角色说明（`role` 节）。
+ */
+/** 所有 ama 子会话共有的角色说明（类型正文追加在它后面）。 */
+export const SUBAGENT_ROLE_PREAMBLE = "You are a sub-agent: the main agent delegated one task to you. It cannot see your work, only " +
+    "your final reply. Complete the task directly; do not delegate further. End with a concise " +
+    "report: what you did, key findings, and files changed (if any).";
+function builtin(name, description, prompt, permissionMode) {
+    return {
+        name,
+        description,
+        permissionMode,
+        model: "inherit",
+        maxTurns: 30,
+        isolation: "none",
+        background: false,
+        runner: "ama",
+        prompt,
+        source: "builtin",
+    };
+}
+export const BUILTIN_AGENTS = Object.freeze([
+    builtin("general", "General-purpose sub-agent (default): researches and changes code like you do.", "", "inherit"),
+    builtin("explore", "Read-only search: locates files, symbols and code paths; returns paths with line numbers.", "Locate, do not review. Return file paths with line numbers and short notes on what is " +
+        "where. State the search scope you covered. You cannot modify files; bash runs read-only " +
+        "commands only.", "plan"),
+    builtin("plan", "Read-only planner: returns a step-by-step plan with key files and trade-offs.", "Produce a step-by-step implementation plan: key files to change, the order of steps, and " +
+        "trade-offs or risks. Do not modify files; you are read-only.", "plan"),
+]);
+export const DEFAULT_AGENT = "general";
+/** 子会话系统提示 `role` 节：通用说明 + 类型正文。 */
+export function agentRole(agent) {
+    const own = agent.prompt.trim();
+    return own === "" ? SUBAGENT_ROLE_PREAMBLE : `${SUBAGENT_ROLE_PREAMBLE}\n\n${own}`;
+}