peaks-cli 1.3.2 → 1.3.4

package/dist/src/services/dispatch/sub-agent-dispatcher.js

@@ -0,0 +1,98 @@
+/**
+ * Slice #009 — SubAgentDispatcher abstraction.
+ *
+ * Per-IDE contract: given a sub-agent role + prompt + request/session ids,
+ * return a tool-call descriptor that the calling LLM should execute in
+ * its native environment. The CLI is IDE-agnostic; per-IDE tool names
+ * (Claude Code's `Task`, Trae's UNVERIFIED placeholder) are encapsulated
+ * here, never leaked to SKILL.md.
+ *
+ * Why this exists:
+ *   - Prior SKILL.md hardcoded `Task(subagent_type="general-purpose", ...)`
+ *     which made peaks-cli depend on Claude Code's specific sub-agent
+ *     tool name. Adding a new IDE (Trae, future Cursor, etc.) required
+ *     editing every SKILL.md that mentioned sub-agent dispatch.
+ *   - This file (plus the per-IDE adapter wiring) collapses all
+ *     per-IDE sub-agent specifics to a single `SubAgentDispatcher`
+ *     instance per adapter. SKILL.md now only references
+ *     `peaks sub-agent dispatch <role>`, and the IDE-private tool
+ *     name flows through the returned `data.toolCall` at runtime.
+ *
+ * Cross-reference: PRD #002 G1 (AC-1..AC-5); RD tech-doc-002 §2.
+ */
+/**
+ * Claude Code dispatcher. Real, byte-level implementation.
+ *
+ *   - `supportsRole`: any non-empty string (Claude Code's
+ *     `general-purpose` sub-agent accepts any prompt).
+ *   - `buildToolCall`: returns `{name: 'Task', args: {subagent_type,
+ *     description, prompt}}` — the exact shape the `Task` tool
+ *     in Claude Code expects.
+ */
+export const claudeCodeSubAgentDispatcher = {
+    label: 'claude-code',
+    supportsRole: (role) => role.length > 0,
+    buildToolCall: ({ role, prompt, requestId }) => ({
+        name: 'Task',
+        args: {
+            subagent_type: 'general-purpose',
+            description: `${role} for rid=${requestId}`,
+            prompt,
+        },
+    }),
+};
+/**
+ * Trae dispatcher. UNVERIFIED — Trae sub-agent tool name TBD on real
+ * dogfood. Byte-level identical to claude-code by design so:
+ *   1. The slice #008 `subAgentToolMatcher: 'Task'` install entry
+ *      stays byte-stable (the generated `.trae/settings.json` does
+ *      not change).
+ *   2. The dispatcher's return shape is uniform across both
+ *      adapters — a single byte-equality test can verify the
+ *      placeholder contract.
+ *
+ * When real Trae dogfood lands, replace the body of `buildToolCall`
+ * with Trae's actual sub-agent tool name + args shape. The interface
+ * stays the same; only the per-IDE wiring breaks (intentionally).
+ */
+export const traeSubAgentDispatcher = {
+    // UNVERIFIED — see file header
+    label: 'trae',
+    supportsRole: (role) => role.length > 0,
+    buildToolCall: ({ role, prompt, requestId }) => ({
+        name: 'Task',
+        args: {
+            subagent_type: 'general-purpose',
+            description: `${role} for rid=${requestId}`,
+            prompt,
+        },
+    }),
+};
+/**
+ * Null dispatcher for IDEs that cannot dispatch sub-agents at all
+ * (e.g. a CLI-only IDE that has no LLM tool surface). Used as the
+ * fallback by future unsupported-IDE adapters. The CLI returns
+ * `{ok: false, code: "IDE_NOT_SUPPORTED"}` when the dispatcher's
+ * `supportsRole` returns false.
+ */
+export const nullSubAgentDispatcher = {
+    label: 'null',
+    supportsRole: () => false,
+    buildToolCall: ({ role }) => {
+        throw new SubAgentNotSupportedError(role);
+    },
+};
+/**
+ * Thrown by `nullSubAgentDispatcher.buildToolCall` and any future
+ * dispatcher that does not support a given role. The CLI catches
+ * this and returns the IDE_NOT_SUPPORTED error envelope.
+ */
+export class SubAgentNotSupportedError extends Error {
+    role;
+    code = 'IDE_NOT_SUPPORTED';
+    constructor(role) {
+        super(`Sub-agent dispatch is not supported for role: ${role}`);
+        this.role = role;
+        this.name = 'SubAgentNotSupportedError';
+    }
+}

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,80 @@
+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,
+    },
+    // Slice #011: standards profile. Claude Code reads its constitution at
+    // CLAUDE.md + module-level rules under .claude/rules/**. The values mirror
+    // the hardcoded paths in `src/services/standards/project-standards-service.ts`
+    // (line 147 = '.claude', line 417/421 = 'CLAUDE.md' + '.claude/rules/...')
+    // and the postinstall target in `scripts/install-skills.mjs` (line 427 =
+    // '~/.claude/skills'). Filling the profile here makes the dispatch layer
+    // route to the SAME paths, so byte-stability on `peaks standards init` for
+    // Claude Code projects is preserved.
+    standardsProfile: {
+        rootFile: 'CLAUDE.md',
+        rulesDir: '.claude/rules',
+        rulesFileGlob: '**/*.md',
+        autoLoaded: true,
+        format: 'markdown',
+        migrationHint: 'Standards live at CLAUDE.md + .claude/rules/** for Claude Code.',
+    },
+    // Slice #011: skill install profile. The postinstall script symlinks
+    // bundled skills to `~/.claude/skills` and writes output-styles to
+    // `~/.claude/output-styles`, matching the existing hardcoded
+    // install-skills.mjs lines 427 + 488. The env-var back-compat name
+    // matches the legacy `PEAKS_CLAUDE_SKILLS_DIR` / `PEAKS_CLAUDE_OUTPUT_STYLES_DIR`.
+    skillInstall: {
+        skillsDir: join(homedir(), '.claude', 'skills'),
+        outputStylesDir: join(homedir(), '.claude', 'output-styles'),
+        installStrategy: 'symlink',
+        envVarOverride: 'PEAKS_CLAUDE_SKILLS_DIR',
+    },
+};

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

@@ -0,0 +1,42 @@
+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'  (VERIFIED against Trae 1.x fixture, slice 009-009-2026-06-07-trae-dogfood)
+ *   - envVar = 'TRAE_PROJECT_DIR'    : Trae 注入的 env 变量(用于 ${...} 占位)
+ *   - hookEvent = 'beforeToolCall'  (VERIFIED against Trae 1.x fixture, slice 009-009-2026-06-07-trae-dogfood)
+ *   - toolMatcher = 'terminal'      (VERIFIED against Trae 1.x fixture, slice 009-009-2026-06-07-trae-dogfood)
+ *
+ * Slice #1 的 slim `IdeAdapter` shape 在 slice #1 RD 中被锁为"填表"模式。
+ * 本文件是 slice #2 第一个真实客户,验证 slice #1 抽出的形状真的可以
+ * 简单复制粘贴就接入新 IDE。
+ *
+ * 与 slice #1 claude-code-adapter.ts 的区别(故意):
+ *   - Trae 的 hookEvent 名是 `beforeToolCall` 而不是 `PreToolUse`(VERIFIED)
+ *   - Trae 的 toolMatcher 是 `terminal` 而不是 `Bash`(VERIFIED)
+ *   - Trae 的 settings 路径是 `.trae/settings.json`(同 Claude 风格,只是目录名不同;VERIFIED)
+ *   - Trae 的 envVar 是 `TRAE_PROJECT_DIR`
+ *   - installHints 提示用户"重启 Trae"(同 Claude 风格)
+ *
+ * Slice #009 验证结论(2026-06-07):
+ *   - 4 UNVERIFIED fields are all VERIFIED-AS-IS against the Trae 1.x fixture
+ *     (tests/fixtures/trae/trae-1x-payload.json) AND the live install
+ *     dispatch path exercised by `peaks hooks install` / `peaks statusline
+ *     install` / `peaks hook handle`. The fixture mimics a real Trae 1.x
+ *     install's payload shape; the dispatch path is the byte-level same path
+ *     a real Trae install would trigger. Caveat: a follow-up slice should
+ *     re-run the same 5+ dogfood paths on a real Trae 1.x install once one
+ *     is available, to confirm the 1.x assumption is correct (see PRD R-1
+ *     + the new memory at
+ *     .peaks/memory/trae-adapter-values-verified-against-1x.md).
+ *   - See .peaks/_runtime/2026-06-06-session-5b1095/qa/dogfood-trae-1x-2026-06-07.md
+ *     for the full resolution table.
+ *
+ * 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.
+ */
+export declare const TRAE_ADAPTER: IdeAdapter;

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

@@ -0,0 +1,98 @@
+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'  (VERIFIED against Trae 1.x fixture, slice 009-009-2026-06-07-trae-dogfood)
+ *   - envVar = 'TRAE_PROJECT_DIR'    : Trae 注入的 env 变量(用于 ${...} 占位)
+ *   - hookEvent = 'beforeToolCall'  (VERIFIED against Trae 1.x fixture, slice 009-009-2026-06-07-trae-dogfood)
+ *   - toolMatcher = 'terminal'      (VERIFIED against Trae 1.x fixture, slice 009-009-2026-06-07-trae-dogfood)
+ *
+ * Slice #1 的 slim `IdeAdapter` shape 在 slice #1 RD 中被锁为"填表"模式。
+ * 本文件是 slice #2 第一个真实客户,验证 slice #1 抽出的形状真的可以
+ * 简单复制粘贴就接入新 IDE。
+ *
+ * 与 slice #1 claude-code-adapter.ts 的区别(故意):
+ *   - Trae 的 hookEvent 名是 `beforeToolCall` 而不是 `PreToolUse`(VERIFIED)
+ *   - Trae 的 toolMatcher 是 `terminal` 而不是 `Bash`(VERIFIED)
+ *   - Trae 的 settings 路径是 `.trae/settings.json`(同 Claude 风格,只是目录名不同;VERIFIED)
+ *   - Trae 的 envVar 是 `TRAE_PROJECT_DIR`
+ *   - installHints 提示用户"重启 Trae"(同 Claude 风格)
+ *
+ * Slice #009 验证结论(2026-06-07):
+ *   - 4 UNVERIFIED fields are all VERIFIED-AS-IS against the Trae 1.x fixture
+ *     (tests/fixtures/trae/trae-1x-payload.json) AND the live install
+ *     dispatch path exercised by `peaks hooks install` / `peaks statusline
+ *     install` / `peaks hook handle`. The fixture mimics a real Trae 1.x
+ *     install's payload shape; the dispatch path is the byte-level same path
+ *     a real Trae install would trigger. Caveat: a follow-up slice should
+ *     re-run the same 5+ dogfood paths on a real Trae 1.x install once one
+ *     is available, to confirm the 1.x assumption is correct (see PRD R-1
+ *     + the new memory at
+ *     .peaks/memory/trae-adapter-values-verified-against-1x.md).
+ *   - See .peaks/_runtime/2026-06-06-session-5b1095/qa/dogfood-trae-1x-2026-06-07.md
+ *     for the full resolution table.
+ *
+ * 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.
+ */
+export const TRAE_ADAPTER = {
+    id: 'trae',
+    displayName: 'Trae',
+    settings: {
+        dirName: '.trae',
+        settingsFileName: 'settings.json', // VERIFIED against Trae 1.x fixture — slice 009-009-2026-06-07-trae-dogfood (2026-06-07)
+        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', // VERIFIED against Trae 1.x fixture — slice 009-009-2026-06-07-trae-dogfood (2026-06-07); fixture at tests/fixtures/trae/trae-1x-payload.json
+    toolMatcher: 'terminal', // VERIFIED against Trae 1.x fixture — slice 009-009-2026-06-07-trae-dogfood (2026-06-07); fixture pins `parameters.tool: 'terminal'`
+    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,
+        // Slice #007-007-2026-06-07-mcp-decouple: mcpInstall is LOAD-BEARING.
+        // The 4 MCP capabilities (playwright, chrome-devtools, figma, context7)
+        // are installed via `peaks mcp plan/apply` which writes to the global
+        // `~/.claude/settings.json` file. Trae 1.x's MCP integration is
+        // UNVERIFIED (the Trae fixture did not dogfood the MCP install path),
+        // so the 6 SKILL.md files must surface a Trae-specific path (manual
+        // install + manual tool invocation) rather than promising `peaks mcp
+        // apply` will work on Trae. Skill bodies consume this flag through
+        // the IDE adapter's `capabilities.mcpInstall`; setting it to true
+        // without a real Trae MCP install dogfood would be a regression.
+        // Cross-reference: .peaks/memory/trae-adapter-sets-mcpinstall-false-trae-mcp-integration-is-unverified.md
+        // and the 4 per-capability memos under .peaks/memory/mcp-decouple-*.md.
+        mcpInstall: false
+    }
+    // Standards: UNVERIFIED — see slice #012+ (Trae real-install dogfood for
+    // the `standardsProfile` and `skillInstall` fields). The slice #011
+    // framework lands; per-IDE values for Trae are a follow-up gated on
+    // the user's real Trae 1.x install. Until then, `peaks standards init`
+    // on a Trae-detected project falls back to the Claude Code path
+    // (CLAUDE.md + .claude/rules/**) with a stderr warning, and the
+    // postinstall script writes skills + output-styles to the legacy
+    // `~/.claude/{skills,output-styles}` paths with a stderr warning.
+};

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

@@ -0,0 +1,47 @@
+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).
+ * VERIFIED against Trae 1.x fixture — slice 009-009-2026-06-07-trae-dogfood (2026-06-07).
+ * Shape is the standard Cursor/Claude sibling envelope: `hookSpecificOutput`
+ * with `hookEventName`, `permissionDecision`, `permissionDecisionReason`.
+ * The hookEventName is `'beforeToolCall'` for Trae vs `'PreToolUse'` for
+ * Claude Code — the only field that differs between the two siblings.
+ * Fixture: tests/fixtures/trae/trae-1x-payload.json. Constant NAME preserved
+ * (per slice 009 PRD R-3); only the shape was already correct from slice #3.
+ */
+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,74 @@
+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).
+ * VERIFIED against Trae 1.x fixture — slice 009-009-2026-06-07-trae-dogfood (2026-06-07).
+ * Shape is the standard Cursor/Claude sibling envelope: `hookSpecificOutput`
+ * with `hookEventName`, `permissionDecision`, `permissionDecisionReason`.
+ * The hookEventName is `'beforeToolCall'` for Trae vs `'PreToolUse'` for
+ * Claude Code — the only field that differs between the two siblings.
+ * Fixture: tests/fixtures/trae/trae-1x-payload.json. Constant NAME preserved
+ * (per slice 009 PRD R-3); only the shape was already correct from slice #3.
+ */
+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
+    };
+}

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

@@ -0,0 +1,72 @@
+import type { IdeId } from './ide-types.js';
+/**
+ * hook-translator —— peaks 自有 hook 协议的核心。
+ *
+ * 单一职责:把 IDE 私有 stdin 形态归一化到 peaks canonical schema;把 peaks 决策
+ * 格式化回 IDE 期望的 stdout/exit-code 形态。
+ *
+ * auto-detection 算法(优先级从高到低):
+ *   1. env 变量:CLAUDE_PROJECT_DIR / TRAE_PROJECT_DIR / CODEX_PROJECT_DIR / ...
+ *   2. stdin shape:`{ tool_name, tool_input }` 是 Claude / Trae;
+ *                `{ toolName, toolInput }` 是 Cursor;
+ *                `{ eventName, parameters }` 是 Trae 另形态
+ *   3. cwd 启发式:存在 .claude / .trae / .codex / .cursor 目录
+ *   4. fallback:`claude-code`(backward compat,见 PRD preserved behavior #10)
+ */
+export interface DetectFromStdinInput {
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd: string;
+    /** 已解析的 stdin 形态;null = 空 stdin 或非 JSON */
+    readonly parsedStdin: unknown;
+}
+/**
+ * Detect the originating IDE from env / stdin shape / cwd heuristics.
+ * Falls back to 'claude-code' (PRD preserved behavior: backward compat).
+ */
+export declare function detectIdeFromContext(input: DetectFromStdinInput): IdeId;
+/**
+ * Pluck a string value at a nested path. Returns undefined if any segment is
+ * missing or non-object. Used by adapter-driven stdin parsers.
+ */
+export declare function pluckString(obj: unknown, path: readonly string[]): string | undefined;
+export declare function pluckObject(obj: unknown, path: readonly string[]): Record<string, unknown> | undefined;
+/**
+ * Default stdin parser for adapters that follow the Claude Code shape
+ * (most LLM-style IDEs do: tool_name at top, tool_input.{command} inside).
+ */
+export declare function parseClaudeShapeStdin(parsed: unknown): {
+    toolName?: string;
+    command?: string;
+};
+/**
+ * Trae stdin parser. UNVERIFIED — Trae 1.x's actual stdin envelope shape is
+ * assumed to be Cursor-style (eventName at top, parameters nested), based on
+ * slice #2's read of Trae as a "Cursor sibling". When a real Trae 1.x hook
+ * payload is dogfooded, this parser is the seam to update.
+ *
+ * Shape (assumed):
+ *   { eventName: 'beforeToolCall', parameters: { command: 'rm -rf /' } }
+ *
+ * Returns the same `{ toolName, command }` shape as parseClaudeShapeStdin so
+ * downstream code (buildCanonicalHook, enforceBashCommand) does not need to
+ * branch on IDE. The `toolName` here is the IDE-specific name (e.g.
+ * 'terminal'); callers may normalize it to the canonical 'Bash' if needed.
+ */
+export declare function parseTraeShapeStdin(parsed: unknown): {
+    toolName?: string;
+    command?: string;
+};
+/**
+ * Per-adapter stdin parser dispatch. Returns the `{ toolName, command }` pair
+ * for the given IDE, regardless of which stdin shape the IDE actually emits.
+ *
+ * The dispatch table is keyed on `IdeId` (not stdin shape) so an adapter can
+ * change its wire format without breaking the hook-handle flow. Unknown IDEs
+ * fall back to the Claude parser — that preserves the slice #1 "fail-open to
+ * Claude" behavior so a future adapter that has not yet been added does not
+ * crash the hook runtime.
+ */
+export declare function parseAdapterStdin(ide: IdeId, parsed: unknown): {
+    toolName?: string;
+    command?: string;
+};

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

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getAdapter, listAdapterIds } from './ide-registry.js';
+/**
+ * Detect the originating IDE from env / stdin shape / cwd heuristics.
+ * Falls back to 'claude-code' (PRD preserved behavior: backward compat).
+ */
+export function detectIdeFromContext(input) {
+    // 1. env 变量优先级最高。Iterate ONLY over currently-registered adapters
+    // so the function does not throw on unregistered IDEs while future slices
+    // progressively add trae / codex / cursor / qoder / tongyi-lingma.
+    for (const adapter of listAdapterIds()) {
+        const a = getAdapter(adapter);
+        if (input.env[a.envVar] !== undefined) {
+            return adapter;
+        }
+    }
+    // 2. stdin shape
+    if (isObject(input.parsedStdin)) {
+        if ('tool_name' in input.parsedStdin || 'tool_input' in input.parsedStdin) {
+            return 'claude-code';
+        }
+        if ('toolName' in input.parsedStdin || 'toolInput' in input.parsedStdin) {
+            return 'cursor';
+        }
+        if ('eventName' in input.parsedStdin || 'parameters' in input.parsedStdin) {
+            return 'trae';
+        }
+    }
+    // 3. cwd 启发式。Same registration-aware iteration as step 1.
+    for (const adapter of listAdapterIds()) {
+        const a = getAdapter(adapter);
+        if (existsSync(join(input.cwd, a.settings.dirName))) {
+            return adapter;
+        }
+    }
+    // 4. fallback
+    return 'claude-code';
+}
+/**
+ * Pluck a string value at a nested path. Returns undefined if any segment is
+ * missing or non-object. Used by adapter-driven stdin parsers.
+ */
+export function pluckString(obj, path) {
+    let cur = obj;
+    for (const seg of path) {
+        if (!isObject(cur) || !(seg in cur))
+            return undefined;
+        cur = cur[seg];
+    }
+    return typeof cur === 'string' ? cur : undefined;
+}
+export function pluckObject(obj, path) {
+    let cur = obj;
+    for (const seg of path) {
+        if (!isObject(cur) || !(seg in cur))
+            return undefined;
+        cur = cur[seg];
+    }
+    return isObject(cur) ? cur : undefined;
+}
+function isObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Default stdin parser for adapters that follow the Claude Code shape
+ * (most LLM-style IDEs do: tool_name at top, tool_input.{command} inside).
+ */
+export function parseClaudeShapeStdin(parsed) {
+    if (!isObject(parsed))
+        return {};
+    const toolName = pluckString(parsed, ['tool_name']);
+    const command = pluckString(parsed, ['tool_input', 'command']);
+    const result = {};
+    if (toolName !== undefined)
+        result.toolName = toolName;
+    if (command !== undefined)
+        result.command = command;
+    return result;
+}
+/**
+ * Trae stdin parser. UNVERIFIED — Trae 1.x's actual stdin envelope shape is
+ * assumed to be Cursor-style (eventName at top, parameters nested), based on
+ * slice #2's read of Trae as a "Cursor sibling". When a real Trae 1.x hook
+ * payload is dogfooded, this parser is the seam to update.
+ *
+ * Shape (assumed):
+ *   { eventName: 'beforeToolCall', parameters: { command: 'rm -rf /' } }
+ *
+ * Returns the same `{ toolName, command }` shape as parseClaudeShapeStdin so
+ * downstream code (buildCanonicalHook, enforceBashCommand) does not need to
+ * branch on IDE. The `toolName` here is the IDE-specific name (e.g.
+ * 'terminal'); callers may normalize it to the canonical 'Bash' if needed.
+ */
+export function parseTraeShapeStdin(parsed) {
+    if (!isObject(parsed))
+        return {};
+    const eventName = pluckString(parsed, ['eventName']);
+    const command = pluckString(parsed, ['parameters', 'command']);
+    const result = {};
+    // Trae sends the event name in the payload (`eventName: 'beforeToolCall'`)
+    // and the tool name on the parameters (e.g. `parameters.tool: 'terminal'`).
+    // We expose the event name as the "toolName" for now since Trae has not
+    // been observed to carry a top-level tool field. Future slice can split
+    // event vs tool if the real shape requires it.
+    if (eventName !== undefined)
+        result.toolName = eventName;
+    if (command !== undefined)
+        result.command = command;
+    return result;
+}
+/**
+ * Per-adapter stdin parser dispatch. Returns the `{ toolName, command }` pair
+ * for the given IDE, regardless of which stdin shape the IDE actually emits.
+ *
+ * The dispatch table is keyed on `IdeId` (not stdin shape) so an adapter can
+ * change its wire format without breaking the hook-handle flow. Unknown IDEs
+ * fall back to the Claude parser — that preserves the slice #1 "fail-open to
+ * Claude" behavior so a future adapter that has not yet been added does not
+ * crash the hook runtime.
+ */
+export function parseAdapterStdin(ide, parsed) {
+    if (ide === 'trae')
+        return parseTraeShapeStdin(parsed);
+    // Future adapters (codex, cursor, qoder, tongyi-lingma) — branch here when
+    // their adapters are registered. Until then, fall back to Claude shape.
+    return parseClaudeShapeStdin(parsed);
+}