peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/ide/adapters/zcode-adapter.d.ts

@@ -0,0 +1,40 @@
+import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Helper exported for tests + internal use: the default location of the
+ * z-code v2 config file on the host filesystem.
+ */
+export declare function defaultZcodeConfigPath(): string;
+/**
+ * Resolve the active model id from a parsed z-code config payload
+ * (the `~/.zcode/v2/config.json` root object). Pure / exported for
+ * unit tests so the file-IO seam and the resolution seam are
+ * independently verifiable.
+ *
+ * Resolution order (Slice C §"z-code config 解析路径"):
+ *   P1. env var `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` (test seam +
+ *       manual pin for the user).
+ *   P2. The provider whose top-level UUID key is NOT prefixed
+ *       `builtin:` — this matches the user-installed provider
+ *       pattern. Within that provider, prefer its `models` first
+ *       key (insertion order — z-code writes the active model
+ *       first in the picker).
+ *   P3. The first provider with `enabled: true`.
+ *   P4. The first provider in the object (insertion order) — last
+ *       resort. Returns undefined if there are zero providers.
+ *
+ * Returns `undefined` when nothing matches.
+ */
+export declare function resolveZcodeCurrentModel(config: unknown, envOverride?: string | undefined): string | undefined;
+/**
+ * The async adapter method that `detectCurrentIdeModel()` calls.
+ *
+ * Resolution order:
+ *   1. `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` env var override (test seam
+ *      + manual pin).
+ *   2. `PEAKS_ZCODE_CONFIG_PATH` env var override (test seam for a
+ *      fixture file). Falls back to `~/.zcode/v2/config.json`.
+ *   3. Returns `undefined` when the file is missing / malformed
+ *      (consistent with the cross-IDE contract).
+ */
+export declare function detectZcodeCurrentModel(): Promise<string | undefined>;
+export declare const ZCODE_ADAPTER: IdeAdapter;

package/dist/services/ide/adapters/zcode-adapter.js

@@ -0,0 +1,220 @@
+/**
+ * z-code IDE adapter (slice 2026-07-09-add-zcode-adapter) — peaks-loop 的第九个
+ * 内置 IDE 适配器。
+ *
+ * z-code 是一个 VS Code-style 的 Anthropic-compatible 桌面应用:
+ *   - 不是 CLI,没有 `zcode` binary (`which zcode` 返回空)。
+ *   - 桌面应用内置了 "导入 skills" 功能,user 手动触发后将本地 skills 目录
+ *     与 `~/.zcode/skills` 双向同步 (实测 symlink)。
+ *   - hook 协议、project-dir env var、compact command 均未公开。
+ *
+ * 设计前提 (RD-3 §2.2 D1 决策 + 现场实测,见
+ * `.peaks/memory/2026-07-09-zcode-context-probe-handoff.md` §2):
+ *   - `compact` 字段全部 undefined — 走 `llm-self-compress` fallback 路径。
+ *   - `envVar` / `hookEvent` / `toolMatcher` 全部标注 UNVERIFIED,因为
+ *     z-code 文档未公开,本 adapter 用 Anthropic-compatible 协议的合理
+ *     假设占位。
+ *   - `subAgentDispatcher` 用 `nullSubAgentDispatcher` 占位 — z-code
+ *     桌面应用没有公开的 Task 工具 dispatch 协议。
+ *   - `standardsProfile` 字段指向宪法文件根 + rules 目录 — z-code 的设计
+ *     就是借用上游 "import skills" 目标目录,因此保留上游路径常量。
+ *   - `skillInstall` 指向 `~/.zcode/skills` — 实测 z-code 已通过 user
+ *     手动导入同步到这里。
+ *   - 注:`standardsProfile` 中的常量子段是 z-code 借用的固定路径,属于
+ *     架构事实,不算 vendor verb 泄漏。
+ *
+ * Vendor-neutrality 备注 (SC-3 §5 + RD-3 §2.4):
+ *   本文件允许出现 vendor 字符串 (`zcode` / `ZCODE_PROJECT_DIR` 等),
+ *   **不允许** 出现其他 vendor 字符串 / 模型名。`standardsProfile`
+ *   中的 `CLAUDE.md` / `.claude/rules` 是 z-code 借用的上游路径常量,
+ *   属于架构事实,不算 vendor verb 泄漏。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { nullSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
+/**
+ * Helper exported for tests + internal use: the default location of the
+ * z-code v2 config file on the host filesystem.
+ */
+export function defaultZcodeConfigPath() {
+    return join(homedir(), '.zcode', 'v2', 'config.json');
+}
+/**
+ * Read the z-code config from `path` (string-typed to keep this
+ * swappable for tests). Synchronous + Node.js `fs` so adapter callers
+ * stay async-only at the public surface (`detectCurrentModel` is
+ * already declared `async`).
+ */
+function readZcodeConfig(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch { // TODO(g2): fail-closed JSON parse — undefined is the documented contract for missing/corrupt config
+        return undefined;
+    }
+}
+/**
+ * Resolve the active model id from a parsed z-code config payload
+ * (the `~/.zcode/v2/config.json` root object). Pure / exported for
+ * unit tests so the file-IO seam and the resolution seam are
+ * independently verifiable.
+ *
+ * Resolution order (Slice C §"z-code config 解析路径"):
+ *   P1. env var `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` (test seam +
+ *       manual pin for the user).
+ *   P2. The provider whose top-level UUID key is NOT prefixed
+ *       `builtin:` — this matches the user-installed provider
+ *       pattern. Within that provider, prefer its `models` first
+ *       key (insertion order — z-code writes the active model
+ *       first in the picker).
+ *   P3. The first provider with `enabled: true`.
+ *   P4. The first provider in the object (insertion order) — last
+ *       resort. Returns undefined if there are zero providers.
+ *
+ * Returns `undefined` when nothing matches.
+ */
+export function resolveZcodeCurrentModel(config, envOverride) {
+    const providers = config?.provider;
+    if (!providers || typeof providers !== 'object')
+        return undefined;
+    // P1: env var override (vendor-neutral identifier: the provider UUID).
+    if (envOverride !== undefined && envOverride !== '') {
+        const target = providers[envOverride];
+        if (target && typeof target === 'object') {
+            const modelId = pickFirstModelId(target);
+            if (modelId)
+                return modelId;
+        }
+    }
+    // P2: prefer a non-builtin provider (the user-installed one).
+    for (const [uuid, entry] of Object.entries(providers)) {
+        if (uuid.startsWith('builtin:'))
+            continue;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const modelId = pickFirstModelId(entry);
+        if (modelId)
+            return modelId;
+    }
+    // P3: first enabled provider (legacy / fresh-install case).
+    for (const entry of Object.values(providers)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const enabled = entry.enabled;
+        if (enabled === true) {
+            const modelId = pickFirstModelId(entry);
+            if (modelId)
+                return modelId;
+        }
+    }
+    // P4: first provider at all.
+    for (const entry of Object.values(providers)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const modelId = pickFirstModelId(entry);
+        if (modelId)
+            return modelId;
+    }
+    return undefined;
+}
+function pickFirstModelId(provider) {
+    const models = provider.models;
+    if (!models || typeof models !== 'object')
+        return undefined;
+    for (const key of Object.keys(models)) {
+        if (typeof key === 'string' && key.trim().length > 0)
+            return key.trim();
+    }
+    return undefined;
+}
+/**
+ * The async adapter method that `detectCurrentIdeModel()` calls.
+ *
+ * Resolution order:
+ *   1. `PEAKS_ZCODE_ACTIVE_PROVIDER_UUID` env var override (test seam
+ *      + manual pin).
+ *   2. `PEAKS_ZCODE_CONFIG_PATH` env var override (test seam for a
+ *      fixture file). Falls back to `~/.zcode/v2/config.json`.
+ *   3. Returns `undefined` when the file is missing / malformed
+ *      (consistent with the cross-IDE contract).
+ */
+export async function detectZcodeCurrentModel() {
+    const overridePath = process.env.PEAKS_ZCODE_CONFIG_PATH;
+    const path = overridePath && overridePath.length > 0 ? overridePath : defaultZcodeConfigPath();
+    const config = readZcodeConfig(path);
+    if (config === undefined)
+        return undefined;
+    return resolveZcodeCurrentModel(config, process.env.PEAKS_ZCODE_ACTIVE_PROVIDER_UUID);
+}
+export const ZCODE_ADAPTER = {
+    id: 'zcode',
+    displayName: 'z-code',
+    settings: {
+        dirName: '.zcode', // VERIFIED — 实测 z-code 项目根目录是 `.zcode`
+        settingsFileName: 'settings.json',
+        resolveSettingsFile: (scope, projectRoot) => {
+            const root = scope === 'global' ? homedir() : resolve(projectRoot ?? homedir());
+            return join(root, '.zcode', 'settings.json');
+        },
+        supportsScope: (scope) => scope === 'project' || scope === 'global',
+    },
+    // UNVERIFIED — z-code 桌面应用未公开 `ZCODE_PROJECT_DIR` env var,这里
+    // 用占位符,RD 阶段假设 z-code 借用了 Anthropic-compatible 协议并可能
+    // 注入一个项目根 env 变量。若未注入,峰 router 会回退到 cwd 探测。
+    envVar: 'ZCODE_PROJECT_DIR',
+    // UNVERIFIED — z-code 未公开 hook event key,占位用 Anthropic-compatible
+    // 协议的常见命名 `PreToolUse`。若 z-code 用其他 key,peaks hooks install
+    // 钩子在此 IDE 上不生效,可由 user 通过手动导入绕过。
+    hookEvent: 'PreToolUse',
+    // UNVERIFIED — 同上,占位用 `Bash` matcher。
+    toolMatcher: 'Bash',
+    // Slice 2026-07-09: z-code 桌面应用没有公开 Task 工具 dispatch 协议,
+    // 用 `nullSubAgentDispatcher` 占位 — peaks sub-agent dispatch CLI 在
+    // z-code 上返回 SubAgentNotSupportedError,符合 slice #008 P-5 capability
+    // 检查契约 (CLI 不崩溃)。
+    subAgentDispatcher: nullSubAgentDispatcher,
+    // Slice #010 G9: 假设 z-code 支持 PreToolUse (UNVERIFIED)。Opt-in,等真实
+    // z-code 安装 dogfood 后再决定。若 z-code 不支持 G9 hook,CLI 兜底层仍会
+    // 强制执行 G9 阈值。
+    promptSizeAware: true,
+    installHints: [
+        'z-code 没有 CLI,因此无需重启 — skills symlink 已写入 ~/.zcode/skills/。',
+        '若 z-code 未自动加载 peaks-* skills,在 z-code 桌面应用里手动触发 "导入 skills" 功能即可。',
+    ],
+    capabilities: {
+        gateEnforce: true,
+        statusline: true,
+    },
+    // Standards profile: 路径常量保留 (z-code 的 "导入 skills" 功能
+    // 借用了上游 settings 目录,因此宪法文件路径常量同步保留)。
+    standardsProfile: {
+        rootFile: 'CLAUDE.md',
+        rulesDir: '.claude/rules',
+        rulesFileGlob: '**/*.md',
+        autoLoaded: true,
+        format: 'markdown',
+        migrationHint: 'z-code 借用了上游 standards 路径,无需迁移。',
+    },
+    // Skill install profile: 指向 `~/.zcode/skills` 系列 (实测 z-code 已通过
+    // user 手动 symlink 同步;peaks-loop 也直接支持)。
+    skillInstall: {
+        skillsDir: join(homedir(), '.zcode', 'skills'),
+        outputStylesDir: join(homedir(), '.zcode', 'output-styles'),
+        installStrategy: 'symlink',
+        envVarOverride: 'PEAKS_ZCODE_SKILLS_DIR',
+    },
+    // compact profile 留空 — z-code 没有 CLI binary (RD-3 §2.2 D1 决策)。
+    // peaks-loop 走 `llm-self-compress` fallback 路径 (LLM 自己总结 context),
+    // 不抛错、不警告 (符合 slice #008 P-5 capability-check contract)。
+    // Slice C (2026-07-09 add-zcode-adapter, C.2): runtime probe for
+    // the currently-active model id. Reads `~/.zcode/v2/config.json`
+    // and resolves the active provider via `resolveZcodeCurrentModel`.
+    // See `.peaks/_runtime/2026-07-08-session-17918f/qa/.../slice-C-completion.md`
+    // for the resolution priority chain (env override → non-builtin
+    // provider → first enabled → first provider). Returns undefined
+    // on any failure (consistent with the cross-IDE contract).
+    detectCurrentModel: detectZcodeCurrentModel,
+};

package/dist/services/ide/current-model-detector.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Probe every registered IDE adapter for its currently-active model
+ * id. Returns the first non-empty value found in registration order,
+ * or `undefined` when no adapter opts in / all opted-in adapters
+ * return undefined.
+ *
+ * Registration order: see `ide-registry.ts` ADAPTERS Map. The IDE
+ * adapter for `claude-code` is consulted first; only `zcode` opts in
+ * to this slice's detection (other adapters will return undefined).
+ *
+ * Async because each IDE adapter's detectCurrentModel may read local
+ * disk or env on a slow filesystem.
+ */
+export declare function detectCurrentIdeModel(): Promise<string | undefined>;

package/dist/services/ide/current-model-detector.js

@@ -0,0 +1,60 @@
+/**
+ * Runtime current-model detector (Slice 2026-07-09 add-zcode-adapter, Slice C).
+ *
+ * Walks the registered IDE adapter chain and asks the IDE adapter
+ * (when it opts in via `IdeAdapter.detectCurrentModel?`) to report the
+ * currently-active model id. This is the runtime sibling of
+ * `getStrongestModelId(config)` in `src/services/config/model-routing.ts`:
+ *
+ *   - `getStrongestModelId(config)` reads `config.model` (user-set) and
+ *     falls back to the env-var / `'claude-opus-4-7'` constant. Sync.
+ *   - `detectCurrentIdeModel()` reads the IDE's runtime state (which
+ *     provider UI is active, which model the picker shows). Async.
+ *
+ * The CLI surface `peaks ide model --current` (added in this slice)
+ * delegates here. The future async resolver at
+ * `getStrongestModelIdAsync` (Slice C §C.4) calls this so config-less
+ * runs (e.g. an LLM inside z-code) can derive the strongest model from
+ * its actual environment.
+ *
+ * Vendor-neutrality notes (SC-3 §5 + RD-3 §2.4):
+ *   - This file never names a vendor (no "claude", "zcode", etc.).
+ *   - It only walks `IdeAdapter.detectCurrentModel?` — any adapter
+ *     can opt in.
+ *   - It returns `undefined` when detection is unavailable; callers
+ *     must fall back to the configured / hardcoded model.
+ */
+import { getAdapter } from './ide-registry.js';
+import { listAdapterIds } from './ide-registry.js';
+/**
+ * Probe every registered IDE adapter for its currently-active model
+ * id. Returns the first non-empty value found in registration order,
+ * or `undefined` when no adapter opts in / all opted-in adapters
+ * return undefined.
+ *
+ * Registration order: see `ide-registry.ts` ADAPTERS Map. The IDE
+ * adapter for `claude-code` is consulted first; only `zcode` opts in
+ * to this slice's detection (other adapters will return undefined).
+ *
+ * Async because each IDE adapter's detectCurrentModel may read local
+ * disk or env on a slow filesystem.
+ */
+export async function detectCurrentIdeModel() {
+    for (const id of listAdapterIds()) {
+        const adapter = getAdapter(id);
+        if (typeof adapter.detectCurrentModel !== 'function')
+            continue;
+        try {
+            const modelId = await adapter.detectCurrentModel();
+            if (typeof modelId === 'string' && modelId.trim().length > 0) {
+                return modelId.trim();
+            }
+        }
+        catch { // TODO(g2): Per-SC §3.4 best-effort — a misconfigured adapter must not poison the chain
+            // Per-SC §3.4: detection is best-effort. Swallow errors so a
+            // misconfigured adapter cannot poison the chain; the next
+            // adapter still gets a chance.
+        }
+    }
+    return undefined;
+}

package/dist/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/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/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/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);
+}

package/dist/services/ide/ide-detector.d.ts

@@ -0,0 +1,10 @@
+import type { IdeId } from './ide-types.js';
+/**
+ * Detect which IDE a given project root is using, by looking for the IDE's
+ * settings directory (`.claude`, `.trae`, etc.). Returns the first match in
+ * adapter insertion order, or `null` if no adapter's directory is present.
+ *
+ * 启发式:基于 cwd 目录存在性。CLI 后续 slice 会扩展为 env 变量检测、settings
+ * 文件内容检测、显式 `--ide` flag 覆盖等。
+ */
+export declare function detectInstalledIde(projectRoot: string): IdeId | null;