peaks-cli 1.3.2 → 1.3.4

package/dist/src/services/skill/skill-scheduler.js

@@ -0,0 +1,53 @@
+/**
+ * G6 — skill-level heartbeat scheduler config.
+ *
+ * Slice 2026-06-07-sub-agent-dispatch-decouple (G6): the SKILL.md front
+ * matter for a Dispatcher (peaks-solo / peaks-rd / peaks-qa) can opt
+ * into a non-default heartbeat interval by including a line like:
+ *
+ *   heartbeatIntervalSec: 15
+ *
+ * The default is 30 s (RL-13 empirical sweet spot). The poller
+ * cadence is fixed at 10 s (sub-agent 30 s / poller 10 s is the
+ * jitter-resistant offset).
+ *
+ * This module is a pure-key parser — it takes a SKILL.md body and
+ * returns the effective config. The Dispatcher's prompt template
+ * for sub-agents is then responsible for inlining the chosen value
+ * into the sub-agent prompt so that the LLM knows how often to
+ * call `peaks sub-agent heartbeat`.
+ *
+ * Note: the heartbeat *cadence* the LLM uses is enforced socially
+ * (via the prompt), not via any hook. R-1 / R-8 boundary — LLM
+ * behaviour is not observable. The user has been explicit about
+ * this: "心跳是 sub-agent 主动写, peaks CLI 不观测 LLM 行为".
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_SEC = 30;
+export const MIN_HEARTBEAT_INTERVAL_SEC = 5;
+export const MAX_HEARTBEAT_INTERVAL_SEC = 600;
+/** Parse a SKILL.md body for a `heartbeatIntervalSec: <N>` line. */
+export function parseHeartbeatConfig(skillBody) {
+    const match = skillBody.match(/^\s*heartbeatIntervalSec\s*:\s*(\d+)\s*$/m);
+    if (!match) {
+        return { intervalSec: DEFAULT_HEARTBEAT_INTERVAL_SEC, source: 'default' };
+    }
+    const value = Number.parseInt(match[1], 10);
+    if (!Number.isInteger(value) || value < MIN_HEARTBEAT_INTERVAL_SEC || value > MAX_HEARTBEAT_INTERVAL_SEC) {
+        return { intervalSec: DEFAULT_HEARTBEAT_INTERVAL_SEC, source: 'default' };
+    }
+    return { intervalSec: value, source: 'skill-frontmatter' };
+}
+/**
+ * Build the heartbeat-instruction paragraph to inline in a sub-agent
+ * prompt. The LLM reads this and adjusts its `peaks sub-agent
+ * heartbeat` cadence accordingly.
+ */
+export function heartbeatInstructionParagraph(config) {
+    return (`While running, call ` +
+        `\`peaks sub-agent heartbeat --record <dispatchRecordPath> --status <state> --progress <pct> --note "<text>"\` ` +
+        `at least every ${config.intervalSec} seconds (the Dispatcher expects ` +
+        `${config.intervalSec}s cadence; default 30s, your SKILL.md overrides to ${config.intervalSec}s). ` +
+        `On completion, call \`--status done --progress 100 --note "completed"\`. ` +
+        `On failure, \`--status failed\`. Do not skip heartbeats; the parent ` +
+        `Dispatcher uses them to keep the user informed during the wait.`);
+}

package/dist/src/services/skills/hooks-settings-service.d.ts

@@ -1,43 +1,59 @@
+import type { IdeId } from '../ide/ide-types.js';
+import type { HookScope } from '../ide/shared/safe-path.js';
 /**
- * Installs (and removes) the Peaks gate-enforcement PreToolUse hook in a Claude
- * Code settings.json. The hook runs `peaks gate enforce` before every Bash call;
- * when a SOP guard's gates fail it returns `permissionDecision: "deny"`, which
- * blocks the tool call BEFORE Claude Code's permission checks — making the gate
- * un-bypassable by the agent (it holds even under --dangerously-skip-permissions).
+ * Install (and remove) the Peaks-managed hooks in an IDE's settings.json.
+ *
+ * The hook runs `peaks gate enforce` (Claude) or `peaks hook handle` (Trae /
+ * other future adapters) before every relevant tool call; when a SOP guard's
+ * gates fail it returns the adapter-specific deny shape, which blocks the
+ * tool call BEFORE the IDE's permission checks — making the gate
+ * un-bypassable by the agent.
+ *
+ * Slice #1 refactor: this service delegates to the `IdeAdapter` for
+ * `claude-code`. Slice #2 added Trae. Adapter provides `dirName` /
+ * `settingsFileName` / `envVar` / `hookEvent` / `toolMatcher`. The Claude
+ * install path is byte-level-compat with slice #0 (AC-1).
+ *
+ * Slice #3 refactor (this commit): the service is now per-IDE aware via an
+ * optional `options.ide` parameter. The CLI command is responsible for
+ * resolving the IDE (env → stdin shape → cwd → fallback to 'claude-code')
+ * via `detectIdeFromContext` and passing the result here. When `ide` is
+ * omitted, the service defaults to `'claude-code'` so existing tests and
+ * downstream callers continue to work without modification.
  *
  * Installation is an EXPLICIT user command (never postinstall): skills describe,
- * the CLI performs side effects. Writes preserve all other settings keys and any
- * other hooks, reject symlinked targets, and use an atomic rename so a partial
- * write can never corrupt the settings file. Our entry is merged into (not
- * replacing) the existing `hooks.PreToolUse` array and is identified by a
+ * the CLI performs side effects. Writes preserve all other settings keys and
+ * any other hooks, reject symlinked targets, and use an atomic rename so a
+ * partial write can never corrupt the settings file. Our entry is merged into
+ * (not replacing) the existing `hooks.<event>` array and is identified by a
  * sentinel substring in its command, so install is idempotent and uninstall
  * removes only our own entry.
  */
-export type HookScope = 'project' | 'global';
-/** The hook command written into settings for the gate-enforce PreToolUse hook. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
-export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
-/**
- * Hook command for the sub-agent progress auto-spawn. Fires on every Task
- * tool call (the harness-enforced mechanism for "sub-agent dispatch"). The
- * command itself is non-blocking: `peaks progress start` is idempotent
- * (5-minute TTL on the spawn record) so the LLM does not see a fresh
- * terminal per Task. The `--quiet` flag keeps the LLM context clean — the
- * hook output otherwise adds ~500 tokens per Task call.
- */
-export declare const HOOK_PROGRESS_COMMAND = "peaks progress start --project \"${CLAUDE_PROJECT_DIR}\" --reason \"auto-spawn for sub-agent Task\" --quiet";
-/** Substring that identifies a Peaks-managed PreToolUse gate-enforce hook entry. */
+export type { HookScope } from '../ide/shared/safe-path.js';
+export type HookInstallOptions = {
+    /**
+     * Which IDE's adapter to install for. Defaults to `'claude-code'` for
+     * backward compatibility. The CLI command should resolve this from
+     * `detectIdeFromContext({ env, cwd, parsedStdin })` and pass the result.
+     * Throws if the IDE is not registered in the adapter registry.
+     */
+    readonly ide?: IdeId;
+};
+/** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export declare const HOOK_ENFORCE_SENTINEL = "peaks gate enforce";
-/** Substring that identifies a Peaks-managed PreToolUse sub-agent-progress hook entry. */
+/** Sentinel substring identifying a peaks-managed sub-agent-progress hook entry. */
 export declare const HOOK_PROGRESS_SENTINEL = "peaks progress start";
+/** Default (claude-code) hook command — kept as a stable export for tests. */
+export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
+/** Default (claude-code) progress command — kept as a stable export for tests. */
+export declare const HOOK_PROGRESS_COMMAND = "peaks progress start --project \"${CLAUDE_PROJECT_DIR}\" --reason \"auto-spawn for sub-agent Task\" --quiet";
 export type HookInstallPlan = {
     scope: HookScope;
     settingsPath: string;
     exists: boolean;
     alreadyInstalled: boolean;
     desiredCommand: string;
-    /** Substring sentinel used to detect the entry. */
     sentinel: string;
-    /** Tool name (Bash | Task) the PreToolUse hook is keyed on. */
     matcher: string;
 };
 export type HookInstallResult = HookInstallPlan & {
@@ -59,9 +75,11 @@ export type PeaksHookEntry = {
     sentinel: string;
     matcher: string;
     command: string;
+    event: string;
 };
+/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. */
 export declare const PEAKS_HOOK_ENTRIES: ReadonlyArray<PeaksHookEntry>;
-export declare function planHookInstall(scope: HookScope, projectRoot?: string): HookInstallPlan;
-export declare function applyHookInstall(scope: HookScope, projectRoot?: string): HookInstallResult;
-export declare function removeHookInstall(scope: HookScope, projectRoot?: string): HookRemoveResult;
-export declare function readHookStatus(scope: HookScope, projectRoot?: string): HookStatus;
+export declare function planHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookInstallPlan;
+export declare function applyHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookInstallResult;
+export declare function removeHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookRemoveResult;
+export declare function readHookStatus(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookStatus;

package/dist/src/services/skills/hooks-settings-service.js

@@ -1,38 +1,57 @@
-import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-/** The hook command written into settings for the gate-enforce PreToolUse hook. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
-export const HOOK_ENFORCE_COMMAND = 'peaks gate enforce --project "${CLAUDE_PROJECT_DIR}"';
-/**
- * Hook command for the sub-agent progress auto-spawn. Fires on every Task
- * tool call (the harness-enforced mechanism for "sub-agent dispatch"). The
- * command itself is non-blocking: `peaks progress start` is idempotent
- * (5-minute TTL on the spawn record) so the LLM does not see a fresh
- * terminal per Task. The `--quiet` flag keeps the LLM context clean — the
- * hook output otherwise adds ~500 tokens per Task call.
- */
-export const HOOK_PROGRESS_COMMAND = 'peaks progress start --project "${CLAUDE_PROJECT_DIR}" --reason "auto-spawn for sub-agent Task" --quiet';
-/** Substring that identifies a Peaks-managed PreToolUse gate-enforce hook entry. */
+import { resolve } from 'node:path';
+import { assertSafeSettingsFile } from '../ide/shared/safe-path.js';
+import { atomicWriteJson, readJsonObjectFile } from '../ide/shared/atomic-json.js';
+import { getAdapter } from '../ide/ide-registry.js';
+// --- Module-level defaults (claude-code) -----------------------------------
+// These exports remain for backward compat — tests and downstream callers
+// that only care about Claude Code can keep importing them. The per-IDE
+// values are computed lazily inside each public function call.
+/** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
-/** Substring that identifies a Peaks-managed PreToolUse sub-agent-progress hook entry. */
+/** Sentinel substring identifying a peaks-managed sub-agent-progress hook entry. */
 export const HOOK_PROGRESS_SENTINEL = 'peaks progress start';
-const HOOK_GATE_MATCHER = 'Bash';
-const HOOK_PROGRESS_MATCHER = 'Task';
-/**
- * Substring sentinels that identify a Peaks-managed PreToolUse hook entry.
- * Used to keep `uninstall` and `isInstalled` checks tight: we only touch
- * entries we wrote, never third-party hooks.
- */
-const PEAKS_HOOK_SENTINELS = [HOOK_ENFORCE_SENTINEL, HOOK_PROGRESS_SENTINEL];
-export const PEAKS_HOOK_ENTRIES = [
-    { sentinel: HOOK_ENFORCE_SENTINEL, matcher: HOOK_GATE_MATCHER, command: HOOK_ENFORCE_COMMAND },
-    { sentinel: HOOK_PROGRESS_SENTINEL, matcher: HOOK_PROGRESS_MATCHER, command: HOOK_PROGRESS_COMMAND }
-];
-function isInsidePath(childPath, parentPath) {
-    const rel = relative(parentPath, childPath);
-    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+/** Default (claude-code) hook command — kept as a stable export for tests. */
+export const HOOK_ENFORCE_COMMAND = `peaks gate enforce --project "\${CLAUDE_PROJECT_DIR}"`;
+/** Default (claude-code) progress command — kept as a stable export for tests. */
+export const HOOK_PROGRESS_COMMAND = `peaks progress start --project "\${CLAUDE_PROJECT_DIR}" --reason "auto-spawn for sub-agent Task" --quiet`;
+function resolveHookSpec(ide) {
+    const adapter = getAdapter(ide);
+    if (ide === 'claude-code') {
+        return {
+            hookEnforceCommand: `peaks gate enforce --project "\${${adapter.envVar}}"`,
+            hookProgressCommand: `peaks progress start --project "\${${adapter.envVar}}" --reason "auto-spawn for sub-agent ${adapter.subAgentToolMatcher}" --quiet`,
+            hookEnforceSentinel: HOOK_ENFORCE_SENTINEL,
+            hookProgressSentinel: HOOK_PROGRESS_SENTINEL,
+            hookEnforceMatcher: adapter.toolMatcher, // 'Bash'
+            hookProgressMatcher: adapter.subAgentToolMatcher, // 'Task' (slice 2026-06-06-sub-agent-spawn-bug-and-decouple — adapter now self-reports sub-agent tool name)
+            hookEnforceEvent: adapter.hookEvent, // 'PreToolUse'
+            hookProgressEvent: adapter.hookEvent // 'PreToolUse' for Claude
+        };
+    }
+    if (ide === 'trae') {
+        return {
+            hookEnforceCommand: `peaks hook handle --project "\${${adapter.envVar}}"`,
+            hookProgressCommand: `peaks progress start --project "\${${adapter.envVar}}" --reason "auto-spawn for sub-agent ${adapter.subAgentToolMatcher}" --quiet`,
+            hookEnforceSentinel: 'peaks hook handle',
+            hookProgressSentinel: HOOK_PROGRESS_SENTINEL,
+            hookEnforceMatcher: adapter.toolMatcher, // 'terminal'
+            hookProgressMatcher: adapter.subAgentToolMatcher, // 'Task' (UNVERIFIED for Trae; matches prior hardcoded literal so byte-level install output is unchanged)
+            hookEnforceEvent: adapter.hookEvent, // 'beforeToolCall'
+            hookProgressEvent: adapter.hookEvent // 'beforeToolCall' (no separate progress event yet for Trae)
+        };
+    }
+    // Future adapters (codex, cursor, qoder, tongyi-lingma) — not yet registered.
+    // When a slice adds them, branch here. Until then, throw a clear error so
+    // the CLI surfaces "unsupported IDE" instead of writing a Claude-shaped
+    // entry to a non-Claude settings.json.
+    throw new Error(`peaks hooks install: unsupported IDE '${ide}' (not registered in adapter registry; future slice will add support)`);
 }
+function resolveIde(options) {
+    return options?.ide ?? 'claude-code';
+}
+/** Resolve settings root dir for a scope. */
 function resolveSettingsRoot(scope, projectRoot) {
     if (scope === 'global')
         return resolve(homedir());
@@ -41,76 +60,37 @@ function resolveSettingsRoot(scope, projectRoot) {
     }
     return resolve(projectRoot);
 }
-function resolveSettingsPath(scope, projectRoot) {
-    return join(resolveSettingsRoot(scope, projectRoot), '.claude', 'settings.json');
-}
-function assertSafeSettingsPath(scope, root, settingsPath) {
-    const claudeDir = join(root, '.claude');
-    if (existsSync(claudeDir) && lstatSync(claudeDir).isSymbolicLink()) {
-        throw new Error('.claude directory must not be a symlink');
-    }
-    if (existsSync(settingsPath)) {
-        if (lstatSync(settingsPath).isSymbolicLink()) {
-            throw new Error('settings.json must not be a symlink');
-        }
-        const realRoot = realpathSync(root);
-        if (!isInsidePath(realpathSync(settingsPath), realRoot)) {
-            throw new Error(`settings.json must stay inside the ${scope} root`);
-        }
-    }
-}
-function readSettings(settingsPath) {
-    if (!existsSync(settingsPath))
-        return {};
-    const fd = openSync(settingsPath, constants.O_RDONLY | constants.O_NOFOLLOW);
-    try {
-        const raw = readFileSync(fd, 'utf8').trim();
-        if (raw.length === 0)
-            return {};
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('settings.json must contain a JSON object');
-        }
-        return parsed;
-    }
-    finally {
-        closeSync(fd);
-    }
+function resolveSettingsPath(scope, ide, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const adapter = getAdapter(ide);
+    return adapter.settings.resolveSettingsFile(scope, scope === 'global' ? homedir() : projectRoot);
 }
-function atomicWriteJson(settingsPath, settings) {
-    const dir = dirname(settingsPath);
-    mkdirSync(dir, { recursive: true });
-    const tempPath = join(dir, `.settings.${randomUUID()}.tmp`);
-    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-    try {
-        writeFileSync(fd, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
-    }
-    finally {
-        closeSync(fd);
-    }
-    try {
-        renameSync(tempPath, settingsPath);
-    }
-    catch (error) {
-        try {
-            unlinkSync(tempPath);
-        }
-        catch {
-            // best effort cleanup
-        }
-        throw error;
+function assertSafeSettingsPathCompat(scope, ide, root, settingsPath) {
+    const adapter = getAdapter(ide);
+    assertSafeSettingsFile(scope, root, adapter.settings.dirName, adapter.settings.settingsFileName);
+    // The compat path receives the already-computed settingsPath; double-check
+    // that the computed path matches what assertSafeSettingsFile would have
+    // produced. This guards against drift between the two resolvers.
+    const expected = adapter.settings.resolveSettingsFile(scope, scope === 'global' ? homedir() : root);
+    if (expected !== settingsPath) {
+        throw new Error(`settings path drift: ${expected} vs ${settingsPath}`);
     }
 }
-/** Read the existing PreToolUse matcher entries (tolerant of any prior shape). */
-function readPreToolUse(settings) {
+/** Read the existing hook array entries for the adapter's hookEvent (tolerant of any prior shape). */
+function readHookEventEntries(settings, eventKey) {
     const hooks = settings.hooks;
     if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
         return [];
-    const pre = hooks.PreToolUse;
-    return Array.isArray(pre) ? pre : [];
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
 }
-/** True when every command handler in the entry matches a known peaks sentinel. */
-function entryIsPeaksManaged(entry) {
+/** Read the existing hook array entries from a `settings.hooks` object (already extracted). */
+function readHookEntriesFromHooks(hooks, eventKey) {
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
+}
+/** True when every command handler in the entry matches a known peaks sentinel for the given IDE. */
+function entryIsPeaksManaged(entry, sentinels) {
     const handlers = Array.isArray(entry?.hooks) ? entry.hooks : [];
     if (handlers.length === 0)
         return false;
@@ -118,78 +98,143 @@ function entryIsPeaksManaged(entry) {
         if (typeof h?.command !== 'string')
             return false;
         const cmd = h.command;
-        return PEAKS_HOOK_SENTINELS.some((sentinel) => cmd.includes(sentinel));
+        return sentinels.some((sentinel) => cmd.includes(sentinel));
     });
 }
-function isInstalled(settings) {
-    return readPreToolUse(settings).some(entryIsPeaksManaged);
+/**
+ * Compute the per-IDE peaks hook entries to merge into the settings file.
+ * Replaces the slice #1 hardcoded `PEAKS_HOOK_ENTRIES` constant; the constant
+ * remains exported (computed for claude-code) for backward compat.
+ */
+function resolveHookEntries(ide) {
+    const spec = resolveHookSpec(ide);
+    return [
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent },
+        { sentinel: spec.hookProgressSentinel, matcher: spec.hookProgressMatcher, command: spec.hookProgressCommand, event: spec.hookProgressEvent }
+    ];
+}
+/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. */
+export const PEAKS_HOOK_ENTRIES = (() => {
+    const spec = resolveHookSpec('claude-code');
+    return [
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent },
+        { sentinel: spec.hookProgressSentinel, matcher: spec.hookProgressMatcher, command: spec.hookProgressCommand, event: spec.hookProgressEvent }
+    ];
+})();
+function isInstalledForIde(settings, ide) {
+    const entries = resolveHookEntries(ide);
+    const sentinels = entries.map((e) => e.sentinel);
+    // Check every distinct event key our entries could be on.
+    const eventKeys = new Set(entries.map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        if (readHookEventEntries(settings, eventKey).some((e) => entryIsPeaksManaged(e, sentinels))) {
+            return true;
+        }
+    }
+    return false;
 }
-export function planHookInstall(scope, projectRoot) {
+export function planHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
     const root = resolveSettingsRoot(scope, projectRoot);
-    const settingsPath = resolveSettingsPath(scope, projectRoot);
-    assertSafeSettingsPath(scope, root, settingsPath);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
     const exists = existsSync(settingsPath);
-    const settings = readSettings(settingsPath);
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    const spec = resolveHookSpec(ide);
     return {
         scope,
         settingsPath,
         exists,
-        alreadyInstalled: isInstalled(settings),
-        desiredCommand: HOOK_ENFORCE_COMMAND,
-        sentinel: HOOK_ENFORCE_SENTINEL,
-        matcher: HOOK_GATE_MATCHER
+        alreadyInstalled: isInstalledForIde(settings, ide),
+        desiredCommand: spec.hookEnforceCommand,
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMatcher
     };
 }
-/** Merge all peaks-managed PreToolUse entries into settings, preserving all other keys and hooks. */
-function withHooksInstalled(settings) {
+/** Merge all peaks-managed hook entries into settings, preserving all other keys and hooks. */
+function withHooksInstalledForIde(settings, ide) {
     const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
         ? settings.hooks
         : {};
-    const preToolUse = readPreToolUse(settings);
-    // Drop any existing peaks-managed entries first so re-runs are idempotent
-    // even if the command string changed (e.g. a bug fix in the command).
-    const nonPeaks = preToolUse.filter((entry) => !entryIsPeaksManaged(entry));
-    const ourEntries = PEAKS_HOOK_ENTRIES.map((spec) => ({
-        matcher: spec.matcher,
-        hooks: [{ type: 'command', command: spec.command }]
-    }));
+    // Per-IDE entries may map to different events (Trae: both on beforeToolCall;
+    // Claude: both on PreToolUse). Group by event so each event array is
+    // independently merged.
+    const ourByEvent = new Map();
+    for (const spec of resolveHookEntries(ide)) {
+        const list = ourByEvent.get(spec.event) ?? [];
+        list.push(spec);
+        ourByEvent.set(spec.event, list);
+    }
+    const sentinels = resolveHookEntries(ide).map((e) => e.sentinel);
+    const nextHooks = { ...existingHooks };
+    for (const [eventKey, ourEntries] of ourByEvent) {
+        const existing = readHookEntriesFromHooks(nextHooks, eventKey);
+        const nonPeaks = existing.filter((entry) => !entryIsPeaksManaged(entry, sentinels));
+        const ourFormatted = ourEntries.map((spec) => ({
+            matcher: spec.matcher,
+            hooks: [{ type: 'command', command: spec.command }]
+        }));
+        const merged = [...nonPeaks, ...ourFormatted];
+        if (merged.length > 0) {
+            nextHooks[eventKey] = merged;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
+    }
     return {
         ...settings,
-        hooks: { ...existingHooks, PreToolUse: [...nonPeaks, ...ourEntries] }
+        hooks: nextHooks
     };
 }
-export function applyHookInstall(scope, projectRoot) {
+export function applyHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
     const root = resolveSettingsRoot(scope, projectRoot);
-    const settingsPath = resolveSettingsPath(scope, projectRoot);
-    assertSafeSettingsPath(scope, root, settingsPath);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
     const exists = existsSync(settingsPath);
-    const settings = readSettings(settingsPath);
-    if (isInstalled(settings)) {
-        return { scope, settingsPath, exists, alreadyInstalled: true, desiredCommand: HOOK_ENFORCE_COMMAND, applied: false, sentinel: HOOK_ENFORCE_SENTINEL, matcher: HOOK_GATE_MATCHER };
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    const spec = resolveHookSpec(ide);
+    const baseResult = {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled: isInstalledForIde(settings, ide),
+        desiredCommand: spec.hookEnforceCommand,
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMatcher
+    };
+    if (baseResult.alreadyInstalled) {
+        return { ...baseResult, applied: false };
     }
-    atomicWriteJson(settingsPath, withHooksInstalled(settings));
-    return { scope, settingsPath, exists, alreadyInstalled: false, desiredCommand: HOOK_ENFORCE_COMMAND, applied: true, sentinel: HOOK_ENFORCE_SENTINEL, matcher: HOOK_GATE_MATCHER };
+    atomicWriteJson(settingsPath, withHooksInstalledForIde(settings, ide));
+    return { ...baseResult, alreadyInstalled: false, applied: true };
 }
-export function removeHookInstall(scope, projectRoot) {
+export function removeHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
     const root = resolveSettingsRoot(scope, projectRoot);
-    const settingsPath = resolveSettingsPath(scope, projectRoot);
-    assertSafeSettingsPath(scope, root, settingsPath);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
     if (!existsSync(settingsPath)) {
         return { scope, settingsPath, removed: false };
     }
-    const settings = readSettings(settingsPath);
-    const preToolUse = readPreToolUse(settings);
-    const kept = preToolUse.filter((entry) => !entryIsPeaksManaged(entry));
-    if (kept.length === preToolUse.length) {
-        return { scope, settingsPath, removed: false };
-    }
+    const settings = readJsonObjectFile(settingsPath);
     const existingHooks = settings.hooks ?? {};
+    const sentinels = resolveHookEntries(ide).map((e) => e.sentinel);
+    const eventKeys = new Set(resolveHookEntries(ide).map((e) => e.event));
+    let removedAny = false;
     const nextHooks = { ...existingHooks };
-    if (kept.length > 0) {
-        nextHooks.PreToolUse = kept;
-    }
-    else {
-        delete nextHooks.PreToolUse;
+    for (const eventKey of eventKeys) {
+        const entries = readHookEntriesFromHooks(nextHooks, eventKey);
+        const kept = entries.filter((entry) => !entryIsPeaksManaged(entry, sentinels));
+        if (kept.length !== entries.length)
+            removedAny = true;
+        if (kept.length > 0) {
+            nextHooks[eventKey] = kept;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
     }
     const nextSettings = { ...settings };
     if (Object.keys(nextHooks).length > 0) {
@@ -199,13 +244,14 @@ export function removeHookInstall(scope, projectRoot) {
         delete nextSettings.hooks;
     }
     atomicWriteJson(settingsPath, nextSettings);
-    return { scope, settingsPath, removed: true };
+    return { scope, settingsPath, removed: removedAny };
 }
-export function readHookStatus(scope, projectRoot) {
+export function readHookStatus(scope, projectRoot, options) {
+    const ide = resolveIde(options);
     const root = resolveSettingsRoot(scope, projectRoot);
-    const settingsPath = resolveSettingsPath(scope, projectRoot);
-    assertSafeSettingsPath(scope, root, settingsPath);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
     const exists = existsSync(settingsPath);
-    const settings = exists ? readSettings(settingsPath) : {};
-    return { scope, settingsPath, exists, installed: isInstalled(settings) };
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    return { scope, settingsPath, exists, installed: isInstalledForIde(settings, ide) };
 }

package/dist/src/services/skills/statusline-settings-service.d.ts

@@ -1,13 +1,38 @@
+import { isInsidePath } from '../ide/shared/safe-path.js';
+import type { IdeId } from '../ide/ide-types.js';
 /**
- * Installs (and removes) the Peaks statusLine entry in a Claude Code
- * settings.json. The statusLine renders `peaks statusline` on every turn, giving
- * users an out-of-band, harness-painted signal of which Peaks skill is active —
- * independent of LLM tokens and immune to context compaction.
+ * Installs (and removes) the Peaks statusLine entry in an IDE's settings
+ * file. The settings file location is adapter-driven
+ * (`getAdapter(ide).settings.dirName` + `settingsFileName`) so a future slice
+ * adding a Trae / Cursor / Codex adapter does not need to touch this file.
+ *
+ * Slice #1 only registers claude-code, so the resolved path is still
+ * `<root>/.claude/settings.json` — the same as before the refactor. The
+ * statusLine entry is rendered as `{ type: 'command', command: 'peaks
+ * statusline' }` because that is the shape Claude Code expects; future
+ * adapters may need a different entry shape (e.g. Cursor's `statusBar`
+ * field) and would override this in their adapter.
+ *
+ * Slice #3 refactor (this commit): the service is now per-IDE aware via an
+ * optional `options.ide` parameter. The CLI command is responsible for
+ * resolving the IDE (env → stdin shape → cwd → fallback to 'claude-code')
+ * via `detectIdeFromContext` and passing the result here. When `ide` is
+ * omitted, the service defaults to `'claude-code'` so existing tests and
+ * downstream callers continue to work without modification.
  *
  * Writes preserve all other settings keys, reject symlinked targets, and use an
  * atomic rename so a partial write can never corrupt an existing settings file.
  */
 export type StatusLineScope = 'project' | 'global';
+export type StatusLineSettingsOptions = {
+    /**
+     * Which IDE's adapter to install for. Defaults to `'claude-code'` for
+     * backward compatibility. The CLI command should resolve this from
+     * `detectIdeFromContext({ env, cwd, parsedStdin })` and pass the result.
+     * Throws if the IDE is not registered in the adapter registry.
+     */
+    readonly ide?: IdeId;
+};
 export type StatusLineSettingsPlan = {
     scope: StatusLineScope;
     settingsPath: string;
@@ -21,11 +46,13 @@ export type StatusLineSettingsResult = StatusLineSettingsPlan & {
     applied: boolean;
 };
 export declare const STATUSLINE_COMMAND = "peaks statusline";
-export declare function planStatusLineInstall(scope: StatusLineScope, projectRoot?: string): StatusLineSettingsPlan;
+export { isInsidePath };
+export declare function planStatusLineInstall(scope: StatusLineScope, projectRoot?: string, options?: StatusLineSettingsOptions): StatusLineSettingsPlan;
 export declare function applyStatusLineInstall(scope: StatusLineScope, projectRoot?: string, options?: {
     force?: boolean;
+    ide?: IdeId;
 }): StatusLineSettingsResult;
-export declare function removeStatusLineInstall(scope: StatusLineScope, projectRoot?: string): {
+export declare function removeStatusLineInstall(scope: StatusLineScope, projectRoot?: string, options?: StatusLineSettingsOptions): {
     scope: StatusLineScope;
     settingsPath: string;
     removed: boolean;