@zhushanwen/pi-plan 0.4.9 → 0.5.0

package/src/exec-skills.ts

@@ -0,0 +1,407 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+import {
+  CONFIG_DIR_NAME,
+  getAgentDir,
+  loadSkillsFromDir,
+  parseFrontmatter,
+} from "@earendil-works/pi-coding-agent";
+import type { Skill } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("pi-plan");
+
+/**
+ * plan-exec skill 检测（D10 选项集 v2 的 skill 数据源）。
+ *
+ * 检测语义 = 「向用户提议的执行 skill」，以 pi 本体加载集为基线做意图/信任对齐：
+ * - 单根枚举复用 pi 公开导出 loadSkillsFromDir——单根内横切规则（ignore / description
+ *   必填门 / name 派生 / 递归遍历 / symlink / node_modules / 隐藏文件）随 pi 升级
+ *   自动同步，零漂移面（对照表①③⑥⑦ 的 SKILL.md 目录形态侧）；
+ * - 跨根组装自实现（pi 的四根拼装逻辑未导出，对照表②④⑤）：根序四枚按 pi 本体
+ *   `package-manager.js addAutoDiscoveredResources`——`.pi/skills` → 祖先链
+ *   `.agents/skills`（近→远，git root 级含）→ `<agentDir>/skills` → `~/.agents/skills`
+ *   （HOME 直取，dev-flow 等用户级 skill 标准安装位）；untrusted 跳过前两族（④）；
+ *   settings overrides 的 `+/-/!` 三级优先级 disable 复刻（②）；同名 first-writer-wins
+ *   + realPath 去重（⑤）；
+ * - plan-exec marker 过滤 = 对过 description 门的 skill 二次读 frontmatter
+ *   （`plan-exec: true`；pi 的 Skill 对象不保留原始 frontmatter）。skill 侧自愿
+ *   opt-in，`disable-model-invocation` 与 plan-exec 并存不过滤（用户显式选择是
+ *   另一通路，设计 D10 顺手裁决）。
+ * - steer 执行走路径读取（read `<skillEntryPath>` = skill 入口文件路径），不依赖 pi skill 注册。
+ *
+ * 已登记偏差（对照表⑦散 .md 形态）：与 pi auto 源（collectSkillEntries）方向相反——
+ * agents 源根级散 .md 检测收而 pi 不收（多提议）、子目录散 .md pi 收而检测不收
+ * （漏提议）；`.pi/skills` 源两侧同构。settings npm 源不扫（现无 npm 发布形态
+ * plan-exec skill，出现时补第五根）。
+ *
+ * 降级规格（检测失败最坏后果 = skill 选项空集，绝不允许炸 executeComplete 的
+ * 核心交互闭环；pi 对坏 skill 也只产 diagnostics 不中断加载）：每根 existsSync
+ * 守卫 + 整根 try/catch（EACCES 等任何 fs 错 → 跳过该根 + warn）；单 skill
+ * frontmatter 读/解析失败 → 跳过该项 + warn；settings 读取/解析失败 → 视为
+ * 无 overrides。
+ */
+
+/** 降级留痕（warn 级）：缺省走 pi-extension-logger，测试注入收集器 */
+type LogFn = (msg: string, detail?: object) => void;
+
+function defaultLog(msg: string, detail?: object): void {
+  logger.warn(msg, detail);
+}
+
+/** pi getHomeDir 同式（package-manager.js:78）：HOME 优先，缺省 os.homedir() */
+function defaultHomeDir(): string {
+  return process.env.HOME || os.homedir();
+}
+
+/** pi canonicalizePath 同式：realpath 失败回退原路径 */
+function canonicalizePath(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function toPosixPath(p: string): string {
+  // 与 pi toPosixPath 同构：Windows 分隔符归一（POSIX 上恒等）
+  return sep === "\\" ? p.split("\\").join("/") : p;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** pi findGitRepoRoot 同式：.git 目录或 .git 文件（worktree）均算 root；无 git 推到文件系统根 */
+function findGitRepoRoot(startDir: string): string | null {
+  let dir = resolve(startDir);
+  while (true) {
+    if (fs.existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** pi collectAncestorAgentsSkillDirs 同式：startDir 起每级 `.agents/skills`，近→远，git root 级含 */
+function collectAncestorAgentsSkillDirs(startDir: string): string[] {
+  const skillDirs: string[] = [];
+  const resolvedStartDir = resolve(startDir);
+  const gitRepoRoot = findGitRepoRoot(resolvedStartDir);
+  let dir = resolvedStartDir;
+  while (true) {
+    skillDirs.push(join(dir, ".agents", "skills"));
+    if (gitRepoRoot && dir === gitRepoRoot) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return skillDirs;
+}
+
+/** BOM 剥离（pi stripBom 同构）：带 BOM 的 settings.json 直接 JSON.parse 会 throw */
+function stripBom(text: string): string {
+  return text.replace(/^\uFEFF/, "");
+}
+
+/**
+ * 读 settings.json 的 skills overrides（`+/-/!` pattern 数组）。
+ * 读取/解析失败 → [] + warn（pi tryLoadFromStorage 同折叠：错误不中断加载）。
+ * pi 旧形态 skills 为对象（customDirectories）——其条目无 `+/-/!` 前缀，对 override
+ * 匹配等价于无，此处按非数组折叠为 [] 即可。
+ */
+function readSkillsOverrides(settingsPath: string, log: LogFn): string[] {
+  try {
+    if (!fs.existsSync(settingsPath)) return [];
+    const parsed: unknown = JSON.parse(stripBom(fs.readFileSync(settingsPath, "utf-8")));
+    if (!isRecord(parsed)) return [];
+    const skills: unknown = parsed.skills;
+    if (!Array.isArray(skills)) return [];
+    return skills.filter((p): p is string => typeof p === "string");
+  } catch (error) {
+    log("plan: exec-skill settings parse failed (treated as no overrides)", {
+      path: settingsPath,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+}
+
+/**
+ * minimatch 子集 glob → RegExp：`**`（跨目录，段间匹配零段）/ `*`（段内任意）/ `?`
+ * （单字符，不跨 /）/ `[...]` 字符类；不支持 brace 展开等高级语法。已登记偏差：
+ * 极端 disable pattern（brace 等）可能与 pi 求值不一致——常用形态（裸名 / `x-*` /
+ * `dir/**`）语义一致。
+ */
+function globToRegExp(pattern: string): RegExp {
+  let source = "^";
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        while (pattern[i + 1] === "*") i++;
+        // 段间 `**/` 允许零段（minimatch globstar 语义），其余 `**` 跨目录任意
+        if (source.endsWith("/") && pattern[i + 1] === "/") {
+          source = `${source.slice(0, -1)}(?:.*/)?`;
+          i++;
+        } else {
+          source += ".*";
+        }
+      } else {
+        source += "[^/]*";
+      }
+    } else if (ch === "?") {
+      source += "[^/]";
+    } else if (ch === "[") {
+      const end = pattern.indexOf("]", i + 1);
+      if (end === -1) {
+        source += "\\[";
+      } else {
+        let cls = pattern.slice(i + 1, end);
+        if (cls.startsWith("!")) cls = `^${cls.slice(1)}`;
+        source += `[${cls}]`;
+        i = end;
+      }
+    } else {
+      source += ch.replace(/[\\^$.+(){}|]/g, "\\$&");
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+
+/** pi normalizeExactPattern 同式：剥前导 `./`（+/- 精确匹配形态归一，只剥一次） */
+function normalizeExactPattern(pattern: string): string {
+  return toPosixPath(pattern.replace(/^\.\/|^\.\\/, ""));
+}
+
+/**
+ * pi matchesAnyPattern 同构（`!` 排除侧的 glob 匹配）：rel / 文件名 / 绝对路径，
+ * SKILL.md 再加父目录的 rel / 名 / 绝对路径三形态——`!dev-flow` 即靠父目录名命中。
+ */
+function matchesAnyGlobPattern(filePath: string, patterns: string[], baseDir: string): boolean {
+  if (patterns.length === 0) return false;
+  const regexes = patterns.map(globToRegExp);
+  const candidates = globMatchCandidates(filePath, baseDir);
+  return candidates.some((candidate) => regexes.some((re) => re.test(candidate)));
+}
+
+/** 匹配候选形态（glob 侧 6 形态 / 精确侧 4 形态的公共部分按需取用） */
+function globMatchCandidates(filePath: string, baseDir: string): string[] {
+  const rel = toPosixPath(relative(baseDir, filePath));
+  const name = basename(filePath);
+  const filePathPosix = toPosixPath(filePath);
+  const isSkillFile = name === "SKILL.md";
+  if (!isSkillFile) return [rel, name, filePathPosix];
+  const parentDir = dirname(filePath);
+  return [
+    rel,
+    name,
+    filePathPosix,
+    toPosixPath(relative(baseDir, parentDir)),
+    basename(parentDir),
+    toPosixPath(parentDir),
+  ];
+}
+
+/** pi matchesAnyExactPattern 同构（`+`/`-` 精确侧）：rel / 绝对路径 + SKILL.md 父目录两形态，无 glob */
+function matchesAnyExactPattern(filePath: string, patterns: string[], baseDir: string): boolean {
+  if (patterns.length === 0) return false;
+  const rel = toPosixPath(relative(baseDir, filePath));
+  const filePathPosix = toPosixPath(filePath);
+  const isSkillFile = basename(filePath) === "SKILL.md";
+  const parentDir = isSkillFile ? dirname(filePath) : undefined;
+  const parentRel = parentDir !== undefined ? toPosixPath(relative(baseDir, parentDir)) : undefined;
+  const parentDirPosix = parentDir !== undefined ? toPosixPath(parentDir) : undefined;
+  return patterns.some((pattern) => {
+    const normalized = normalizeExactPattern(pattern);
+    if (normalized === rel || normalized === filePathPosix) return true;
+    return (parentRel !== undefined && normalized === parentRel)
+      || (parentDirPosix !== undefined && normalized === parentDirPosix);
+  });
+}
+
+/** pi isEnabledByOverrides 同构：三级优先级 `-` > `+` > `!` > 默认启用（横切全部根） */
+export function isEnabledByOverrides(filePath: string, patterns: string[], baseDir: string): boolean {
+  const overrides = patterns.filter((p) => p.startsWith("!") || p.startsWith("+") || p.startsWith("-"));
+  const excludes = overrides.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
+  const forceIncludes = overrides.filter((p) => p.startsWith("+")).map((p) => p.slice(1));
+  const forceExcludes = overrides.filter((p) => p.startsWith("-")).map((p) => p.slice(1));
+  let enabled = true;
+  if (excludes.length > 0 && matchesAnyGlobPattern(filePath, excludes, baseDir)) {
+    enabled = false;
+  }
+  if (forceIncludes.length > 0 && matchesAnyExactPattern(filePath, forceIncludes, baseDir)) {
+    enabled = true;
+  }
+  if (forceExcludes.length > 0 && matchesAnyExactPattern(filePath, forceExcludes, baseDir)) {
+    enabled = false;
+  }
+  return enabled;
+}
+
+/** plan-exec marker 的 frontmatter 键（skill 侧自愿 opt-in：SKILL.md 加一行 `plan-exec: true`） */
+const PLAN_EXEC_MARKER_FIELD = "plan-exec";
+
+/**
+ * 二次读 frontmatter 判 plan-exec marker（pi 的 Skill 对象不保留原始 frontmatter；
+ * pi 加载器对未知字段忽略不拒，marker 字段约定可行）。读/解析失败 → false + warn
+ * （降级：跳过该项）。严格 `=== true`：字符串 "true" 等 YAML 形态不误判。
+ */
+export function hasPlanExecMarker(skillFilePath: string, log: LogFn = defaultLog): boolean {
+  try {
+    const { frontmatter } = parseFrontmatter(fs.readFileSync(skillFilePath, "utf-8"));
+    return frontmatter[PLAN_EXEC_MARKER_FIELD] === true;
+  } catch (error) {
+    log("plan: exec-skill frontmatter read failed (skill skipped)", {
+      path: skillFilePath,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return false;
+  }
+}
+
+/** 检测产物：一个可提议为执行方式的 skill（name 与 pi prompt 列表一致，⑥） */
+export interface ExecSkill {
+  name: string;
+  description: string;
+  /** skill 入口文件路径（标准形态 = SKILL.md 路径，散 .md 形态 = 文件本身；steer 指引 read 该路径，两种形态统一无分支） */
+  skillEntryPath: string;
+}
+
+export interface DetectExecSkillsOptions {
+  /** 项目目录（`<CONFIG_DIR_NAME>/skills` 根 + 祖先链起点，目录名跟 pi CONFIG_DIR_NAME 导出）。生产调用传 ctx.cwd */
+  cwd: string;
+  /** 项目信任态（untrusted 跳过 `.pi/skills` 与祖先链两族，④）。生产调用传 ctx.isProjectTrusted() */
+  trusted: boolean;
+  /** pi agentDir（`<agentDir>/skills` 根 + 全局 settings 位置）。缺省 pi getAgentDir()（读 PI_CODING_AGENT_DIR）；测试注入 */
+  agentDir?: string;
+  /** 用户 home（`~/.agents/skills` 根）。缺省 `process.env.HOME || os.homedir()`（pi getHomeDir 同式）；测试注入 */
+  homeDir?: string;
+  /** 降级留痕（warn 级），缺省 pi-extension-logger */
+  log?: LogFn;
+}
+
+/** 检测的单根描述：目录 + overrides 求值 baseDir（pi 按根挂各自 baseDir）+ 该根适用的 overrides */
+interface SkillRoot {
+  dir: string;
+  baseDir: string;
+  overrides: string[];
+}
+
+/**
+ * 检测入口：枚举 pi 本体加载集的四根，返回带 plan-exec marker 的 skill 清单
+ * （root 序去重后）。complete 时现扫、无缓存（低频路径 + 技能热装可见性）。
+ * 永不 throw（降级规格）。
+ */
+export function detectExecSkills(options: DetectExecSkillsOptions): ExecSkill[] {
+  const log: LogFn = options.log ?? defaultLog;
+  try {
+    return detectExecSkillsInternal(options, log);
+  } catch (error) {
+    log("plan: exec-skill detection failed (degraded to empty option set)", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+}
+
+/**
+ * trusted 门内两族根（④）：`.pi/skills` 根 + 祖先链；overrides 挂 project settings。
+ * 祖先链每根 baseDir = 各自的 `.agents` 目录；与 `~/.agents/skills`
+ * 同路径的项滤掉（pi :1979 同款——cwd 在 HOME 下时防与第四根重复）。
+ */
+function collectTrustedProjectRoots(cwd: string, homeDir: string, projectOverrides: string[]): SkillRoot[] {
+  const roots: SkillRoot[] = [];
+  roots.push({ dir: join(cwd, CONFIG_DIR_NAME, "skills"), baseDir: join(cwd, CONFIG_DIR_NAME), overrides: projectOverrides });
+  const userAgentsSkillsDir = join(homeDir, ".agents", "skills");
+  for (const dir of collectAncestorAgentsSkillDirs(cwd)) {
+    if (resolve(dir) === resolve(userAgentsSkillsDir)) continue;
+    roots.push({ dir, baseDir: dirname(dir), overrides: projectOverrides });
+  }
+  return roots;
+}
+
+/** 四根 root 序组装（pi 本体加载集序，见 detectExecSkills 头注）；overrides 按根挂载 */
+function collectSkillRoots(
+  options: DetectExecSkillsOptions,
+  cwd: string,
+  agentDir: string,
+  homeDir: string,
+  log: LogFn,
+): SkillRoot[] {
+  const userOverrides = readSkillsOverrides(join(agentDir, "settings.json"), log);
+  // project settings 仅 trusted 时参与（pi loadFromStorage 对 untrusted 的 project 恒 {}）
+  const projectOverrides = options.trusted
+    ? readSkillsOverrides(join(cwd, CONFIG_DIR_NAME, "settings.json"), log)
+    : [];
+  const roots: SkillRoot[] = options.trusted
+    ? collectTrustedProjectRoots(cwd, homeDir, projectOverrides)
+    : [];
+  roots.push({ dir: join(agentDir, "skills"), baseDir: agentDir, overrides: userOverrides });
+  roots.push({ dir: join(homeDir, ".agents", "skills"), baseDir: join(homeDir, ".agents"), overrides: userOverrides });
+  return roots;
+}
+
+/**
+ * 单根扫描：overrides 过滤（②）→ first-writer-wins 去重（⑤，seen 集跨根共享）→
+ * marker 过滤。根目录缺失 / 整根读失败 → 空集（降级规格，不中断其余根）。
+ */
+function scanSkillRoot(
+  root: SkillRoot,
+  seenNames: Set<string>,
+  seenRealPaths: Set<string>,
+  log: LogFn,
+): ExecSkill[] {
+  if (!fs.existsSync(root.dir)) return []; // 合法缺省（~/.agents/skills 不存在是常态主路径）
+  let skills: Skill[];
+  try {
+    skills = loadSkillsFromDir({ dir: root.dir, source: "detect" }).skills;
+  } catch (error) {
+    log("plan: exec-skill root scan failed (root skipped)", {
+      dir: root.dir,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  }
+  const found: ExecSkill[] = [];
+  for (const skill of skills) {
+    // ② 用户显式 disable 的 skill 不提议（意图对齐）
+    if (!isEnabledByOverrides(skill.filePath, root.overrides, root.baseDir)) continue;
+    // ⑤ first-writer-wins（含非 marker skill 占名——pi 的 collision 语义以加载集为准，
+    // 后根同名不因 marker 缺席而让位）
+    const realPath = canonicalizePath(skill.filePath);
+    if (seenRealPaths.has(realPath) || seenNames.has(skill.name)) continue;
+    seenRealPaths.add(realPath);
+    seenNames.add(skill.name);
+    if (!hasPlanExecMarker(skill.filePath, log)) continue;
+    found.push({
+      name: skill.name,
+      description: skill.description,
+      // 入口文件路径两种形态统一：标准形态 filePath 即 SKILL.md 路径、散 .md 形态即
+      // 文件本身——接收端（steer 文案）直接 read 该值，不再拼 SKILL.md（散 .md 形态
+      // 拼接会得到不存在的 `<skills根>/SKILL.md` 悬空指引）
+      skillEntryPath: skill.filePath,
+    });
+  }
+  return found;
+}
+
+function detectExecSkillsInternal(options: DetectExecSkillsOptions, log: LogFn): ExecSkill[] {
+  const cwd = resolve(options.cwd);
+  const agentDir = resolve(options.agentDir ?? getAgentDir());
+  const homeDir = resolve(options.homeDir ?? defaultHomeDir());
+
+  const roots = collectSkillRoots(options, cwd, agentDir, homeDir, log);
+
+  const seenNames = new Set<string>();
+  const seenRealPaths = new Set<string>();
+  const found: ExecSkill[] = [];
+  for (const root of roots) {
+    for (const skill of scanSkillRoot(root, seenNames, seenRealPaths, log)) {
+      found.push(skill);
+    }
+  }
+  return found;
+}

package/src/i18n.ts

@@ -0,0 +1,70 @@
+/**
+ * plan 包 i18n 层（u-locale-channel 消费端）：只本地化「给人看的交互面」——complete
+ * 执行方式选择的 FormOverlay 单 choice 问题（question/header/options）与 ctx.ui.notify
+ * 提示。tool result 里的英文是给 LLM 的执行指令，不进词典（agent 会以会话语言转述，
+ * 指令语言 ≠ UI 语言）。
+ *
+ * locale 读取（readUiLocale + mtime/size 缓存 + 降级）下沉在
+ * `@zhushanwen/pi-llm-shared` 单一实现（@data-owner #39 注解随实现持有），本包
+ * re-export；env `TAIJI_AGENT_DATA_DIR` 缺失 / 文件缺失 / JSON 损坏 → 回落 `en-US`
+ * （与 runtime readUiPreferences 的降级口径一致）。
+ */
+import { DEFAULT_UI_LOCALE, readUiLocale, type UiLocale } from "@zhushanwen/pi-llm-shared/ui-locale";
+
+export { DEFAULT_UI_LOCALE, readUiLocale, type UiLocale };
+
+/** 词典 key 集合（exec-choice 交互面 + notify；键缺失回落链见 t()）。 */
+type Dictionary = Record<string, string>;
+
+const EN_US: Dictionary = {
+  "exec.question": "Plan is ready. Choose how to execute:",
+  "exec.header": "Execution method",
+  "exec.viaSkill": "Execute via skill: {name}",
+  "exec.viaSkillDesc": "Load the {name} skill and follow its workflow to execute the plan.",
+  "exec.execute": "Execute",
+  "exec.executeDesc":
+    "Set up goal tracking when available, then execute: delegate independent tasks to subagents, run small or tightly-coupled steps in this session.",
+  "exec.later": "Not now",
+  "exec.laterDesc": "Keep the plan and stay in plan mode. You can execute it later.",
+  "exec.goalFailedNotify": "Goal tracking was not started ({reason}).",
+};
+
+const ZH_CN: Dictionary = {
+  "exec.question": "计划已就绪，请选择执行方式：",
+  "exec.header": "执行方式",
+  "exec.viaSkill": "用技能「{name}」执行",
+  "exec.viaSkillDesc": "加载 {name} 技能并按其工作流执行该计划。",
+  "exec.execute": "执行",
+  "exec.executeDesc": "可用时先建立 goal 跟踪，再自动执行：独立任务派发 subagent，小而紧耦合的步骤在本会话逐步完成。",
+  "exec.later": "暂不执行",
+  "exec.laterDesc": "保留计划并留在计划模式，稍后可再执行。",
+  "exec.goalFailedNotify": "Goal 跟踪未能启动（{reason}）。",
+};
+
+const DICTIONARIES: Record<UiLocale, Dictionary> = {
+  "zh-CN": ZH_CN,
+  "en-US": EN_US,
+};
+
+/** 指定语言的词典 key 集合（测试用于 zh/en 双侧对齐断言）。 */
+export function dictionaryKeys(locale: UiLocale): string[] {
+  return Object.keys(DICTIONARIES[locale]);
+}
+
+/**
+ * 渲染词典模板。回落链：当前 locale → en-US → 键名本身（禁返回空串，scheduler r4 S1
+ * 同款）。占位符缺参时保留 `{name}` 原样。
+ */
+export function t(key: string, params?: Record<string, string | number>, locale?: UiLocale): string {
+  const resolved = locale ?? readUiLocale();
+  const template = DICTIONARIES[resolved][key] ?? DICTIONARIES[DEFAULT_UI_LOCALE][key] ?? key;
+  return interpolate(template, params);
+}
+
+function interpolate(template: string, params?: Record<string, string | number>): string {
+  if (params === undefined) return template;
+  return template.replace(/\{(\w+)\}/g, (match: string, name: string): string => {
+    const value = params[name];
+    return value === undefined ? match : String(value);
+  });
+}

package/src/index.ts

@@ -1,18 +1,49 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import { registerPlanCommand } from "./command.js";
 import { registerPlanEventHandlers } from "./compact.js";
-import { type PlanSessionMap, reconstructPlanState } from "./state.js";
+import {
+  type PlanAbortControllers,
+  type PlanSessionMap,
+  PLAN_CONTEXT_CUSTOM_TYPE,
+  PLAN_MODE_TOOLS,
+  persistPlanState,
+  reconstructPlanState,
+} from "./state.js";
 import { registerPlanTool } from "./tool.js";
 import { updatePlanWidget } from "./widget.js";
 
+const logger = getLogger("pi-plan");
+
+/**
+ * D9 引导文案（约 60 token）：仅在 taiji 宿主注入。plan 模式是只读子集（读代码、产
+ * 文档、不改源码），进入它不是危险操作——agent 可在合适时机**自行进入**（plan-mode-
+ * agent-enter U1 后 enter 是 tool action，无需用户确认；用户随时可经 PlanModeBar 退出）。
+ */
+const PLAN_MODE_SUGGESTION_PROMPT =
+  "\n\n" +
+  "When the user's request involves large-scale refactoring, cross-module changes, or other high-risk modifications, " +
+  "proactively enter plan mode yourself by calling plan(action='enter', requirement='<the task>', skills=[...relevant skills]). " +
+  "Plan mode is read-only for source code: you explore and write plan documents, then the user reviews before implementation. " +
+  "Do not ask for permission to enter — entering plan mode is safe and reversible (the user can exit anytime).";
+
 export default function planExtension(pi: ExtensionAPI) {
   // Per-session state cache — keyed by sessionId
   const sessions: PlanSessionMap = new Map();
+  // 挂起 select 的 per-session AbortController（E10：submit-review 审批 + complete
+  // 执行方式选择两处共用注册表；发挂起 select 前 fresh，settled/重建/关闭即弃）
+  const abortControllers: PlanAbortControllers = new Map();
 
   // Register tool and command
-  registerPlanTool(pi, sessions);
-  registerPlanCommand(pi, sessions);
+  registerPlanTool(pi, sessions, abortControllers);
+  registerPlanCommand(pi, sessions, abortControllers);
 
   // Register compact/tree event handlers
   registerPlanEventHandlers(pi, sessions);
@@ -22,10 +53,79 @@ export default function planExtension(pi: ExtensionAPI) {
     const sessionId = ctx.sessionManager.getSessionId();
     const state = reconstructPlanState(ctx);
     sessions.set(sessionId, state);
+    // session 重建即弃旧 controller：挂起 select 只存在于 tool execute 进行中的
+    // turn，pi 重生后不可能有存活的 select；残留的已 abort controller 禁止复用
+    // （发起新挂起 select 会 fresh 新建，此处删除是防御性清理）
+    abortControllers.delete(sessionId);
     updatePlanWidget(ctx, state);
     // If plan mode was active, re-restrict tools to the plan-mode set (includes bash — file-write constraints come from the injected plan mode prompt)
     if (state.isActive) {
-      pi.setActiveTools(["read", "bash", "grep", "find", "ls", "plan"]);
+      pi.setActiveTools(PLAN_MODE_TOOLS);
+
+      // E3：挂起交互点（审批 select / 执行方式 form）随 pi 进程消亡。本 hook 跑在
+      // pi 懒重生之后（taiji 冷启动不拉 pi 进程——用户重开 session 发首条消息时 pi
+      // 才重生、hook 才跑），此时冷启动扫描已恢复持久态但挂起交互不复存在（上方
+      // delete 已清残留 controller，pi 重生后不可能有存活的挂起）→ 按 reviewState
+      // 三态 steer 恢复（恢复动作全部在 extension 侧，前端不造失败信号链）：
+      // - awaiting：重调 submit-review 重挂审批；
+      // - revising：继续按评论修订并重新提交（P1-1：原实现只覆盖 awaiting，revising
+      //   崩溃后审批条恒显假「修订中」且无任何恢复指引）。
+      // 不覆盖「approve 后执行方式选择窗口中断」：该态（isActive + docs>0 + 无
+      // reviewState）与「探索期 pi 重生」在持久态上不可区分，steer「计划已批准」会
+      // 对正常探索期误报——防误报优先，该窗口中断由用户重发消息自然恢复。
+      if (state.reviewState === "awaiting" || state.reviewState === "revising") {
+        const revising = state.reviewState === "revising";
+        pi.sendMessage(
+          {
+            customType: PLAN_CONTEXT_CUSTOM_TYPE,
+            content: revising
+              ? "[PLAN MODE] A revision round was interrupted (session restarted). The user's revision comments were already injected — continue handling them: rewrite the documents, re-register each revised document via plan(action='register-doc'), then re-submit via plan(action='submit-review')."
+              : "[PLAN MODE] A previous review request was interrupted (session restarted). " +
+                "The registered documents are still waiting for user approval. " +
+                "Call plan(action='submit-review') now to re-hang the review dialog.",
+            display: false,
+          },
+          { deliverAs: "steer", triggerTurn: true },
+        );
+        if (!revising) {
+          // E3 重挂即落 'resubmit' 源标记 + persist（此处原只发 steer 不落盘，renderer
+          // 冷启动扫描的 View 恒无 source、恒渲染通用文案；落盘后才能渲染「会话已重启，
+          // 尚未重新提交」分支）。无条件覆盖既有 source 为有意——「会话已重启」语义
+          // 优先成立（P3-9 登记；旧 entry 存量的其他 source 值一并被覆盖归一）。
+          state.reviewStateSource = "resubmit";
+          persistPlanState(pi, state);
+        }
+      }
+    }
+  });
+
+  // D9：AI 主动建议（轻量引导），仅 taiji 形态注入。
+  // 信号用 TAIJI_AGENT_EXT_LOG 而非 TAIJI_RUNTIME_TOKEN——后者在 SPAWN_ENV 出站
+  // deny list 被强制剥除（C-proc-09），pi 子进程 env 里恒不可见，照抄即引导
+  // 静默失效且诱导实施者动 deny list 造成安全回归；前者由 taiji runtime 对托管
+  // pi 恒注入（rpc-client buildPiOutboundEnv）。独立 pi（信号缺失）不注入——
+  // universal 包语义不变。
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent): BeforeAgentStartEventResult | undefined => {
+    if (process.env.TAIJI_AGENT_EXT_LOG !== "1") return undefined;
+    // Never block the agent loop（system-prompt extension 同款先例）
+    try {
+      return { systemPrompt: event.systemPrompt + PLAN_MODE_SUGGESTION_PROMPT };
+    } catch (error) {
+      const msg = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+      // 注入失败只损失一句引导，不值得中断 agent loop——先走 extension-logger 落盘
+      // （~/.pi/agent/logs/ 文件通道，诊断可见）；logger 自身抛错才降级 stderr
+      // （system-prompt logHookFailure 同款形态：logger 首选、stderr 内层兜底）
+      try {
+        logger.warn("plan: before_agent_start injection failed", { error: msg });
+      } catch (nestedErr) {
+        try {
+          process.stderr.write(`[pi-plan] before_agent_start injection log also failed: ${String(nestedErr)}\n`);
+        } catch (finalErr) {
+          // 完全静默：两层兜底都失败时无处可写
+          void finalErr;
+        }
+      }
+      return undefined;
     }
   });
 
@@ -33,5 +133,6 @@ export default function planExtension(pi: ExtensionAPI) {
   pi.on("session_shutdown", async (_event: unknown, ctx: ExtensionContext) => {
     const sessionId = ctx.sessionManager.getSessionId();
     sessions.delete(sessionId);
+    abortControllers.delete(sessionId);
   });
 }