peaks-cli 1.3.1 → 1.3.3

package/README.md

@@ -8,8 +8,8 @@
 Peaks 是一个**跨 AI IDE 的工作流门禁 CLI + 技能家族**——把项目治理、工作流规划、受控执行、QA 验证、变更追踪组织成可复用的工程流程。CLI 是跨 IDE 稳定的核心（门禁 + JSON 契约 + 不可逆动作），技能 / 钩子 / 配置按各 IDE 的原生格式承载。
 
 > **支持的 IDE**：
-> - ✅ **Claude Code**（当前实现）：11 个 `peaks-*` 技能 + `.claude/settings.json` PreToolUse hook
-> - 🚧 **Trae**（适配中）：用 Trae 的原生配置承载相同的角色 / 状态机 / 门禁
+> - ✅ **Claude Code**（shipped, 当前主用）：11 个 `peaks-*` 技能 + `.claude/settings.json` PreToolUse hook；agent team 在本 IDE 已 dogfood
+> - ⚠️ **Trae**（adapter shipped, real-Trae unverified）：slim `IdeAdapter` 已注册到 slice #1 registry（`hookEvent` / `toolMatcher` / `envVar` 是 1.x 假设，**未在真实 Trae 上验证**）；真实 Trae 集成 dogfood 留到后续切片
 > - 📋 **Codex / Cursor / Qoder / 通义灵码 等**（路线图）
 
 > **产品定位**：你**用技能工作**，CLI 是跨 IDE 的质量保障层。
@@ -115,6 +115,10 @@ peaks-solo strict 模式做 X       # 显式 strict：最严格门禁
 
 **3 个 solo 包装 + 7 个角色技能 + 1 个 solo 编排 = 11 个技能家族。** 日常使用中，1 个（`peaks-solo`）覆盖 ≥90% 的需求。
 
+## Agent team
+
+`peaks` 帮你调度一个 agent team——`peaks-solo` / `peaks-rd` / `peaks-qa` / `peaks-ui` 把 peer sub-agent 派到隔离沙箱里写 PRD / 做架构分析 / 跑测试 / 设计 UI，主 LLM 只看每个 sub-agent 的元数据（路径 + 大小 + 摘要）。
+
 ## 怎么用：技能优先，CLI 是门禁
 
 Peaks 里的 `peaks <cmd>` CLI **不是日常使用的主要入口**。它的存在有三个理由，全都是机器层保障：

package/dist/src/cli/commands/core-artifact-commands.js

@@ -8,7 +8,7 @@ import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
-import { ensureSession, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
+import { getSessionId, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { generateProjectContext } from '../../services/memory/project-context-service.js';
@@ -120,7 +120,7 @@ export function registerCoreAndArtifactCommands(program, io) {
         .description('Set the currently active Peaks skill for session-wide visibility')
         .option('--mode <mode>', 'execution mode')
         .option('--gate <gate>', 'current gate')
-        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (name, options) => {
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((name, options) => {
         const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
         if (options.mode !== undefined && !isSkillPresenceMode(options.mode)) {
             printResult(io, fail('skill.presence:set', 'INVALID_MODE', `Invalid mode: ${options.mode} (expected one of: full-auto, assisted, swarm, strict)`, { name, mode: options.mode }, ['Use a valid mode: full-auto, assisted, swarm, or strict']), options.json);
@@ -128,13 +128,26 @@ export function registerCoreAndArtifactCommands(program, io) {
             return;
         }
         const presence = setSkillPresence(name, options.mode, options.gate, options.project);
-        // Also update session metadata so session dirs self-document
-        const sessionId = await ensureSession(projectRoot);
-        setSessionMeta(projectRoot, sessionId, {
-            skill: name,
-            ...(options.mode ? { mode: options.mode } : {}),
-            ...(options.gate ? { gate: options.gate } : {})
-        });
+        // As of slice 003-2026-06-06-session-layout-canonicalize we do NOT
+        // call `ensureSession` here. The CLI wrapper previously spawned a
+        // new session on every presence call, which made the canonical
+        // session binding drift (the LLM saw the session id change every
+        // turn). The presence now reuses the session bound at
+        // `.peaks/_runtime/session.json` (or the legacy `.peaks/.session.json`
+        // during the back-compat window). If no session is bound, the
+        // presence still writes the active-skill marker — downstream code
+        // can `peaks workspace init` separately to create the session.
+        //
+        // Session metadata is updated when a session is bound (read-only
+        // path: `getSessionId`). We do not auto-spawn a session.
+        const boundSessionId = getSessionId(projectRoot);
+        if (boundSessionId !== null) {
+            setSessionMeta(projectRoot, boundSessionId, {
+                skill: name,
+                ...(options.mode ? { mode: options.mode } : {}),
+                ...(options.gate ? { gate: options.gate } : {})
+            });
+        }
         printResult(io, ok('skill.presence:set', { active: true, ...presence }), options.json);
     });
     addJsonOption(skill
@@ -191,9 +204,34 @@ export function registerCoreAndArtifactCommands(program, io) {
         printResult(io, ok('session.list', { sessions: metas, total: metas.length }), options.json);
     });
     addJsonOption(session
-        .command('info <sessionId>')
-        .description('Show full metadata for a session directory')).action((sessionId, options) => {
+        .command('info [sessionId]')
+        .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive).')
+        .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')).action(async (sessionId, options) => {
         const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+        // Slice 007 — sub-agent session sharing. A sub-agent that does
+        // not know the parent's sid reads it from the binding via
+        // `peaks session info --active`. The call uses the
+        // canonicalize-on-read path so a stored "projectRoot: '.'" and a
+        // caller-passed absolute realpath both resolve to the same
+        // binding. Without this primitive the sub-agent has no way to
+        // discover the parent sid short of scanning the filesystem.
+        if (options.active === true) {
+            // Import lazily to avoid a cycle with workspace-commands.
+            const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+            const activeSid = getSessionIdCanonical(projectRoot);
+            if (activeSid === null) {
+                printResult(io, fail('session.info', 'NO_ACTIVE_BINDING', 'No canonical session binding at .peaks/_runtime/session.json', { projectRoot }, ['Run `peaks workspace init` or `peaks skill presence:set` to anchor a session']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('session.info', { active: true, sessionId: activeSid, source: '.peaks/_runtime/session.json' }), options.json);
+            return;
+        }
+        if (sessionId === undefined) {
+            printResult(io, fail('session.info', 'SESSION_ID_REQUIRED', 'session.info requires a <sessionId> or --active', {}, ['Pass a <sessionId> argument, or use --active to resolve the canonical binding']), options.json);
+            process.exitCode = 1;
+            return;
+        }
         const meta = getSessionMeta(projectRoot, sessionId);
         if (meta === null) {
             printResult(io, fail('session.info', 'SESSION_NOT_FOUND', `Session "${sessionId}" not found or has no metadata`, { sessionId }, ['Use `peaks session list` to see available sessions']), options.json);

package/dist/src/cli/commands/gate-commands.js

@@ -1,7 +1,15 @@
 import { enforceBashCommand, recordGateBypass, GateBypassError } from '../../services/sop/gate-enforce-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-/** Read the PreToolUse hook payload. `PEAKS_HOOK_STDIN` is a test seam; production reads stdin. */
+import { detectIdeFromContext, parseClaudeShapeStdin } from '../../services/ide/hook-translator.js';
+import { formatDecisionResponse } from '../../services/ide/hook-protocol.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+/**
+ * Read the PreToolUse hook payload. `PEAKS_HOOK_STDIN` is a test seam; production
+ * reads stdin. The CLI-side stdin reader is intentionally kept here (not in
+ * `hook-translator.ts`) because it owns the `process.stdin` lifecycle and the
+ * test-seam env var. The translator operates on already-parsed payloads.
+ */
 async function readHookPayload() {
     const override = process.env.PEAKS_HOOK_STDIN;
     if (override !== undefined) {
@@ -20,17 +28,6 @@ async function readHookPayload() {
         process.stdin.on('error', () => resolveStdin(data));
     });
 }
-function emitDeny(io, reason) {
-    // The exact, verified PreToolUse decision shape. permissionDecision:"deny"
-    // blocks the tool call before Claude Code's permission checks (un-bypassable).
-    io.stdout(JSON.stringify({
-        hookSpecificOutput: {
-            hookEventName: 'PreToolUse',
-            permissionDecision: 'deny',
-            permissionDecisionReason: reason
-        }
-    }));
-}
 export function registerGateCommands(program, io) {
     const gate = program.command('gate').description('SOP gate enforcement (PreToolUse hook handler and bypass)');
     addJsonOption(gate
@@ -41,14 +38,25 @@ export function registerGateCommands(program, io) {
         // decide must FAIL-OPEN (allow), never block the user's Claude Code.
         try {
             const raw = await readHookPayload();
-            let command;
-            let toolName;
+            let parsedStdin = null;
             if (raw.trim().length > 0) {
-                const payload = JSON.parse(raw);
-                toolName = payload.tool_name;
-                command = payload.tool_input?.command;
+                try {
+                    parsedStdin = JSON.parse(raw);
+                }
+                catch {
+                    // Malformed JSON — fail-open. Detect + parse on null fall back to the
+                    // default adapter and yield empty tool/command, which short-circuits
+                    // to the "not a guarded surface" early exit below.
+                }
             }
-            if (toolName !== 'Bash' || typeof command !== 'string' || command.trim().length === 0) {
+            const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin });
+            const adapter = getAdapter(ide);
+            // For slice #1 only the Claude adapter is registered, so the parser is
+            // Claude-shaped. Future slices dispatch on `ide` to pick a per-adapter
+            // parser; the parser entry-point (`parseXxxShapeStdin`) is the only
+            // change required.
+            const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
+            if (toolName !== adapter.toolMatcher || typeof command !== 'string' || command.trim().length === 0) {
                 // Not a guarded surface — allow (no output = normal permission flow).
                 if (options.json === true) {
                     printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
@@ -57,7 +65,8 @@ export function registerGateCommands(program, io) {
             }
             const decision = await enforceBashCommand(options.project, command);
             if (decision.decision === 'deny') {
-                emitDeny(io, decision.reason);
+                const { stdout } = formatDecisionResponse(ide, 'deny', decision.reason);
+                io.stdout(stdout);
                 if (options.json === true) {
                     io.stderr(JSON.stringify(ok('gate.enforce', decision)));
                 }

package/dist/src/cli/commands/hook-handle.d.ts

@@ -0,0 +1,17 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * `peaks hook handle` —— peaks 自有 hook 协议的单一入口。
+ *
+ * 该命令是 peaks-cli 拥有的 hook 处理总入口。它:
+ *   1. 读 stdin
+ *   2. auto-detect 来源 IDE(env / stdin shape / cwd)
+ *   3. 归一化到 peaks canonical schema
+ *   4. dispatch 到内部 peaks 逻辑(目前:gate enforce 或 progress start)
+ *   5. 用 IDE 期望的格式发回决策
+ *
+ * Slice #1 阶段:peaks hook handle 与 peaks gate enforce / peaks progress start
+ * 并存(后者内部走 hook-translator)。Slice #2 把 IDE settings 改成调用
+ * peaks hook handle 即可。Slice #3 删除旧命令。
+ */
+export declare function registerHookHandleCommand(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/hook-handle.js

@@ -0,0 +1,111 @@
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { detectIdeFromContext, parseAdapterStdin, parseClaudeShapeStdin, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
+import { buildCanonicalHook, formatDecisionResponse } from '../../services/ide/hook-protocol.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { fail, ok } from '../../shared/result.js';
+/**
+ * Read the hook payload. `PEAKS_HOOK_STDIN` is a test seam (same convention as
+ * `gate-commands.ts`); production reads stdin. The TTY short-circuit means an
+ * interactive shell invocation is treated as an empty payload (allow).
+ */
+async function readStdin() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    if (override !== undefined) {
+        return override;
+    }
+    if (process.stdin.isTTY)
+        return '';
+    return new Promise((resolveStdin) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => resolveStdin(data));
+        process.stdin.on('error', () => resolveStdin(data));
+    });
+}
+/**
+ * `peaks hook handle` —— peaks 自有 hook 协议的单一入口。
+ *
+ * 该命令是 peaks-cli 拥有的 hook 处理总入口。它:
+ *   1. 读 stdin
+ *   2. auto-detect 来源 IDE(env / stdin shape / cwd)
+ *   3. 归一化到 peaks canonical schema
+ *   4. dispatch 到内部 peaks 逻辑(目前:gate enforce 或 progress start)
+ *   5. 用 IDE 期望的格式发回决策
+ *
+ * Slice #1 阶段:peaks hook handle 与 peaks gate enforce / peaks progress start
+ * 并存(后者内部走 hook-translator)。Slice #2 把 IDE settings 改成调用
+ * peaks hook handle 即可。Slice #3 删除旧命令。
+ */
+export function registerHookHandleCommand(program, io) {
+    const hook = program.command('hook').description('Peaks 自有 hook 协议单一入口（slice #1 新增；后续 slice 将逐步替代 gate enforce / progress start）');
+    addJsonOption(hook
+        .command('handle')
+        .description('Read stdin hook payload, auto-detect IDE, dispatch to peaks gate/progress logic, output IDE-formatted decision')
+        .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')).action(async (options) => {
+        try {
+            const raw = await readStdin();
+            let parsed = null;
+            if (raw.trim().length > 0) {
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    // Malformed JSON — treat as empty payload (fail-open)
+                    parsed = null;
+                }
+            }
+            const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin: parsed });
+            const adapter = getAdapter(ide);
+            // Slice #3: per-adapter stdin parser dispatch. The detected IDE
+            // determines which parser runs; unknown IDEs fall back to the Claude
+            // shape (preserves slice #1's "fail-open to Claude" semantics).
+            const { toolName, command } = parseAdapterStdin(ide, parsed);
+            // Also try the Claude parser as a secondary fallback so a Trae user who
+            // accidentally pipes a Claude-shaped payload still gets the right fields.
+            const claudeShape = parseClaudeShapeStdin(parsed);
+            const fallbackToolName = toolName ?? claudeShape.toolName ?? pluckString(parsed, ['toolName']);
+            const fallbackCommand = command ?? claudeShape.command ?? pluckString(parsed, ['toolInput', 'command']);
+            const projectRoot = process.env[adapter.envVar] ?? options.project;
+            const hook = buildCanonicalHook({
+                toolName: fallbackToolName ?? '',
+                toolInput: pluckObject(parsed, ['tool_input']) ?? pluckObject(parsed, ['toolInput']) ?? {},
+                projectRoot,
+                rawIdeFormat: ide,
+                rawPayload: parsed
+            });
+            // Dispatch by toolName. For slice #1, we only handle Bash and Task.
+            // Other tools: allow (no-op; future events will be added here).
+            if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string' && fallbackCommand.trim().length > 0) {
+                // Lazy import to avoid circular: peaks gate enforce logic
+                const { enforceBashCommand } = await import('../../services/sop/gate-enforce-service.js');
+                const decision = await enforceBashCommand(projectRoot, fallbackCommand);
+                if (decision.decision === 'deny') {
+                    const formatted = formatDecisionResponse(ide, 'deny', decision.reason);
+                    io.stdout(formatted.stdout);
+                    if (options.json === true) {
+                        io.stderr(JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: decision.reason })));
+                    }
+                    return;
+                }
+            }
+            else if (hook.toolName === 'Task') {
+                // peaks progress start is a fire-and-forget; do not block hook.handle.
+                // Slice #1: simply acknowledge (no terminal spawn from hook handle itself;
+                // the legacy `peaks progress start` command still does that).
+            }
+            const allow = formatDecisionResponse(ide, 'allow');
+            io.stdout(allow.stdout);
+            if (options.json === true) {
+                printResult(io, ok('hook.handle', { ide, tool: hook.toolName, decision: 'allow' }), true);
+            }
+        }
+        catch (error) {
+            // Fail-open: a bug in hook.handle must not brick Claude Code.
+            io.stderr(`hook handle: internal error, allowing command (${error instanceof Error ? error.message : String(error)})`);
+            if (options.json === true) {
+                printResult(io, fail('hook.handle', 'HOOK_HANDLE_FAILED', error instanceof Error ? error.message : 'unknown', {}), true);
+            }
+        }
+    });
+}

package/dist/src/cli/commands/hooks-commands.js

@@ -1,89 +1,140 @@
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
-import { applyHookInstall, PEAKS_HOOK_ENTRIES, planHookInstall, readHookStatus, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
+import { applyHookInstall, planHookInstall, readHookStatus, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
+import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
 function resolveScope(options) {
     return options.global ? 'global' : 'project';
 }
 function resolveProjectRoot(scope, project) {
     return scope === 'project' ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd()) : undefined;
 }
+/**
+ * Resolve the IDE the install should target. The CLI user can override with
+ * `--ide <id>`. Otherwise we delegate to `detectIdeFromContext` which checks
+ * `process.env[adapter.envVar]` → stdin shape → cwd `.trae`/`.claude` →
+ * fallback `'claude-code'`. Pass `parsedStdin: null` since `peaks hooks
+ * install` is not invoked from inside an IDE hook — there's no stdin payload.
+ */
+function resolveIdeForCommand(options, projectRoot) {
+    if (options.ide !== undefined && options.ide.length > 0) {
+        return options.ide;
+    }
+    return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
+}
+// Slice #3: compute the per-IDE peaks hook entries for the CLI response
+// summary. Replaces the slice #1 PEAKS_HOOK_ENTRIES constant which was
+// hardcoded to claude-code values. Slice 2026-06-06-sub-agent-spawn-bug-
+// and-decouple: the sub-agent progress matcher now reads from
+// `adapter.subAgentToolMatcher` instead of being hardcoded to 'Task', so
+// every IDE self-reports its sub-agent tool name (claude-code: 'Task',
+// future adapters: whatever the adapter declares).
+function listInstalledEntriesForIde(ide) {
+    const adapter = getAdapter(ide);
+    if (ide === 'trae') {
+        return [
+            { matcher: adapter.toolMatcher, sentinel: 'peaks hook handle' },
+            { matcher: adapter.subAgentToolMatcher, sentinel: 'peaks progress start' }
+        ];
+    }
+    // Default (claude-code) and any future registered adapters.
+    return [
+        { matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' },
+        { matcher: adapter.subAgentToolMatcher, sentinel: 'peaks progress start' }
+    ];
+}
 export function registerHooksCommands(program, io) {
     const hooks = program
         .command('hooks')
-        .description('Manage the Peaks PreToolUse hooks in .claude/settings.json: (1) Bash→peaks gate enforce (SOP gate), (2) Task→peaks progress start (auto-spawn sub-agent progress terminal). Both are installed / removed together.');
+        .description("Manage the Peaks-managed hook entries in the adapter's settings.json (default: .claude/settings.json for Claude, .trae/settings.json for Trae): (1) gate-enforce hook (SOP gate), (2) progress-start hook (auto-spawn sub-agent progress terminal). Both are installed / removed together. The IDE is auto-detected from env / cwd; override with --ide <id>.");
     addJsonOption(hooks
         .command('install')
-        .description(`Install all peaks-managed PreToolUse hooks (${PEAKS_HOOK_ENTRIES.map((e) => e.matcher).join(', ')}) into the target .claude/settings.json. Idempotent: re-runs are no-ops. Project scope by default.`)
+        .description(`Install all peaks-managed hook entries into the adapter's settings.json. Idempotent: re-runs are no-ops. Project scope by default.`)
         .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', "target adapter id (claude-code | trae); default: auto-detect from env/cwd")
         .option('--dry-run', 'show what would change without writing')).action((options) => {
         const scope = resolveScope(options);
         const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
         try {
             if (options.dryRun === true) {
-                const plan = planHookInstall(scope, projectRoot);
+                const plan = planHookInstall(scope, projectRoot, { ide });
+                const dryRunEntries = listInstalledEntriesForIde(ide);
                 printResult(io, ok('hooks.install', {
                     ...plan,
+                    ide,
                     applied: false,
                     dryRun: true,
-                    entries: PEAKS_HOOK_ENTRIES.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
-                }, [], [`would install ${PEAKS_HOOK_ENTRIES.length} peaks-managed hook entries`]), options.json);
+                    entries: dryRunEntries
+                }, [], [`would install ${dryRunEntries.length} peaks-managed hook entries`]), options.json);
                 return;
             }
-            const result = applyHookInstall(scope, projectRoot);
+            const result = applyHookInstall(scope, projectRoot, { ide });
+            // Slice #3: build the per-IDE entries summary from the actual installed
+            // entries, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
+            // claude-code default). The user's JSON envelope must reflect the IDE
+            // they targeted.
+            const installedEntries = listInstalledEntriesForIde(ide);
             const nextActions = result.applied
                 ? [
-                    'Restart Claude Code (or reload the window) so the PreToolUse hooks take effect',
-                    `Installed: ${PEAKS_HOOK_ENTRIES.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`
+                    'Restart the IDE (or reload the workspace) so the hook entries take effect',
+                    `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`
                 ]
                 : [];
             printResult(io, ok('hooks.install', {
                 ...result,
+                ide,
                 dryRun: false,
-                entries: PEAKS_HOOK_ENTRIES.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+                entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
             }, [], nextActions), options.json);
         }
         catch (error) {
             const message = getErrorMessage(error);
-            printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, applied: false }, [message]), options.json);
+            printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, ide, applied: false }, [message]), options.json);
             process.exitCode = 1;
         }
     });
     addJsonOption(hooks
         .command('uninstall')
-        .description('Remove all peaks-managed PreToolUse hooks (gate-enforce + progress-start) from the target .claude/settings.json. Third-party hooks are preserved.')
+        .description("Remove all peaks-managed hook entries (gate-enforce + progress-start) from the target settings.json. Third-party hooks are preserved.")
         .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
-        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((options) => {
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
         const scope = resolveScope(options);
         const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
         try {
-            const result = removeHookInstall(scope, projectRoot);
-            printResult(io, ok('hooks.uninstall', result), options.json);
+            const result = removeHookInstall(scope, projectRoot, { ide });
+            printResult(io, ok('hooks.uninstall', { ...result, ide }), options.json);
         }
         catch (error) {
             const message = getErrorMessage(error);
-            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, removed: false }, [message]), options.json);
+            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [message]), options.json);
             process.exitCode = 1;
         }
     });
     addJsonOption(hooks
         .command('status')
-        .description('Report which peaks-managed PreToolUse hooks are installed (gate-enforce + progress-start).')
+        .description('Report which peaks-managed hook entries are installed.')
         .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
-        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((options) => {
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
         const scope = resolveScope(options);
         const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
         try {
-            const status = readHookStatus(scope, projectRoot);
+            const status = readHookStatus(scope, projectRoot, { ide });
             printResult(io, ok('hooks.status', {
                 ...status,
-                entries: PEAKS_HOOK_ENTRIES.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+                ide,
+                entries: listInstalledEntriesForIde(ide)
             }), options.json);
         }
         catch (error) {
             const message = getErrorMessage(error);
-            printResult(io, fail('hooks.status', 'HOOKS_STATUS_FAILED', message, { scope }, [message]), options.json);
+            printResult(io, fail('hooks.status', 'HOOKS_STATUS_FAILED', message, { scope, ide }, [message]), options.json);
             process.exitCode = 1;
         }
     });

package/dist/src/cli/commands/progress-commands.js

@@ -15,7 +15,7 @@ export function registerProgressCommands(program, io) {
     // peaks progress step
     // LLM-side: called by the LLM on phase transitions. Near-zero
     // token cost — one Bash call per phase change. Writes
-    // `.peaks/<sid>/system/subagent-progress.json`. No auto-spawn
+    // `.peaks/_sub_agents/<sid>/subagent-progress.json`. No auto-spawn
     // here; the LLM invokes `peaks progress start` separately when
     // the user-visible window needs to open.
     // ─────────────────────────────────────────────────────────────────
@@ -193,7 +193,14 @@ export function registerProgressCommands(program, io) {
             // asked for visible "this is peaks-cli" branding so the
             // spawned terminal is identifiable at a glance; the title
             // also makes `peaks progress close` self-documenting.
-            const windowTitle = `peaks-cli: sub-agent progress${reasonSuffix}`;
+            //
+            // Em-dash (U+2014) instead of a colon. On Windows, cmd /c's
+            // script parser interprets a `:` even inside quotes as a
+            // drive-letter prefix, so `peaks-cli: sub-agent progress`
+            // triggers the "Windows 找不到文件 'sub-agent'" dialog. The
+            // em-dash is a no-op for cmd / c, bash, and AppleScript
+            // string parsing — the visible branding is preserved.
+            const windowTitle = `peaks-cli — sub-agent progress${reasonSuffix}`;
             const watchCommand = `${peaksBin} progress watch --project "${canonical}"`;
             // Build the platform-specific spawn command + args. This
             // is extracted to ./progress-start-spawn.ts so the three

package/dist/src/cli/commands/progress-start-spawn.js

@@ -45,9 +45,25 @@ function buildPosixTitleCmd(windowTitle) {
     const escaped = windowTitle.replaceAll("'", "'\\''");
     return `printf '\\033]0;${escaped}\\007'`;
 }
-/** cmd.exe `title` builtin call. Quoting is intentionally bare. */
+/**
+ * cmd.exe `title` builtin call. Quoting is REQUIRED: cmd /k parses the
+ * subsequent tokens as a command line, and a `:` in the unquoted title (the
+ * canonical peaks windowTitle starts with `peaks-cli:`) gets mis-read as a
+ * drive-letter prefix, triggering Windows' "找不到文件 'sub-agent'" dialog.
+ *
+ * The double-quote wrap makes the whole title one parameter to `title`.
+ * Defensive guard: reject embedded `"`, `\n`, or `\r` (the `cmd /k` parser
+ * will not survive a literal newline or an un-escaped quote in the title).
+ * Callers (progress-commands.ts:267) compose the title from CLI args; if
+ * the user passed a `--reason` containing one of these characters, the
+ * spawn attempt is abandoned with a tagged result so the CLI can surface
+ * a clear error envelope.
+ */
 function buildWinTitleCmd(windowTitle) {
-    return `title ${windowTitle}`;
+    if (windowTitle.includes('"') || windowTitle.includes('\n') || windowTitle.includes('\r')) {
+        return { ok: false, unsupported: true };
+    }
+    return { ok: true, cmd: `title "${windowTitle}"` };
 }
 /** Shared helper: the shell command that runs the watch. */
 function buildWatchCommand(peaksBin, projectRoot) {
@@ -103,11 +119,21 @@ export function buildStartSpawn(options) {
         return { ok: true, command: terminal, args: ['-e', bannerShell] };
     }
     if (currentPlatform === 'win32') {
-        const bannerCmd = `${winTitleCmd} && echo peaks-cli --- sub-agent progress && ${watchCommand}`;
+        if (!winTitleCmd.ok) {
+            return { ok: false, unsupported: true };
+        }
+        const bannerCmd = `${winTitleCmd.cmd} && echo peaks-cli --- sub-agent progress && ${watchCommand}`;
         return {
             ok: true,
             command: 'cmd',
-            args: ['/c', 'start', `"${windowTitle}"`, 'cmd', '/k', bannerCmd]
+            // Wrap bannerCmd in an EXTRA pair of outer quotes so the OUTER
+            // `cmd /c`'s script parser sees the banner as a single arg
+            // (not a `&&`-chained script). The INNER `cmd /k` in the new
+            // window strips the extra outer quotes and parses the banner
+            // as a normal script. windowTitle is left unquoted: Node's
+            // spawn applies the correct Windows escaping naturally,
+            // which is more robust than pre-quoting.
+            args: ['/c', 'start', windowTitle, 'cmd', '/k', `"${bannerCmd}"`]
         };
     }
     return { ok: false, unsupported: true };

package/dist/src/cli/commands/slice-commands.js

@@ -16,14 +16,16 @@ export function registerSliceCommands(program, io) {
         .option('--project <path>', 'target project root', '.')
         .option('--rid <rid>', 'request id; defaults to the active current-change binding')
         .option('--refresh-fanout', 're-run the 3-way review fan-out (peaks-rd) even if the review files already exist', false)
-        .option('--skip-tests', 'skip the unit-test stage (e.g. docs-only slices)', false)).action(async (options) => {
+        .option('--skip-tests', 'skip the unit-test stage (e.g. docs-only slices)', false)
+        .option('--allow-pre-existing-failures', 'opt-in: if the unit-test stage fails, report it as `skipped` with a reason naming the failure count (useful when the repo has unrelated pre-existing failures; the long-term fix is to .skip or coverage.exclude those tests)', false)).action(async (options) => {
         try {
             const projectRoot = resolveCanonicalProjectRoot(options.project);
             const result = await sliceCheck({
                 projectRoot,
                 ...(options.rid ? { rid: options.rid } : {}),
                 refreshFanout: options.refreshFanout === true,
-                skipTests: options.skipTests === true
+                skipTests: options.skipTests === true,
+                allowPreExistingFailures: options.allowPreExistingFailures === true
             });
             const warnings = [];
             if (result.stages.some((s) => s.status === 'fail')) {