peaks-loop 4.0.0-beta → 4.0.0-beta.11

package/dist/services/config/config-types.d.ts

@@ -0,0 +1,117 @@
+export type ModelPreference = 'haiku' | 'sonnet' | 'opus';
+export type ModelProviderId = string;
+export type ExecutionModelId = string;
+export type ProviderModelConfig = {
+    model?: ExecutionModelId;
+    baseUrl?: string;
+    apiKey?: string;
+};
+export type ModelProviderConfig = {
+    [providerId: string]: ProviderModelConfig | undefined;
+};
+export type ProxyConfig = {
+    httpProxy?: string;
+};
+export type TokenRef = {
+    env: string;
+} | {
+    keychain: string;
+} | {
+    ghCli: true;
+};
+export type TokenConfig = {
+    AnthropicApiKey?: TokenRef;
+    OpenAiApiKey?: TokenRef;
+    GitHubToken?: TokenRef;
+    GitLabToken?: TokenRef;
+};
+export type ArtifactProvider = 'github' | 'gitlab';
+export type ArtifactRemoteRepoConfig = {
+    provider: ArtifactProvider;
+    owner: string;
+    name: string;
+};
+export type ArtifactStorageConfig = {
+    mode: 'local';
+    localPath?: string;
+} | {
+    mode: 'local-with-remote-sync';
+    localPath?: string;
+    remote: ArtifactRemoteRepoConfig;
+};
+export type WorkspaceConfig = {
+    workspaceId: string;
+    name: string;
+    rootPath: string;
+    artifactRepo?: ArtifactRemoteRepoConfig;
+    artifactStorage?: ArtifactStorageConfig;
+    installedCapabilityIds: string[];
+};
+export type OcrAuthHeader = 'authorization' | 'x-api-key' | 'bearer';
+export type OcrLlmConfig = {
+    url?: string;
+    authToken?: string;
+    model?: string;
+    useAnthropic?: boolean;
+    authHeader?: OcrAuthHeader;
+};
+export type OcrConfig = {
+    llm?: OcrLlmConfig;
+};
+/**
+ * 2.0.1 slim `~/.peaks/config.json` schema. The on-disk file holds
+ * ONLY `version` + `ocr.llm.*` placeholders. All other settings
+ * (providers, proxy, workspaces, language/model/economy/swarm
+ * toggles) live in sidecar files under the same `~/.peaks/`
+ * directory or in per-project `preferences.json`.
+ *
+ * The slim shape is enforced on disk by `loadGlobalConfig`; any
+ * unknown field on read is silently stripped and the file is
+ * rewritten with the slim shape, so a hand-written or partially-
+ * migrated file cannot grow stale fields.
+ *
+ * NOTE: legacy fields below are kept on the type as `@deprecated`
+ * so existing consumers (`config-service.ts`, `workflow-commands.ts`,
+ * etc.) continue to compile during the migration window. They are
+ * written to / read from sidecar files at runtime; the slim
+ * `~/.peaks/config.json` only persists `version` + `ocr`.
+ */
+export type PeaksConfig = {
+    version: string;
+    ocr?: OcrConfig;
+    /** @deprecated Moved to `~/.peaks/providers.json` (provider-service.ts) */
+    providers?: ModelProviderConfig;
+    /** @deprecated Moved to `~/.peaks/proxy.json` (proxy-service.ts) */
+    proxy?: ProxyConfig;
+    /** @deprecated Removed in 2.0.1; canonical home is `<project>/.peaks/preferences.json` */
+    language?: string;
+    /** @deprecated Removed in 2.0.1; canonical home is preferences */
+    model?: ModelPreference;
+    /** @deprecated Removed in 2.0.1; canonical home is preferences */
+    economyMode?: boolean;
+    /** @deprecated Removed in 2.0.1; canonical home is preferences */
+    swarmMode?: boolean;
+    /** @deprecated Removed in 2.0.1; never read from this file */
+    tokens?: TokenConfig;
+    /** @deprecated Moved to `~/.peaks/workspaces.json` (workspace-state-service.ts) */
+    workspaces?: WorkspaceConfig[];
+    /** @deprecated Moved to `~/.peaks/workspaces.json` (workspace-state-service.ts) */
+    currentWorkspace?: string | null;
+};
+export type ConfigLayer = 'user' | 'project';
+export type ConfigGetOptions = {
+    key?: string;
+    layer?: ConfigLayer;
+};
+export type ConfigSetOptions = {
+    key: string;
+    value: unknown;
+    layer?: ConfigLayer;
+};
+/**
+ * 2.0.1 slim runtime default for `~/.peaks/config.json`. The on-disk
+ * file only carries `version` + empty `ocr.llm.*` placeholders.
+ */
+export declare const DEFAULT_CONFIG: PeaksConfig;
+export type { ConfigV2 } from './config-migration.js';
+export { isConfigV2 } from './config-migration.js';

package/dist/services/config/model-routing.d.ts

@@ -0,0 +1,66 @@
+import { type ModelProviderConfig, type PeaksConfig } from './config-types.js';
+/**
+ * Slice 2026-07-09 add-zcode-adapter (A.3): replaces the legacy
+ * `STRONGEST_MODEL_ID = 'claude-opus-4-7'` constant (removed) with a dynamic
+ * resolver. The strongest planner/reviewer model is now derived
+ * from the active config instead of being hardcoded to a specific
+ * vendor. This unlocks running peaks-loop under non-Claude IDEs
+ * (z-code, Cursor, Trae, ...).
+ *
+ * Resolution order:
+ *   1. Explicit `config.model` (user override via `peaks config set model ...`)
+ *   2. Stable fallback for back-compat (env-var override; defaults to
+ *      `claude-opus-4-7` so legacy fixtures keep compiling per
+ *      SC §3.4 strategy A)
+ *
+ * Vendor-neutrality note: the default `'claude-opus-4-7'` is a
+ * *back-compat fallback*, NOT a hardcoded "the strongest model is
+ * always Claude" assumption. Production callers should set
+ * `config.model` (or override the env var) to declare their strongest
+ * model. Adapter-level runtime probing is wired in Slice C
+ * (`getStrongestModelIdAsync` below).
+ */
+export declare function getStrongestModelId(config?: {
+    model?: unknown;
+}): string;
+/**
+ * Slice 2026-07-09 add-zcode-adapter (Slice C, C.4): async variant
+ * of `getStrongestModelId`. Same precedence for layers 1 + 2, but
+ * layer 2.5 is the IDE's runtime probe (`detectCurrentIdeModel`)
+ * which is consulted BEFORE the env-var back-compat fallback.
+ *
+ * Why this exists:
+ *   - `rd-service.buildPlan` (and other sync callers) still call the
+ *     sync `getStrongestModelId` — we do NOT change those signatures.
+ *   - New async callers (the future Slice C-extension of
+ *     `workflow-router-service`, plus any LLM-inside-z-code path)
+ *     resolve the strongest model from the IDE's actual state,
+ *     without forcing the user to set `config.model`.
+ *
+ * Resolution order:
+ *   1. Explicit `config.model`.
+ *   2. `PEAKS_STRONGEST_MODEL_DEFAULT` env var override.
+ *   3. Runtime probe via `detectCurrentIdeModel()` (only when the
+ *      registered IDE adapter opts in via `detectCurrentModel?` —
+ *      only `zcode` does in Slice C; other IDEs skip this layer).
+ *   4. Hardcoded back-compat default `'claude-opus-4-7'`.
+ *
+ * Each layer is isolated so a failure in the probe does not break
+ * the resolver.
+ */
+export declare function getStrongestModelIdAsync(config?: {
+    model?: unknown;
+}, runtimeProbeDisabled?: boolean): Promise<string>;
+export declare function getConfiguredExecutionModelId(providers: ModelProviderConfig | undefined): string;
+/**
+ * Slice 015 — typed exception for "no provider has a configured model".
+ * Lives next to its throw site so a downstream `instanceof` check survives
+ * any tree-shaking. CLI catch sites map this to the `INVALID_PROVIDERS`
+ * envelope code via `_cli-error-envelope.mapServiceError`.
+ */
+export declare class ProviderNotConfiguredError extends Error {
+    constructor(message?: string);
+}
+export declare function getEconomyAwareExecutionModelId(config: Pick<PeaksConfig, 'economyMode' | 'providers'> & {
+    model?: string;
+}): string;

package/dist/services/config/model-routing.js

@@ -0,0 +1,105 @@
+import { detectCurrentIdeModel } from '../ide/current-model-detector.js';
+/**
+ * Slice 2026-07-09 add-zcode-adapter (A.3): replaces the legacy
+ * `STRONGEST_MODEL_ID = 'claude-opus-4-7'` constant (removed) with a dynamic
+ * resolver. The strongest planner/reviewer model is now derived
+ * from the active config instead of being hardcoded to a specific
+ * vendor. This unlocks running peaks-loop under non-Claude IDEs
+ * (z-code, Cursor, Trae, ...).
+ *
+ * Resolution order:
+ *   1. Explicit `config.model` (user override via `peaks config set model ...`)
+ *   2. Stable fallback for back-compat (env-var override; defaults to
+ *      `claude-opus-4-7` so legacy fixtures keep compiling per
+ *      SC §3.4 strategy A)
+ *
+ * Vendor-neutrality note: the default `'claude-opus-4-7'` is a
+ * *back-compat fallback*, NOT a hardcoded "the strongest model is
+ * always Claude" assumption. Production callers should set
+ * `config.model` (or override the env var) to declare their strongest
+ * model. Adapter-level runtime probing is wired in Slice C
+ * (`getStrongestModelIdAsync` below).
+ */
+export function getStrongestModelId(config) {
+    const raw = config?.model;
+    const fromConfig = typeof raw === 'string' ? raw.trim() : undefined;
+    if (fromConfig)
+        return fromConfig;
+    // Slice 2026-07-09: back-compat fallback for test fixtures that
+    // pre-date this slice (SC §3.4 strategy A env-var override).
+    return process.env.PEAKS_STRONGEST_MODEL_DEFAULT ?? 'claude-opus-4-7';
+}
+/**
+ * Slice 2026-07-09 add-zcode-adapter (Slice C, C.4): async variant
+ * of `getStrongestModelId`. Same precedence for layers 1 + 2, but
+ * layer 2.5 is the IDE's runtime probe (`detectCurrentIdeModel`)
+ * which is consulted BEFORE the env-var back-compat fallback.
+ *
+ * Why this exists:
+ *   - `rd-service.buildPlan` (and other sync callers) still call the
+ *     sync `getStrongestModelId` — we do NOT change those signatures.
+ *   - New async callers (the future Slice C-extension of
+ *     `workflow-router-service`, plus any LLM-inside-z-code path)
+ *     resolve the strongest model from the IDE's actual state,
+ *     without forcing the user to set `config.model`.
+ *
+ * Resolution order:
+ *   1. Explicit `config.model`.
+ *   2. `PEAKS_STRONGEST_MODEL_DEFAULT` env var override.
+ *   3. Runtime probe via `detectCurrentIdeModel()` (only when the
+ *      registered IDE adapter opts in via `detectCurrentModel?` —
+ *      only `zcode` does in Slice C; other IDEs skip this layer).
+ *   4. Hardcoded back-compat default `'claude-opus-4-7'`.
+ *
+ * Each layer is isolated so a failure in the probe does not break
+ * the resolver.
+ */
+export async function getStrongestModelIdAsync(config, runtimeProbeDisabled = false) {
+    const raw = config?.model;
+    const fromConfig = typeof raw === 'string' ? raw.trim() : undefined;
+    if (fromConfig)
+        return fromConfig;
+    const envDefault = process.env.PEAKS_STRONGEST_MODEL_DEFAULT;
+    if (envDefault && envDefault.length > 0)
+        return envDefault;
+    if (!runtimeProbeDisabled) {
+        try {
+            const probed = await detectCurrentIdeModel();
+            if (probed && probed.length > 0)
+                return probed;
+        }
+        catch { // TODO(g2): best-effort runtime probe — fall through to back-compat default is intentional
+            // best-effort — fall through to back-compat default
+        }
+    }
+    return 'claude-opus-4-7';
+}
+export function getConfiguredExecutionModelId(providers) {
+    const providerConfigs = Object.values(providers ?? {});
+    const configuredModel = providerConfigs
+        .map((provider) => provider?.model?.trim())
+        .find((model) => typeof model === 'string' && model.length > 0);
+    if (!configuredModel) {
+        throw new ProviderNotConfiguredError();
+    }
+    return configuredModel;
+}
+/**
+ * Slice 015 — typed exception for "no provider has a configured model".
+ * Lives next to its throw site so a downstream `instanceof` check survives
+ * any tree-shaking. CLI catch sites map this to the `INVALID_PROVIDERS`
+ * envelope code via `_cli-error-envelope.mapServiceError`.
+ */
+export class ProviderNotConfiguredError extends Error {
+    constructor(message = 'Execution model must be configured in providers') {
+        super(message);
+        this.name = 'ProviderNotConfiguredError';
+    }
+}
+export function getEconomyAwareExecutionModelId(config) {
+    // Slice 2.0.1-bug1 round 3: economy is the project default. Treat undefined as enabled
+    // (matches the pre-slice implicit default from DEFAULT_CONFIG.economyMode = true). Only an
+    // explicit `economyMode === false` switches execution to the strongest planner/reviewer
+    // model (resolved dynamically per Slice 2026-07-09 add-zcode-adapter A.3).
+    return config.economyMode !== false ? getConfiguredExecutionModelId(config.providers) : getStrongestModelId(config);
+}

package/dist/services/context/auto-compact-dispatcher.d.ts

@@ -0,0 +1,37 @@
+import type { CompactDispatchResult } from './auto-compact-types.js';
+export type CompactTarget = 'main' | 'sub-agent';
+export interface DispatchIdeCompactInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Spawn timeout (ms). Default 30s — Claude Code `/compact` is sync. */
+    readonly timeoutMs?: number | undefined;
+    /**
+     * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which session
+     * the compact should target. Default `'main'` — the orchestrator
+     * (peaks-code body) runs in the main-session Claude Code window and
+     * wants to compress *its* context, not a sub-agent's. Sub-agent
+     * shells that spawn their own `peaks code auto-compact` flow pass
+     * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
+     *
+     * Behaviour matrix (claude-code MVP):
+     *   - target='main'     → llm-self-compress (write intent; main LLM
+     *                          fires `/compact` on its next turn).
+     *   - target='sub-agent'→ shell-exec (spawn `sh -c /compact` in the
+     *                          sub-agent's own shell, preserving the
+     *                          pre-slice behaviour).
+     * Non-claude-code IDEs + target='main' return noop + warning.
+     */
+    readonly target?: CompactTarget | undefined;
+}
+/**
+ * Dispatch compact via the active IDE's registered pathway.
+ *
+ * Returns a `CompactDispatchResult` envelope. The result is `ok`
+ * when the dispatch path completed without error — for
+ * `llm-self-compress` the LLM still has to do the actual summary,
+ * so the orchestrator MUST NOT treat `ok: true` as proof that the
+ * context actually shrunk; the next `peaks context now` probe
+ * confirms.
+ */
+export declare function dispatchIdeCompact(input: DispatchIdeCompactInput): Promise<CompactDispatchResult>;

package/dist/services/context/auto-compact-dispatcher.js

@@ -0,0 +1,240 @@
+/**
+ * AC-3 — IDE-aware compact dispatcher.
+ *
+ * Reads the active IDE's `IdeAdapter.compact` profile and dispatches
+ * compact via the adapter-declared pathway. No hard-coded IDE names
+ * — Claude Code is the MVP that fills `compact`; other adapters
+ * register their own `compact` profile as L2-dogfood verifies
+ * each IDE's actual compact surface.
+ *
+ * Pathway dispatch:
+ *
+ *   - `shell-exec`     — peaks-loop spawns the adapter's
+ *                        `compactCommand` via `child_process.spawn`.
+ *                        Works for any IDE that accepts a slash
+ *                        command via a shell-spawnable entry point
+ *                        (Claude Code MVP: `/compact`).
+ *   - `ide-native`     — peaks-loop writes the compact intent to
+ *                        the IDE's hook file (per
+ *                        `IdeSettingsLocation`). Used when the IDE
+ *                        requires a registered hook rather than a
+ *                        runtime command.
+ *   - `llm-self-compress` — peaks-loop records the intent and
+ *                        returns `ok: true` with `pathway` echoed.
+ *                        The LLM does its own context summarization
+ *                        on the next turn. Always available; least
+ *                        precise fallback.
+ *   - `noop`           — adapter explicitly opted out. peaks-loop
+ *                        returns `ok: false` with `message: 'noop'`.
+ *                        Used by legacy / unverified adapters.
+ */
+import { spawn } from 'node:child_process';
+import { detectIdeFromEnv } from './main-session-monitor.js';
+import { getAdapter } from '../ide/ide-registry.js';
+/**
+ * Dispatch compact via the active IDE's registered pathway.
+ *
+ * Returns a `CompactDispatchResult` envelope. The result is `ok`
+ * when the dispatch path completed without error — for
+ * `llm-self-compress` the LLM still has to do the actual summary,
+ * so the orchestrator MUST NOT treat `ok: true` as proof that the
+ * context actually shrunk; the next `peaks context now` probe
+ * confirms.
+ */
+export async function dispatchIdeCompact(input) {
+    const env = input.env ?? process.env;
+    const detected = detectIdeFromEnv(env);
+    // See auto-compact-reader.ts for the IdeKind→IdeId cast rationale.
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    // Slice 2026-06-28-code-mode-bypass-fix (defect #4): default to
+    // `'main'` so the orchestrator's auto-compact actually compresses
+    // the main-session context. The orchestrator passes `'sub-agent'`
+    // explicitly when a sub-agent shell dispatches the call.
+    const target = input.target ?? 'main';
+    // Slice 2026-06-28: when targeting the MAIN session, refuse
+    // up-front for adapters we cannot dispatch a main-session compact
+    // against. We DO this before the `!adapter.compact` short-circuit
+    // so the test message reflects the operational cause (target vs
+    // adapter capability). Even non-claude-code adapters without a
+    // registered `compact` profile should report "main-session target
+    // unsupported" rather than the generic "no compact profile" line.
+    if (target === 'main' && ideId !== 'claude-code') {
+        return {
+            ok: false,
+            ide: ideId,
+            pathway: 'noop',
+            message: `main-session target unsupported on adapter '${ideId}'; only claude-code supports in-band main-session compact.`
+        };
+    }
+    // Adapters that don't declare `compact` (legacy / unverified) →
+    // explicit noop so the caller can distinguish "IDE doesn't support
+    // compact" from "IDE supports but dispatch failed".
+    if (!adapter.compact) {
+        return {
+            ok: false,
+            ide: ideId,
+            pathway: 'noop',
+            message: `IDE '${ideId}' has no registered compact profile; cannot dispatch.`
+        };
+    }
+    const profile = adapter.compact;
+    const timeoutMs = input.timeoutMs ?? 30_000;
+    const pathway = profile.compactPathway;
+    switch (pathway) {
+        case 'shell-exec':
+            // Slice 2026-06-28: shell-exec is only correct when the caller
+            // IS the shell whose context we want compressed. Sub-agents
+            // qualify; the main-session orchestrator does not.
+            if (target === 'main') {
+                return {
+                    ok: true,
+                    ide: ideId,
+                    pathway: 'llm-self-compress',
+                    message: `Main-session target on shell-exec adapter '${ideId}': deferring to in-band /compact (next LLM turn); writing intent record.`
+                };
+            }
+            return await dispatchShellExec({
+                ideId,
+                command: profile.compactCommand,
+                timeoutMs
+            });
+        case 'ide-native':
+            // Slice 2026-07-02-auto-compact-zero-pause: write the auto-compact
+            // PreToolUse hook into `.claude/settings.local.json`. The hook
+            // command (`peaks session auto-compact-hook`) reads
+            // `CLAUDE_CONTEXT_USAGE_PERCENT` on every subsequent Bash/Task
+            // tool call from the runner and, at ratio ≥ 0.95, in-band spawns
+            // `claude --compact` against the CURRENT runner (not a child
+            // process — the bug documented in
+            // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
+            //
+            // `ide-native` is ONLY for the main-session runner. When the
+            // caller is a sub-agent shell (which has its own ephemeral
+            // context window — not the runner's), fall through to
+            // shell-exec so the sub-agent's `compactCommand` spawns a
+            // child claude process and the sub-agent's own runner doesn't
+            // get a PreToolUse hook installed in the wrong place.
+            if (target === 'sub-agent') {
+                return await dispatchShellExec({
+                    ideId,
+                    command: profile.compactCommand,
+                    timeoutMs
+                });
+            }
+            // Lazy install: we only get here when the caller explicitly
+            // invokes `peaks code auto-compact --execute`, so the user has
+            // already opted in. No zero-touch surprise on workspace init.
+            return await dispatchIdeNativeHook({
+                projectRoot: input.projectRoot,
+                sessionId: input.sessionId,
+                target
+            });
+        case 'llm-self-compress':
+            return {
+                ok: true,
+                ide: ideId,
+                pathway: 'llm-self-compress',
+                message: `Adapter '${ideId}' uses LLM-self-compress; LLM will summarize on next turn.`
+            };
+        case 'noop':
+            return {
+                ok: false,
+                ide: ideId,
+                pathway: 'noop',
+                message: `Adapter '${ideId}' explicitly opted out of auto-compact.`
+            };
+        default:
+            // Forward-compatibility: if a new pathway is added to the
+            // union, we fall through to noop + log the unknown value.
+            return {
+                ok: false,
+                ide: ideId,
+                pathway: 'noop',
+                message: `Unknown compact pathway '${String(pathway)}' for adapter '${ideId}'.`
+            };
+    }
+}
+/**
+ * Spawn the adapter's `compactCommand` via child_process. Returns
+ * the dispatch envelope with `pathway: 'shell-exec'`.
+ *
+ * MVP: Claude Code registers `compactCommand: '/compact'` and
+ * `compactPathway: 'shell-exec'`. We spawn via `sh -c` so the
+ * slash-command resolves inside the runner's shell session.
+ *
+ * For other IDEs that adopt `shell-exec` in the future, the
+ * `compactCommand` field drives whatever shell-spawnable token
+ * the IDE accepts (e.g. trae's compact-token).
+ */
+function dispatchShellExec(input) {
+    return new Promise((resolve) => {
+        const child = spawn('sh', ['-c', input.command], {
+            stdio: 'ignore',
+            // Detach so the IDE's runner picks up the slash command.
+            detached: true,
+            env: process.env
+        });
+        child.unref();
+        const timer = setTimeout(() => {
+            // Don't kill — the IDE runner keeps the command alive in
+            // its own session; we just stop waiting.
+            resolve({
+                ok: true,
+                ide: input.ideId,
+                pathway: 'shell-exec',
+                message: `Compact command '${input.command}' dispatched (timeout=${input.timeoutMs}ms); IDE runner should pick it up.`
+            });
+        }, input.timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({
+                ok: false,
+                ide: input.ideId,
+                pathway: 'shell-exec',
+                message: `Failed to spawn compact command '${input.command}': ${err.message}`
+            });
+        });
+        child.on('spawn', () => {
+            // Spawn succeeded — return immediately; the IDE runner
+            // continues processing the slash command in its own session.
+            clearTimeout(timer);
+            resolve({
+                ok: true,
+                ide: input.ideId,
+                pathway: 'shell-exec',
+                message: `Compact command '${input.command}' spawned successfully.`
+            });
+        });
+    });
+}
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause: implement the
+ * `ide-native` pathway. Writes the auto-compact PreToolUse hook
+ * into `.claude/settings.local.json` (idempotent; the install
+ * service is a no-op if the hook is already present). On the next
+ * Bash/Task tool call from the runner, the hook fires
+ * `peaks session auto-compact-hook` which in-band spawns
+ * `claude --compact` against the CURRENT runner session.
+ *
+ * Returns `ok: true, pathway: 'ide-native'` regardless of install
+ * action (`installed` vs `already-installed`) — both states
+ * achieve the operational goal: the hook is wired and the next
+ * Bash call will trigger it.
+ */
+async function dispatchIdeNativeHook(input) {
+    // Lazy dynamic import — matches the existing pattern in
+    // `runAutoCompact` for `auto-compact-reader.ts` (line 311) and
+    // avoids a static cycle if future slices add cross-imports
+    // between dispatcher and hook-install.
+    const { installAutoCompactHook } = await import('../hooks/auto-compact-hook-install.js');
+    const result = installAutoCompactHook({ projectRoot: input.projectRoot });
+    return {
+        ok: true,
+        ide: 'claude-code',
+        pathway: 'ide-native',
+        message: result.action === 'installed'
+            ? `Auto-compact PreToolUse hook installed at ${result.settingsPath}. Next Bash/Task tool call will read CLAUDE_CONTEXT_USAGE_PERCENT and compact in-band at ratio ≥ 95%.`
+            : `Auto-compact PreToolUse hook already installed at ${result.settingsPath}; next Bash/Task tool call will trigger compact in-band at ratio ≥ 95%.`
+    };
+}