peaks-cli 1.3.1 → 1.3.3

package/dist/src/services/doctor/doctor-service.d.ts

@@ -18,6 +18,32 @@ export type CodegraphCapabilityProbe = {
     binaryPath: string;
     binaryExists: boolean;
 };
+export type DistVersionComparison = {
+    dist: string | null;
+    source: string;
+    match: boolean;
+    distReadable: boolean;
+};
+export type DistVersionProbe = () => DistVersionComparison;
+export type WorkspaceLayoutInspection = {
+    topLevelSessionDirs: string[];
+    legacyDotfiles: string[];
+    /**
+     * Slice 007 — per-change-id top-level dirs (e.g. `.peaks/001-2026-06-06-.../`).
+     * The pre-F3 canonical layout put reviewable artifacts under a
+     * per-change-id top-level dir; the post-F3 canonical layout
+     * consolidates them under `.peaks/_runtime/<sid>/<role>/`. Any
+     * leftover per-change-id top-level dir is a regression to flag.
+     * Slice 008's migration will consolidate these; until then, the
+     * check reports them as `ok: false`.
+     *
+     * Optional in the type for back-compat with test probes that
+     * pre-date the slice 007 broadening; the check itself falls back
+     * to an empty array when the field is missing.
+     */
+    perChangeIdDirs?: string[];
+};
+export type WorkspaceLayoutProbe = () => WorkspaceLayoutInspection;
 export type DoctorOptions = {
     schemasBaseDir?: string;
     skillsBaseDir?: string;
@@ -29,6 +55,10 @@ export type DoctorOptions = {
     workspaceInitializedProbe?: () => boolean;
     /** Platform string (defaults to process.platform); injectable for tests. */
     platform?: NodeJS.Platform;
+    /** Injected for the build:dist-version-matches-source check (defaults to compareDistVersion on disk). */
+    distVersionProbe?: DistVersionProbe;
+    /** Injected for the build:workspace-layout-canonical check (defaults to inspectWorkspaceLayout on disk). */
+    workspaceLayoutProbe?: WorkspaceLayoutProbe;
 };
 /**
  * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
@@ -37,4 +67,36 @@ export type DoctorOptions = {
  * `.peaks/_runtime/session.json` OR the legacy `.peaks/.session.json` exists.
  */
 export declare function isWorkspaceInitializedAt(projectRoot: string): boolean;
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against the
+ * source-of-truth `package.json#version`. Default readers fail-soft to `null`
+ * on missing/unreadable/malformed input. Exported so tests can drive the
+ * filesystem reads without monkey-patching `process.cwd()`.
+ */
+export declare function compareDistVersion(opts: {
+    projectRoot: string;
+    distVersionReader?: (root: string) => string | null;
+    sourceVersionReader?: (root: string) => string | null;
+}): DistVersionComparison;
+/**
+ * Pure helper that inspects the on-disk workspace layout for
+ * post-F3-canonical violations. The post-F3 canonical layout puts
+ * session dirs under `.peaks/_runtime/<sid>/` and the runtime
+ * binding at `.peaks/_runtime/session.json`; the legacy paths
+ * (top-level `<YYYY-MM-DD-session-<hex>>/` dirs and the legacy
+ * top-level `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * dotfiles) must be absent. This helper is exported so tests can
+ * drive the filesystem walk without monkey-patching `process.cwd()`
+ * or `findProjectRoot`.
+ *
+ * Both scanners fail-soft (return `[]` on read errors) so a flaky
+ * filesystem read on a non-fatal probe path never escalates into a
+ * doctor failure.
+ */
+export declare function inspectWorkspaceLayout(opts: {
+    projectRoot: string;
+    topLevelScanner?: (root: string) => string[];
+    dotfileScanner?: (root: string) => string[];
+    perChangeIdScanner?: (root: string) => string[];
+}): WorkspaceLayoutInspection;
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

package/dist/src/services/doctor/doctor-service.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { existsSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { readText } from '../../shared/fs.js';
@@ -68,6 +68,192 @@ export function isWorkspaceInitializedAt(projectRoot) {
     return (existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json')) ||
         existsSync(join(projectRoot, '.peaks', '.session.json')));
 }
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against the
+ * source-of-truth `package.json#version`. Default readers fail-soft to `null`
+ * on missing/unreadable/malformed input. Exported so tests can drive the
+ * filesystem reads without monkey-patching `process.cwd()`.
+ */
+export function compareDistVersion(opts) {
+    const distReader = opts.distVersionReader ?? defaultDistVersionReader;
+    const sourceReader = opts.sourceVersionReader ?? defaultSourceVersionReader;
+    const dist = safeRead(() => distReader(opts.projectRoot));
+    const source = safeRead(() => sourceReader(opts.projectRoot)) ?? 'unknown';
+    const distReadable = dist !== null;
+    return {
+        dist,
+        source,
+        match: distReadable && dist === source,
+        distReadable
+    };
+}
+function safeRead(reader) {
+    try {
+        return reader();
+    }
+    catch {
+        return null;
+    }
+}
+function defaultDistVersionReader(projectRoot) {
+    // Synchronous read is fine: the dist version.js is small and on the
+    // local build pipeline's hot path. readFileSync + regex is cheaper
+    // than pulling in fs/promises for a single short file.
+    const distPath = join(projectRoot, 'dist', 'src', 'shared', 'version.js');
+    if (!existsSync(distPath)) {
+        return null;
+    }
+    const body = readFileSync(distPath, 'utf8');
+    const match = /export\s+const\s+CLI_VERSION\s*=\s*["']([^"']+)["']/.exec(body);
+    return match?.[1] ?? null;
+}
+function defaultSourceVersionReader(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return null;
+    }
+    const body = readFileSync(pkgPath, 'utf8');
+    const parsed = JSON.parse(body);
+    return typeof parsed.version === 'string' ? parsed.version : null;
+}
+function defaultDistVersionProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null) {
+        return { dist: null, source: 'unknown', match: false, distReadable: false };
+    }
+    return compareDistVersion({ projectRoot });
+}
+/**
+ * Pure helper that inspects the on-disk workspace layout for
+ * post-F3-canonical violations. The post-F3 canonical layout puts
+ * session dirs under `.peaks/_runtime/<sid>/` and the runtime
+ * binding at `.peaks/_runtime/session.json`; the legacy paths
+ * (top-level `<YYYY-MM-DD-session-<hex>>/` dirs and the legacy
+ * top-level `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * dotfiles) must be absent. This helper is exported so tests can
+ * drive the filesystem walk without monkey-patching `process.cwd()`
+ * or `findProjectRoot`.
+ *
+ * Both scanners fail-soft (return `[]` on read errors) so a flaky
+ * filesystem read on a non-fatal probe path never escalates into a
+ * doctor failure.
+ */
+export function inspectWorkspaceLayout(opts) {
+    const topLevel = opts.topLevelScanner ?? defaultTopLevelSessionDirScanner;
+    const dotfiles = opts.dotfileScanner ?? defaultLegacyDotfileScanner;
+    const perChangeId = opts.perChangeIdScanner ?? defaultPerChangeIdDirScanner;
+    return {
+        topLevelSessionDirs: safeList(() => topLevel(opts.projectRoot)),
+        legacyDotfiles: safeList(() => dotfiles(opts.projectRoot)),
+        perChangeIdDirs: safeList(() => perChangeId(opts.projectRoot))
+    };
+}
+function safeList(reader) {
+    try {
+        const out = reader();
+        return Array.isArray(out) ? out : [];
+    }
+    catch {
+        return [];
+    }
+}
+const SESSION_DIR_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
+function defaultTopLevelSessionDirScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return [];
+    }
+    const offenders = [];
+    for (const name of names) {
+        if (!SESSION_DIR_PATTERN.test(name))
+            continue;
+        const full = join(peaksRoot, name);
+        try {
+            const stat = existsSync(full) ? lstatSync(full) : null;
+            if (stat === null)
+                continue;
+            // Directories only — the regex should never match a dotfile or
+            // regular file, but be defensive against weird filesystem state
+            // (e.g. someone manually created a file whose name happens to
+            // match the session-id pattern).
+            if (stat.isDirectory()) {
+                offenders.push(join('.peaks', name) + '/');
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return offenders;
+}
+const LEGACY_DOTFILES = ['.session.json', '.active-skill.json'];
+function defaultLegacyDotfileScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const offenders = [];
+    for (const name of LEGACY_DOTFILES) {
+        if (existsSync(join(peaksRoot, name))) {
+            offenders.push(join('.peaks', name));
+        }
+    }
+    return offenders;
+}
+function defaultWorkspaceLayoutProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null) {
+        return { topLevelSessionDirs: [], legacyDotfiles: [], perChangeIdDirs: [] };
+    }
+    return inspectWorkspaceLayout({ projectRoot });
+}
+// Slice 007 — per-change-id top-level dir pattern. Matches the
+// F3-canonical (pre-canonicalization) layout the 5 already-shipped
+// slices left behind, e.g. `.peaks/001-2026-06-06-doctor-dist-version-check/`.
+// The pattern is intentionally narrow so it does NOT match the
+// post-F3 system dirs (`_runtime/`, `_dogfood/`, `retrospective/`,
+// `issues/`, `memory/`, `perf-baseline/`, `project-scan/`, `sops/`,
+// `0NN-session-...`, `YYYY-MM-DD-session-...`).
+const PER_CHANGE_ID_PATTERN = /^\d{3}-\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+function defaultPerChangeIdDirScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return [];
+    }
+    const offenders = [];
+    for (const name of names) {
+        if (!PER_CHANGE_ID_PATTERN.test(name))
+            continue;
+        const full = join(peaksRoot, name);
+        try {
+            const stat = existsSync(full) ? lstatSync(full) : null;
+            if (stat === null)
+                continue;
+            // Directories only — the regex should never match a dotfile
+            // or regular file, but be defensive against weird filesystem
+            // state (e.g. someone manually created a file whose name
+            // happens to match the per-change-id pattern).
+            if (stat.isDirectory()) {
+                offenders.push(join('.peaks', name) + '/');
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return offenders;
+}
 const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+sync[^\n]*--apply/,
     /peaks\s+memory\s+extract[^\n]*--apply/,
@@ -344,6 +530,95 @@ export async function runDoctor(options = {}) {
             message: `@colbymchenry/codegraph not resolvable: ${getErrorMessage(error)}`
         });
     }
+    // Build-hygiene check: the published `dist/` ships a different CLI_VERSION
+    // than the source-of-truth `src/shared/version.ts` / `package.json#version`
+    // whenever the user runs `npx peaks` or `node bin/peaks.js` after `pnpm
+    // install` but before `pnpm build`. This is the silent-stale-CLI failure
+    // mode reported in `.peaks/2026-06-05-session-fecddb/txt/dogfood-2026-06-04-05.md`
+    // (F1). A missing dist/ is treated as informational (fresh clone, not broken)
+    // so the check does not flip the summary to red on a clean checkout.
+    const distProbe = options.distVersionProbe ?? defaultDistVersionProbe;
+    try {
+        const result = distProbe();
+        if (!result.distReadable) {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: true,
+                message: `dist/ is not present; run \`pnpm build\` to populate dist/src/shared/version.js (source version ${result.source})`
+            });
+        }
+        else if (result.match) {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: true,
+                message: `dist/src/shared/version.js ships CLI_VERSION ${result.dist} matching source ${result.source}`
+            });
+        }
+        else {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: false,
+                message: `dist/src/shared/version.js ships CLI_VERSION ${result.dist} but source ${result.source} is in src/shared/version.ts; run \`pnpm build\` to refresh dist/`
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'build:dist-version-matches-source',
+            ok: false,
+            message: `dist version check failed: ${getErrorMessage(error)}`
+        });
+    }
+    // Build-hygiene check: a non-canonical post-F3 workspace layout is
+    // the silent-regression failure mode that slice 003 explicitly chose
+    // to allow (the current session binding was kept at top-level as a
+    // safety measure). This check surfaces any leftover top-level
+    // session dirs, the legacy runtime dotfiles (`.peaks/.session.json`,
+    // `.peaks/.active-skill.json`), OR per-change-id top-level dirs
+    // (`.peaks/NNN-YYYY-MM-DD-<slug>/`) so a future contributor who
+    // manually recreates one of them is warned. The check is read-only;
+    // the fix path is `peaks workspace migrate --to-runtime --project
+    // <repo> --apply`.
+    //
+    // Slice 007 broadened this check to flag per-change-id top-level
+    // dirs (the 5 already-shipped slices left them behind). Until
+    // slice 008's migration consolidates them, the check reports
+    // `ok: false` for any repo that still has the legacy per-change-id
+    // layout.
+    const layoutProbe = options.workspaceLayoutProbe ?? defaultWorkspaceLayoutProbe;
+    try {
+        const layout = layoutProbe();
+        // Back-compat: probes injected by older tests (pre-slice-007)
+        // return a 2-field shape (no perChangeIdDirs). Treat missing
+        // field as empty.
+        const perChangeIdDirs = layout.perChangeIdDirs ?? [];
+        if (layout.topLevelSessionDirs.length === 0 && layout.legacyDotfiles.length === 0 && perChangeIdDirs.length === 0) {
+            checks.push({
+                id: 'build:workspace-layout-canonical',
+                ok: true,
+                message: 'Workspace layout is canonical: no top-level session dirs, no legacy runtime dotfiles, no per-change-id top-level dirs'
+            });
+        }
+        else {
+            const offenders = [
+                ...layout.topLevelSessionDirs.map((p) => `top-level session dir: ${p}`),
+                ...layout.legacyDotfiles.map((p) => `legacy dotfile: ${p}`),
+                ...perChangeIdDirs.map((p) => `per-change-id top-level dir: ${p}`)
+            ];
+            checks.push({
+                id: 'build:workspace-layout-canonical',
+                ok: false,
+                message: `Workspace layout is not canonical. Offenders: ${offenders.join('; ')}. Run \`peaks workspace migrate --to-runtime --project <repo> --apply\` to consolidate.`
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'build:workspace-layout-canonical',
+            ok: false,
+            message: `Workspace layout check failed: ${getErrorMessage(error)}`
+        });
+    }
     try {
         const schemaText = await readText(join(schemaRoot, 'doctor-report.schema.json'));
         const schema = JSON.parse(schemaText);

package/dist/src/services/ide/adapters/claude-code-adapter.d.ts

@@ -0,0 +1,18 @@
+import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Claude Code adapter —— peaks-cli 的"起源 IDE"。
+ *
+ * 该 adapter 从原 `src/services/skills/hooks-settings-service.ts` 提取,保持
+ * 字节级兼容:用户在 Claude Code 环境下跑 `peaks hooks install` 产出的
+ * `.claude/settings.json` 与 refactor 前逐字节相同。
+ *
+ * 字段解释(见 PRD AC-1):
+ *   - dirName = '.claude'           : Claude Code 项目根下的 settings 目录
+ *   - settingsFileName = 'settings.json'
+ *   - envVar = 'CLAUDE_PROJECT_DIR' : Claude Code 注入的 env 变量,用于 ${...} 占位
+ *   - hookEvent = 'PreToolUse'      : Claude Code hook 数组 key
+ *   - toolMatcher = 'Bash' | 'Task' : PreToolUse 数组元素的 matcher 字段
+ *
+ * 不可消除的 per-IDE 字段(见 tech-doc.md §1.3)。
+ */
+export declare const CLAUDE_CODE_ADAPTER: IdeAdapter;

package/dist/src/services/ide/adapters/claude-code-adapter.js

@@ -0,0 +1,53 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { claudeCodeSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
+/**
+ * Claude Code adapter —— peaks-cli 的"起源 IDE"。
+ *
+ * 该 adapter 从原 `src/services/skills/hooks-settings-service.ts` 提取,保持
+ * 字节级兼容:用户在 Claude Code 环境下跑 `peaks hooks install` 产出的
+ * `.claude/settings.json` 与 refactor 前逐字节相同。
+ *
+ * 字段解释(见 PRD AC-1):
+ *   - dirName = '.claude'           : Claude Code 项目根下的 settings 目录
+ *   - settingsFileName = 'settings.json'
+ *   - envVar = 'CLAUDE_PROJECT_DIR' : Claude Code 注入的 env 变量,用于 ${...} 占位
+ *   - hookEvent = 'PreToolUse'      : Claude Code hook 数组 key
+ *   - toolMatcher = 'Bash' | 'Task' : PreToolUse 数组元素的 matcher 字段
+ *
+ * 不可消除的 per-IDE 字段(见 tech-doc.md §1.3)。
+ */
+export const CLAUDE_CODE_ADAPTER = {
+    id: 'claude-code',
+    displayName: 'Claude Code',
+    settings: {
+        dirName: '.claude',
+        settingsFileName: 'settings.json',
+        resolveSettingsFile: (scope, projectRoot) => {
+            const root = scope === 'global' ? homedir() : resolve(projectRoot ?? homedir());
+            return join(root, '.claude', 'settings.json');
+        },
+        supportsScope: () => true,
+    },
+    envVar: 'CLAUDE_PROJECT_DIR',
+    hookEvent: 'PreToolUse',
+    toolMatcher: 'Bash',
+    subAgentToolMatcher: 'Task',
+    // Slice #009: Claude Code uses the `Task` tool for sub-agent dispatch.
+    // The CLI calls `claudeCodeSubAgentDispatcher.buildToolCall` to construct
+    // the exact args shape the `Task` tool expects.
+    subAgentDispatcher: claudeCodeSubAgentDispatcher,
+    // Slice #010 G9: Claude Code supports the PreToolUse hook event in a
+    // form that can wrap `peaks sub-agent-dispatch-guard` as a sub-command.
+    // Opt in to the G9 hook install.
+    promptSizeAware: true,
+    installHints: [
+        'Restart Claude Code (or reload the window) so the PreToolUse hooks take effect.'
+    ],
+    capabilities: {
+        gateEnforce: true,
+        progressStart: true,
+        statusline: true,
+        mcpInstall: true,
+    },
+};

package/dist/src/services/ide/adapters/trae-adapter.d.ts

@@ -0,0 +1,34 @@
+import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Trae IDE adapter —— peaks-cli 的第二个内置 IDE 适配器。
+ *
+ * 不可消除的 per-IDE 字段(slice #1 锁定):
+ *   - settings.dirName = '.trae'            : Trae 项目根下的配置目录
+ *   - settings.settingsFileName = 'settings.json'  (UNVERIFIED at slice time: Trae 实际叫什么待 Trae 1.x 文档确认,先按 Claude 风格)
+ *   - envVar = 'TRAE_PROJECT_DIR'    : Trae 注入的 env 变量(用于 ${...} 占位)
+ *   - hookEvent = 'beforeToolCall'  : UNVERIFIED — Trae 的 hook 数组 key(待 Trae 文档确认,先假设与 Cursor 同名)
+ *   - toolMatcher = 'terminal'      : UNVERIFIED — Trae 的 bash 工具 matcher(待 Trae 文档确认)
+ *
+ * Slice #1 的 slim `IdeAdapter` shape 在 slice #1 RD 中被锁为"填表"模式。
+ * 本文件是 slice #2 第一个真实客户,验证 slice #1 抽出的形状真的可以
+ * 简单复制粘贴就接入新 IDE。
+ *
+ * 与 slice #1 claude-code-adapter.ts 的区别(故意):
+ *   - Trae 的 hookEvent 名是 `beforeToolCall` 而不是 `PreToolUse`(假设)
+ *   - Trae 的 toolMatcher 是 `terminal` 而不是 `Bash`(假设)
+ *   - Trae 的 settings 路径是 `.trae/settings.json`(同 Claude 风格,只是目录名不同)
+ *   - Trae 的 envVar 是 `TRAE_PROJECT_DIR`
+ *   - installHints 提示用户"重启 Trae"(同 Claude 风格)
+ *
+ * 等 Trae 真实文档/真实用户的 dogfood 之后,可能需要把 hookEvent /
+ * toolMatcher 替换为 Trae 实际值。slice #2 的 tech-doc 里要明确"此 adapter
+ * 是基于 1.x 假设,Trae 真实集成需要在 Trae 上 dogfood 验证"。
+ *
+ * Slice #3 refactor: the `peaks hooks install` command now dispatches on the
+ * IDE adapter (auto-detect from env / cwd, override with `--ide trae`). When
+ * a Trae install is run, the resulting `<root>/.trae/settings.json` will use
+ * the `beforeToolCall` event key and the `terminal` matcher from this adapter.
+ * Until a real Trae 1.x install dogfoods the byte-level output, treat the
+ * UNVERIFIED fields as best-effort defaults.
+ */
+export declare const TRAE_ADAPTER: IdeAdapter;

package/dist/src/services/ide/adapters/trae-adapter.js

@@ -0,0 +1,70 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { traeSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
+/**
+ * Trae IDE adapter —— peaks-cli 的第二个内置 IDE 适配器。
+ *
+ * 不可消除的 per-IDE 字段(slice #1 锁定):
+ *   - settings.dirName = '.trae'            : Trae 项目根下的配置目录
+ *   - settings.settingsFileName = 'settings.json'  (UNVERIFIED at slice time: Trae 实际叫什么待 Trae 1.x 文档确认,先按 Claude 风格)
+ *   - envVar = 'TRAE_PROJECT_DIR'    : Trae 注入的 env 变量(用于 ${...} 占位)
+ *   - hookEvent = 'beforeToolCall'  : UNVERIFIED — Trae 的 hook 数组 key(待 Trae 文档确认,先假设与 Cursor 同名)
+ *   - toolMatcher = 'terminal'      : UNVERIFIED — Trae 的 bash 工具 matcher(待 Trae 文档确认)
+ *
+ * Slice #1 的 slim `IdeAdapter` shape 在 slice #1 RD 中被锁为"填表"模式。
+ * 本文件是 slice #2 第一个真实客户,验证 slice #1 抽出的形状真的可以
+ * 简单复制粘贴就接入新 IDE。
+ *
+ * 与 slice #1 claude-code-adapter.ts 的区别(故意):
+ *   - Trae 的 hookEvent 名是 `beforeToolCall` 而不是 `PreToolUse`(假设)
+ *   - Trae 的 toolMatcher 是 `terminal` 而不是 `Bash`(假设)
+ *   - Trae 的 settings 路径是 `.trae/settings.json`(同 Claude 风格,只是目录名不同)
+ *   - Trae 的 envVar 是 `TRAE_PROJECT_DIR`
+ *   - installHints 提示用户"重启 Trae"(同 Claude 风格)
+ *
+ * 等 Trae 真实文档/真实用户的 dogfood 之后,可能需要把 hookEvent /
+ * toolMatcher 替换为 Trae 实际值。slice #2 的 tech-doc 里要明确"此 adapter
+ * 是基于 1.x 假设,Trae 真实集成需要在 Trae 上 dogfood 验证"。
+ *
+ * Slice #3 refactor: the `peaks hooks install` command now dispatches on the
+ * IDE adapter (auto-detect from env / cwd, override with `--ide trae`). When
+ * a Trae install is run, the resulting `<root>/.trae/settings.json` will use
+ * the `beforeToolCall` event key and the `terminal` matcher from this adapter.
+ * Until a real Trae 1.x install dogfoods the byte-level output, treat the
+ * UNVERIFIED fields as best-effort defaults.
+ */
+export const TRAE_ADAPTER = {
+    id: 'trae',
+    displayName: 'Trae',
+    settings: {
+        dirName: '.trae',
+        settingsFileName: 'settings.json', // UNVERIFIED — see slice #2 closeout code-review M-1
+        resolveSettingsFile: (scope, projectRoot) => {
+            const root = scope === 'global' ? homedir() : resolve(projectRoot ?? homedir());
+            return join(root, '.trae', 'settings.json');
+        },
+        supportsScope: (scope) => scope === 'project' || scope === 'global'
+    },
+    envVar: 'TRAE_PROJECT_DIR',
+    hookEvent: 'beforeToolCall', // UNVERIFIED — see slice #2 closeout code-review M-1; will be validated when a real Trae 1.x install dogfoods the install path
+    toolMatcher: 'terminal', // UNVERIFIED — see slice #2 closeout code-review M-1
+    subAgentToolMatcher: 'Task', // UNVERIFIED — Trae's sub-agent tool name is unknown; matches the prior hardcoded 'Task' literal so byte-level install output is unchanged. Will be dogfooded when a real Trae 1.x install dispatches a sub-agent.
+    // Slice #009: Trae's sub-agent dispatcher is UNVERIFIED — Trae sub-agent
+    // tool name TBD on real dogfood; byte-level identical to claude-code by
+    // design so the slice #008 `subAgentToolMatcher: 'Task'` install entry
+    // stays byte-stable. Awaiting real Trae 1.x dogfood to confirm/replace.
+    subAgentDispatcher: traeSubAgentDispatcher,
+    // Slice #010 G9: Trae supports `beforeToolCall` which can wrap
+    // `peaks sub-agent-dispatch-guard`. Opt in (matches the byte-stable
+    // slice #008 install entry shape).
+    promptSizeAware: true,
+    installHints: [
+        'Restart Trae (or reload the workspace) so the beforeToolCall hooks take effect.'
+    ],
+    capabilities: {
+        gateEnforce: true,
+        progressStart: true,
+        statusline: true,
+        mcpInstall: false // Trae 的 MCP 集成尚未确定,先关掉避免误导
+    }
+};

package/dist/src/services/ide/hook-protocol.d.ts

@@ -0,0 +1,44 @@
+import { PEAKS_HOOK_SCHEMA, type IdeId, type PeaksCanonicalHook, type PeaksDecisionTransport } from './ide-types.js';
+export { PEAKS_HOOK_SCHEMA };
+export type { PeaksCanonicalHook, PeaksDecisionTransport };
+/**
+ * Compute the deny decision shape for Claude Code (the only adapter registered
+ * in slice #1). The output is a JSON object that, when written to stdout, makes
+ * the Claude Code permission system block the tool call BEFORE the user's
+ * permission prompt — un-bypassable, even under --dangerously-skip-permissions.
+ */
+export declare const CLAUDE_CODE_DENY_SHAPE: Record<string, unknown>;
+export declare const CLAUDE_CODE_DENY_TRANSPORT: PeaksDecisionTransport;
+/**
+ * Compute the deny decision shape for Trae (Cursor-style sibling IDE).
+ * UNVERIFIED — Trae 1.x's actual response envelope is a 1.x assumption
+ * (see src/services/ide/adapters/trae-adapter.ts). Slice #3 ships a
+ * Cursor-style envelope as the best-effort default; if a future slice
+ * confirms Trae's actual shape, update this constant and the related test.
+ */
+export declare const TRAE_DENY_SHAPE: Record<string, unknown>;
+export declare const TRAE_DENY_TRANSPORT: PeaksDecisionTransport;
+/**
+ * Format a decision response for a given IDE. Slice #1 handles Claude Code;
+ * slice #3 added Trae (1.x-assumption shape — see TRAE_DENY_SHAPE doc).
+ * Future slices will add exit-code / both variants for IDEs that don't read
+ * stdout.
+ */
+export declare function formatDecisionResponse(ide: IdeId, decision: 'allow' | 'deny', reason?: string): {
+    stdout: string;
+    exitCode: number;
+};
+/**
+ * Build a peaks canonical hook from a parsed stdin payload. Caller has already
+ * done stdin parsing + IDE auto-detection; this function normalizes to the
+ * canonical schema.
+ */
+export interface BuildCanonicalHookInput {
+    readonly toolName: string;
+    readonly toolInput: Record<string, unknown>;
+    readonly projectRoot: string;
+    readonly rawIdeFormat: IdeId;
+    readonly rawPayload: unknown;
+    readonly event?: PeaksCanonicalHook['event'];
+}
+export declare function buildCanonicalHook(input: BuildCanonicalHookInput): PeaksCanonicalHook;

package/dist/src/services/ide/hook-protocol.js

@@ -0,0 +1,71 @@
+import { PEAKS_HOOK_SCHEMA } from './ide-types.js';
+export { PEAKS_HOOK_SCHEMA };
+/**
+ * Compute the deny decision shape for Claude Code (the only adapter registered
+ * in slice #1). The output is a JSON object that, when written to stdout, makes
+ * the Claude Code permission system block the tool call BEFORE the user's
+ * permission prompt — un-bypassable, even under --dangerously-skip-permissions.
+ */
+export const CLAUDE_CODE_DENY_SHAPE = {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: '__REASON__' // replaced at format time
+    }
+};
+export const CLAUDE_CODE_DENY_TRANSPORT = {
+    kind: 'stdout-json',
+    denyShape: CLAUDE_CODE_DENY_SHAPE
+};
+/**
+ * Compute the deny decision shape for Trae (Cursor-style sibling IDE).
+ * UNVERIFIED — Trae 1.x's actual response envelope is a 1.x assumption
+ * (see src/services/ide/adapters/trae-adapter.ts). Slice #3 ships a
+ * Cursor-style envelope as the best-effort default; if a future slice
+ * confirms Trae's actual shape, update this constant and the related test.
+ */
+export const TRAE_DENY_SHAPE = {
+    hookSpecificOutput: {
+        hookEventName: 'beforeToolCall',
+        permissionDecision: 'deny',
+        permissionDecisionReason: '__REASON__' // replaced at format time
+    }
+};
+export const TRAE_DENY_TRANSPORT = {
+    kind: 'stdout-json',
+    denyShape: TRAE_DENY_SHAPE
+};
+/**
+ * Format a decision response for a given IDE. Slice #1 handles Claude Code;
+ * slice #3 added Trae (1.x-assumption shape — see TRAE_DENY_SHAPE doc).
+ * Future slices will add exit-code / both variants for IDEs that don't read
+ * stdout.
+ */
+export function formatDecisionResponse(ide, decision, reason) {
+    if (decision === 'allow') {
+        return { stdout: '', exitCode: 0 };
+    }
+    let shape;
+    if (ide === 'claude-code') {
+        shape = CLAUDE_CODE_DENY_SHAPE;
+    }
+    else if (ide === 'trae') {
+        shape = TRAE_DENY_SHAPE;
+    }
+    else {
+        throw new Error(`formatDecisionResponse: unsupported IDE ${ide} (not registered in adapter registry; future slice will add support)`);
+    }
+    const filled = JSON.stringify(shape).replace('"__REASON__"', JSON.stringify(reason ?? 'denied'));
+    return { stdout: filled, exitCode: 0 };
+}
+export function buildCanonicalHook(input) {
+    return {
+        schema: PEAKS_HOOK_SCHEMA,
+        event: input.event ?? 'pre-tool-use',
+        toolName: input.toolName,
+        toolInput: input.toolInput,
+        projectRoot: input.projectRoot,
+        rawIdeFormat: input.rawIdeFormat,
+        rawPayload: input.rawPayload
+    };
+}