peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

package/dist/cli/commands/gate-commands.js

@@ -0,0 +1,117 @@
+import { enforceBashCommand, recordGateBypass, GateBypassError } from '../../services/sop/gate-enforce-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { detectIdeFromContext, parseClaudeShapeStdin } from '../../services/ide/hook-translator.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { emitBlock, emitHint } from '../../services/hooks/output.js';
+/**
+ * Read the PreToolUse hook payload. `PEAKS_HOOK_STDIN` is a test seam; production
+ * reads stdin. The CLI-side stdin reader is intentionally kept here (not in
+ * `hook-translator.ts`) because it owns the `process.stdin` lifecycle and the
+ * test-seam env var. The translator operates on already-parsed payloads.
+ */
+async function readHookPayload() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    if (override !== undefined) {
+        return override;
+    }
+    if (process.stdin.isTTY) {
+        return '';
+    }
+    return new Promise((resolveStdin) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolveStdin(data));
+        process.stdin.on('error', () => resolveStdin(data));
+    });
+}
+export function registerGateCommands(program, io) {
+    const gate = program.command('gate').description('SOP gate enforcement (PreToolUse hook handler and bypass)');
+    addJsonOption(gate
+        .command('enforce')
+        .description('PreToolUse hook handler: deny a Bash command guarded by an unsatisfied SOP gate')
+        .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')).action(async (options) => {
+        // Trust red line: this runs on (potentially) every Bash call. Any failure to
+        // decide must FAIL-OPEN (allow), never block the user's Claude Code.
+        try {
+            const raw = await readHookPayload();
+            let parsedStdin = null;
+            if (raw.trim().length > 0) {
+                try {
+                    parsedStdin = JSON.parse(raw);
+                }
+                catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    // Malformed JSON — fail-open. Detect + parse on null fall back to the
+                    // default adapter and yield empty tool/command, which short-circuits
+                    // to the "not a guarded surface" early exit below.
+                }
+            }
+            const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin });
+            const adapter = getAdapter(ide);
+            // For slice #1 only the Claude adapter is registered, so the parser is
+            // Claude-shaped. Future slices dispatch on `ide` to pick a per-adapter
+            // parser; the parser entry-point (`parseXxxShapeStdin`) is the only
+            // change required.
+            const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
+            if (toolName !== adapter.toolMatcher || typeof command !== 'string' || command.trim().length === 0) {
+                // Not a guarded surface — allow (no output = normal permission flow).
+                if (options.json === true) {
+                    printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
+                }
+                return;
+            }
+            const decision = await enforceBashCommand(options.project, command);
+            if (decision.decision === 'deny') {
+                // PRD#2 (2026-06-16-fact-forcing-gate-format): a true SOP gate failure is
+                // a HARD block. emitBlock writes the Claude Code permissionDecision:"deny"
+                // JSON to stdout (the hook's decision signal), sets process.exitCode = 2
+                // (Claude Code's block exit code), AND surfaces the reason to stderr so
+                // the LLM sees it on the next turn. This prevents the previous behaviour
+                // where Claude Code wrapped the output as "PreToolUse:Bash hook error".
+                emitBlock(io, decision.reason);
+                if (options.json === true) {
+                    emitHint(io, JSON.stringify(ok('gate.enforce', decision)));
+                }
+                return;
+            }
+            if (decision.warnings && decision.warnings.length > 0) {
+                for (const warning of decision.warnings) {
+                    emitHint(io, warning);
+                }
+            }
+            if (options.json === true) {
+                emitHint(io, JSON.stringify(ok('gate.enforce', decision)));
+            }
+            // allow: emit nothing on stdout → normal permission flow.
+        }
+        catch (error) {
+            // Fail-open: a bug in enforcement must not brick Claude Code.
+            emitHint(io, `gate enforce: internal error, allowing command (${getErrorMessage(error)})`);
+        }
+    });
+    addJsonOption(gate
+        .command('bypass')
+        .description('Record a one-shot bypass so the next guarded Bash command is allowed once')
+        .requiredOption('--sop <id>', 'SOP id whose guard to bypass')
+        .requiredOption('--phase <phase>', 'phase whose gate to bypass')
+        .requiredOption('--reason <text>', 'justification recorded for the bypass')
+        .option('--project <path>', 'project whose run-state holds the token (default: current directory)', '.')).action((options) => {
+        try {
+            if (options.reason.trim().length === 0) {
+                printResult(io, fail('gate.bypass', 'BYPASS_REASON_REQUIRED', '--reason must not be empty', { sop: options.sop, phase: options.phase }, ['Provide --reason "<why>"']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = recordGateBypass(options.project, options.sop, options.phase, options.reason);
+            printResult(io, ok('gate.bypass', { sop: options.sop, phase: options.phase, count: result.count }, [], ['The next guarded Bash command for this transition will be allowed once']), options.json);
+        }
+        catch (error) {
+            const code = error instanceof GateBypassError ? error.code : 'GATE_BYPASS_FAILED';
+            printResult(io, fail('gate.bypass', code, getErrorMessage(error), { sop: options.sop, phase: options.phase }, ['Satisfy the gate instead of bypassing']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/heartbeat-commands.js

@@ -0,0 +1,135 @@
+/**
+ * `peaks sub-agent heartbeat` — G6: append a heartbeat to a dispatch record.
+ *
+ * Pulled out of `sub-agent-commands.ts` (slice 2026-06-23-audit-p0-split)
+ * to honor the 800-line file cap. The heartbeat is fire-and-forget; the
+ * parent Dispatcher polls the record during the batch-sync wait and
+ * renders a status line. Sub-agents should call this at least every
+ * 30s (configurable via SKILL.md heartbeatIntervalSec).
+ *
+ * R-2 path guard: `assertSafeDispatchRecordPath` ensures the record
+ * lives under `.peaks/_sub_agents/` so a malicious `--record` arg can't
+ * point at a sensitive file outside the runtime tree.
+ */
+import { existsSync } from 'node:fs';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { appendHeartbeat } from '../../services/dispatch/dispatch-record-writer.js';
+import { assertSafeDispatchRecordPath } from '../../services/security/safe-settings-path.js';
+import { writeLogEntry } from '../../services/log/logger.js';
+import { HEARTBEAT_STATUSES } from './sub-agent-shared.js';
+export function registerHeartbeatCommand(parent, io) {
+    addJsonOption(parent
+        .command('heartbeat')
+        .description('Append a heartbeat entry to a dispatch record. Fire-and-forget: ' +
+        'the parent Dispatcher polls this record during the batch-sync ' +
+        'wait and renders a status line. Sub-agents should call this at ' +
+        'least every 30s (configurable via SKILL.md heartbeatIntervalSec).')
+        .requiredOption('--record <path>', 'absolute path to a dispatch record JSON')
+        .requiredOption('--status <state>', 'queued | running | finalizing | done | failed | stale')
+        .requiredOption('--progress <pct>', 'integer 0-100')
+        .option('--note <text>', 'free-form progress note (≤ 200 chars)')
+        .option('--project <path>', 'trusted project root (defaults to cwd); used for the R-2 path guard so a malicious --record cannot point at another project\'s dispatch record')).action((options) => {
+        const asJson = options.json === true;
+        if (!options.record || !existsSync(options.record)) {
+            printResult(io, fail('sub-agent.heartbeat', 'INVALID_RECORD_PATH', `record not found: ${options.record ?? '(empty)'}`, { recordPath: options.record ?? null, truncated: false }, [
+                'Pass the absolute path from the `peaks sub-agent dispatch` envelope.'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        if (!HEARTBEAT_STATUSES.includes(options.status)) {
+            printResult(io, fail('sub-agent.heartbeat', 'INVALID_STATUS', `--status must be one of ${HEARTBEAT_STATUSES.join(' | ')} (got ${options.status})`, { recordPath: options.record, truncated: false }, [
+                'Use one of the documented statuses; poller compares lastBeatAt against now() - 5min to set `stale`.'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const progress = Number.parseInt(options.progress ?? 'NaN', 10);
+        if (!Number.isInteger(progress) || progress < 0 || progress > 100) {
+            printResult(io, fail('sub-agent.heartbeat', 'INVALID_PROGRESS', `--progress must be integer 0-100 (got ${options.progress})`, { recordPath: options.record, truncated: false }, [
+                'Use 0..100 inclusive.'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        if (options.note !== undefined && options.note.length > 200) {
+            printResult(io, fail('sub-agent.heartbeat', 'NOTE_TOO_LONG', `--note must be ≤ 200 chars (got ${options.note.length})`, { recordPath: options.record, truncated: false }, [
+                'Shorten the note; the record file is not a log file.'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            // R-2 guard (slice 2026-06-23-audit-3rd): trust --project or process.cwd(),
+            // NOT the --record path. deriveProjectRoot(recordPath) walked the path
+            // itself, which let an attacker point --record at any other project's
+            // .peaks/_sub_agents/ tree and slip past the guard. The relative()
+            // backstop still applies — the record must live under the trusted
+            // root's .peaks/_sub_agents/ subdir.
+            const trustedRoot = options.project ?? process.cwd();
+            assertSafeDispatchRecordPath(options.record, trustedRoot);
+            const result = appendHeartbeat({
+                recordPath: options.record,
+                status: options.status,
+                progress,
+                ...(options.note !== undefined ? { note: options.note } : {})
+            });
+            printResult(io, ok('sub-agent.heartbeat', {
+                // Slice 2026-06-23-audit-4th #E1: envelopeVersion marker
+                envelopeVersion: '2.1.0',
+                recordPath: options.record,
+                heartbeatCount: result.record.heartbeats.length,
+                lastBeatAt: result.record.lastBeatAt,
+                status: result.record.status,
+                truncated: result.truncated
+            }, [], ['Continue business logic; heartbeat is fire-and-forget.']), asJson);
+            // Slice 2026-06-23-audit-4th #B1: structured log on success.
+            try {
+                writeLogEntry({
+                    ts: new Date().toISOString(),
+                    level: 'info',
+                    command: 'sub-agent.heartbeat',
+                    msg: 'heartbeat',
+                    batchId: result.record.batchId,
+                    data: {
+                        recordPath: options.record,
+                        status: result.record.status,
+                        heartbeatCount: result.record.heartbeats.length,
+                        truncated: result.truncated
+                    }
+                });
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                /* best-effort */
+            }
+        }
+        catch (error) {
+            const code = error.code ?? 'HEARTBEAT_ERROR';
+            printResult(io, fail('sub-agent.heartbeat', code, getErrorMessage(error), { recordPath: options.record ?? null, truncated: false }, [
+                heartbeatErrorNextActions(code)
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+}
+/**
+ * Slice 2026-06-23-audit-3rd #9: branch nextActions on `error.code` so
+ * the LLM-side runner gets a specific hint instead of the generic
+ * "see error message" fallback.
+ */
+function heartbeatErrorNextActions(code) {
+    if (code === 'LOCK_TIMEOUT') {
+        return 'A concurrent writer (markCompleted or another heartbeat) holds the record lock for >5s; retry, or check for a crashed holder (the .lock file is reaped after 30s).';
+    }
+    if (code === 'RECORD_NOT_FOUND') {
+        return 'The dispatch record does not exist on disk. Re-run `peaks sub-agent dispatch <role>` to materialize a fresh record path; the previous batch may have been garbage-collected.';
+    }
+    if (code === 'INVALID_RECORD_JSON') {
+        return 'The record file is corrupted (truncated mid-write or hand-edited). Delete it and re-run `peaks sub-agent dispatch`; the parent Dispatcher will treat this as a fresh dispatch.';
+    }
+    if (code === 'INVALID_PROGRESS' || code === 'NOTE_TOO_LONG') {
+        return 'Pass --progress as integer 0..100 and --note as ≤ 200 chars. Both are validated by the CLI before reaching the writer.';
+    }
+    return 'See error message; if the record file is missing or corrupted, the parent Dispatcher will mark the sub-agent as stale after 5 minutes.';
+}

package/dist/cli/commands/hook-handle.js

@@ -0,0 +1,157 @@
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { detectIdeFromContext, parseAdapterStdin, parseClaudeShapeStdin, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
+import { buildCanonicalHook, formatDecisionResponse } from '../../services/ide/hook-protocol.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { evaluateCodeBan } from '../../services/audit/enforcers/code-ban.js';
+import { isRootWrite } from '../../services/audit/enforcers/no-root-pollution.js';
+import { checkLoginGate } from '../../services/audit/enforcers/login-gate.js';
+import { resolveActiveSkillForCaller } from '../../services/audit/enforcers/active-skill-resolver.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { emitDecision, emitHint } from '../../services/hooks/output.js';
+/**
+ * Read the hook payload. `PEAKS_HOOK_STDIN` is a test seam (same convention as
+ * `gate-commands.ts`); production reads stdin. The TTY short-circuit means an
+ * interactive shell invocation is treated as an empty payload (allow).
+ */
+async function readStdin() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    if (override !== undefined) {
+        return override;
+    }
+    if (process.stdin.isTTY)
+        return '';
+    return new Promise((resolveStdin) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => resolveStdin(data));
+        process.stdin.on('error', () => resolveStdin(data));
+    });
+}
+/**
+ * `peaks hook handle` —— peaks 自有 hook 协议的单一入口。
+ *
+ * 该命令是 peaks-loop 拥有的 hook 处理总入口。它:
+ *   1. 读 stdin
+ *   2. auto-detect 来源 IDE(env / stdin shape / cwd)
+ *   3. 归一化到 peaks canonical schema
+ *   4. dispatch 到内部 peaks 逻辑(目前:gate enforce)
+ *   5. 用 IDE 期望的格式发回决策
+ *
+ * Slice #1 阶段:peaks hook handle 与 peaks gate enforce
+ * 并存(后者内部走 hook-translator)。Slice #2 把 IDE settings 改成调用
+ * peaks hook handle 即可。Slice #3 删除旧命令。
+ */
+export function registerHookHandleCommand(program, io) {
+    const hook = program.command('hook').description('Peaks 自有 hook 协议单一入口（slice #1 新增；后续 slice 将逐步替代 gate enforce）');
+    addJsonOption(hook
+        .command('handle')
+        .description('Read stdin hook payload, auto-detect IDE, dispatch to peaks gate-enforce logic, output IDE-formatted decision')
+        .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')).action(async (options) => {
+        try {
+            const raw = await readStdin();
+            let parsed = null;
+            if (raw.trim().length > 0) {
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    // Malformed JSON — treat as empty payload (fail-open)
+                    parsed = null;
+                }
+            }
+            const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin: parsed });
+            const adapter = getAdapter(ide);
+            // Slice #3: per-adapter stdin parser dispatch. The detected IDE
+            // determines which parser runs; unknown IDEs fall back to the Claude
+            // shape (preserves slice #1's "fail-open to Claude" semantics).
+            const { toolName, command } = parseAdapterStdin(ide, parsed);
+            // Also try the Claude parser as a secondary fallback so a Trae user who
+            // accidentally pipes a Claude-shaped payload still gets the right fields.
+            const claudeShape = parseClaudeShapeStdin(parsed);
+            const fallbackToolName = toolName ?? claudeShape.toolName ?? pluckString(parsed, ['toolName']);
+            const fallbackCommand = command ?? claudeShape.command ?? pluckString(parsed, ['toolInput', 'command']);
+            const projectRoot = process.env[adapter.envVar] ?? options.project;
+            const hook = buildCanonicalHook({
+                toolName: fallbackToolName ?? '',
+                toolInput: pluckObject(parsed, ['tool_input']) ?? pluckObject(parsed, ['toolInput']) ?? {},
+                projectRoot,
+                rawIdeFormat: ide,
+                rawPayload: parsed
+            });
+            // Dispatch by toolName. For slice #1+, we only handle Bash. Task tool sub-agent dispatch goes through `peaks sub-agent dispatch` (slice #009) and does not need a hook entry.
+            // Other tools: allow (no-op; future events will be added here).
+            if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string' && fallbackCommand.trim().length > 0) {
+                // L2.1 P0 #1: code-commit-ban. Deny `git commit` / `git apply` from peaks-* skills
+                // BEFORE the SOP gate runs. The active skill is read from the per-caller
+                // active-skill file (see active-skill-resolver.ts).
+                const activeSkill = resolveActiveSkillForCaller(projectRoot);
+                if (activeSkill.skill !== null) {
+                    const codeDecision = evaluateCodeBan({ skill: activeSkill.skill, command: fallbackCommand });
+                    if (codeDecision.denied) {
+                        const formatted = formatDecisionResponse(ide, 'deny', codeDecision.reason);
+                        emitDecision(io, formatted.stdout);
+                        if (options.json === true) {
+                            emitHint(io, JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: codeDecision.reason, enforcer: 'code-ban' })));
+                        }
+                        return;
+                    }
+                }
+                // Lazy import to avoid circular: peaks gate enforce logic
+                const { enforceBashCommand } = await import('../../services/sop/gate-enforce-service.js');
+                const decision = await enforceBashCommand(projectRoot, fallbackCommand);
+                if (decision.decision === 'deny') {
+                    const formatted = formatDecisionResponse(ide, 'deny', decision.reason);
+                    emitDecision(io, formatted.stdout);
+                    if (options.json === true) {
+                        emitHint(io, JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: decision.reason })));
+                    }
+                    return;
+                }
+            }
+            // L2.2 P1 #1: login-gate. After code-commit-ban + gate-enforce pass,
+            // flag destructive patterns (uninstall, force-push, --force, --hard,
+            // rm -rf) so the LLM gets a soft warning (still allow). The user
+            // gets the warning via the warn channel; the command proceeds.
+            if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string') {
+                const gate = checkLoginGate({ command: fallbackCommand });
+                if (gate.destructive) {
+                    emitHint(io, `warning: login-gate: destructive command detected (pattern: ${gate.matchedPattern}). Confirm with the user before proceeding.`);
+                }
+            }
+            // L2.1 P0 #2: no-root-pollution. Deny Write/Edit to files outside the
+            // root allowlist. file_path is read from toolInput.file_path (Claude
+            // and most IDEs use the same shape). When the field is missing or the
+            // path is not at depth 1, the enforcer allows (no-op).
+            if (hook.toolName === 'Write' || hook.toolName === 'Edit' || hook.toolName === 'MultiEdit' || hook.toolName === 'Create') {
+                const filePath = pluckString(parsed, ['tool_input', 'file_path'])
+                    ?? pluckString(parsed, ['toolInput', 'file_path'])
+                    ?? pluckString(parsed, ['tool_input', 'path'])
+                    ?? pluckString(parsed, ['toolInput', 'path']);
+                if (typeof filePath === 'string' && filePath.trim().length > 0) {
+                    const rootCheck = isRootWrite({ projectRoot, filePath });
+                    if (!rootCheck.allowed) {
+                        const formatted = formatDecisionResponse(ide, 'deny', rootCheck.denyReason);
+                        emitDecision(io, formatted.stdout);
+                        if (options.json === true) {
+                            emitHint(io, JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: rootCheck.denyReason, enforcer: 'no-root-pollution' })));
+                        }
+                        return;
+                    }
+                }
+            }
+            const allow = formatDecisionResponse(ide, 'allow');
+            emitDecision(io, allow.stdout);
+            if (options.json === true) {
+                printResult(io, ok('hook.handle', { ide, tool: hook.toolName, decision: 'allow' }), true);
+            }
+        }
+        catch (error) {
+            // Fail-open: a bug in hook.handle must not brick Claude Code.
+            emitHint(io, `hook handle: internal error, allowing command (${error instanceof Error ? error.message : String(error)})`);
+            if (options.json === true) {
+                printResult(io, fail('hook.handle', 'HOOK_HANDLE_FAILED', error instanceof Error ? error.message : 'unknown', {}), true);
+            }
+        }
+    });
+}

package/dist/cli/commands/hooks-commands.js

@@ -0,0 +1,156 @@
+import { existsSync } from 'node:fs';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
+import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
+import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+function resolveScope(options) {
+    return options.global ? 'global' : 'project';
+}
+function resolveProjectRoot(scope, project) {
+    return scope === 'project' ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd()) : undefined;
+}
+/**
+ * Resolve the IDE the install should target. The CLI user can override with
+ * `--ide <id>`. Otherwise we delegate to `detectIdeFromContext` which checks
+ * `process.env[adapter.envVar]` → stdin shape → cwd `.trae`/`.claude` →
+ * fallback `'claude-code'`. Pass `parsedStdin: null` since `peaks hooks
+ * install` is not invoked from inside an IDE hook — there's no stdin payload.
+ */
+function resolveIdeForCommand(options, projectRoot) {
+    if (options.ide !== undefined && options.ide.length > 0) {
+        return options.ide;
+    }
+    return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
+}
+/**
+ * Slice #014: compute the per-IDE peaks hook entries for the install /
+ * dry-run RESPONSE SUMMARY. This is the *desired* shape (what the install
+ * WOULD write), not what is on disk. The status command uses a different
+ * helper (`readInstalledEntriesFromSettings`) that reads the actual
+ * settings.json.
+ *
+ * After slice #014 only the gate-enforce entry is ever installed
+ * (the legacy progress-start surface is gone). The summary mirrors
+ * the install shape so the JSON envelope doesn't claim a hook the
+ * service did not write.
+ */
+function listExpectedEntriesForIde(ide, _skipProgress = false) {
+    const adapter = getAdapter(ide);
+    if (ide === 'trae') {
+        return [{ matcher: adapter.toolMatcher, sentinel: 'peaks hook handle' }];
+    }
+    return [{ matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' }];
+}
+export function registerHooksCommands(program, io) {
+    const hooks = program
+        .command('hooks')
+        .description("Manage the Peaks-managed hook entry in the adapter's settings.json (default: .claude/settings.json for Claude, .trae/settings.json for Trae). Slice #014: the only installed entry is the gate-enforce hook (SOP gate). The legacy progress-start hook (auto-spawn sub-agent progress terminal) is no longer installed — sub-agent progress is now surfaced via the dispatch + heartbeat flow (`peaks sub-agent dispatch` / `peaks sub-agent heartbeat`). The IDE is auto-detected from env / cwd; override with --ide <id>.");
+    addJsonOption(hooks
+        .command('install')
+        .description(`Install the peaks-managed gate-enforce hook entry into the adapter's settings.json. Slice #014: only the gate-enforce entry is installed; the legacy progress-start entry is no longer installed. Idempotent: re-runs are no-ops. Project scope by default.`)
+        .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', "target adapter id (claude-code | trae); default: auto-detect from env/cwd")
+        .option('--dry-run', 'show what would change without writing')
+        .option('--no-progress', 'skip the progress-start PreToolUse hook entry; install ONLY the gate-enforce entry')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        const skipProgress = options.progress === false;
+        try {
+            if (options.dryRun === true) {
+                const plan = planHookInstall(scope, projectRoot, { ide, skipProgress });
+                const dryRunEntries = listExpectedEntriesForIde(ide, skipProgress);
+                printResult(io, ok('hooks.install', {
+                    ...plan,
+                    ide,
+                    applied: false,
+                    dryRun: true,
+                    skipProgress,
+                    entries: dryRunEntries
+                }, [], [`would install ${dryRunEntries.length} peaks-managed hook entries`]), options.json);
+                return;
+            }
+            const result = applyHookInstall(scope, projectRoot, { ide, skipProgress });
+            // Slice #3: build the per-IDE entries summary from the actual installed
+            // entries, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
+            // claude-code default). The user's JSON envelope must reflect the IDE
+            // they targeted. Slice #014: the install only emits the gate-enforce
+            // entry; the summary mirrors the install shape, NOT a hardcoded
+            // expected list.
+            const installedEntries = listExpectedEntriesForIde(ide, skipProgress);
+            const nextActions = result.applied
+                ? [
+                    'Restart the IDE (or reload the workspace) so the hook entries take effect',
+                    `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`
+                ]
+                : [];
+            printResult(io, ok('hooks.install', {
+                ...result,
+                ide,
+                dryRun: false,
+                skipProgress,
+                entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+            }, [], nextActions), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, ide, applied: false, skipProgress }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('uninstall')
+        .description("Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.")
+        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const result = removeHookInstall(scope, projectRoot, { ide });
+            printResult(io, ok('hooks.uninstall', { ...result, ide }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('status')
+        .description('Report which peaks-managed hook entries are installed.')
+        .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const status = readHookStatus(scope, projectRoot, { ide });
+            // Slice #014: read the ACTUAL on-disk entries (post-install shape),
+            // not the IDE-EXPECTED list. Pre-#014 `listInstalledEntriesForIde`
+            // returned the expected list and reported `entries: [Bash, Task]`
+            // even when the file only had `Bash`. The new helper reads the
+            // file and reports whatever peaks-managed entries are present,
+            // including any legacy progress-start entry that a pre-#014
+            // install left behind.
+            const settingsPath = status.settingsPath;
+            const settings = existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
+            printResult(io, ok('hooks.status', {
+                ...status,
+                ide,
+                entries: readInstalledEntriesFromSettings(settings, ide)
+            }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.status', 'HOOKS_STATUS_FAILED', message, { scope, ide }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/ide-commands.d.ts

@@ -0,0 +1,25 @@
+/**
+ * peaks ide * CLI (Slice 2026-07-09 add-zcode-adapter, Slice C).
+ *
+ * Slice C adds ONE verb:
+ *
+ *   peaks ide model --current
+ *
+ * Outputs the currently-active model id detected from the host
+ * environment (so far: only the `zcode` adapter opts in via
+ * `IdeAdapter.detectCurrentModel?`). The CLI is the read-only
+ * debugging surface for runtime model probing. It does NOT set any
+ * state — `peaks config set model` remains the canonical write path.
+ *
+ * Future slices will extend this surface with `peaks ide list`,
+ * `peaks ide detect`, etc. — this slice keeps the surface minimal
+ * (per Karpathy guideline #2 — Simplicity First).
+ *
+ * Vendor-neutrality: this file delegates to
+ * `src/services/ide/current-model-detector.ts` which walks every
+ * registered adapter. This file does NOT import any specific
+ * adapter.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerIdeCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/ide-commands.js

@@ -0,0 +1,42 @@
+import { detectCurrentIdeModel } from '../../services/ide/current-model-detector.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { listAdapterIds } from '../../services/ide/ide-registry.js';
+export function registerIdeCommands(program, io) {
+    const ide = program.command('ide').description('Read-only introspection helpers for the registered IDE adapter layer (slice 2026-07-09 add-zcode-adapter, Slice C)');
+    addJsonOption(ide
+        .command('model')
+        .description('Inspect the IDE adapter model surface. Slice C supports `--current` only.')
+        .option('--current', 'Print the model id the active IDE adapter reports as currently configured')
+        .action(async (options) => {
+        if (options.current) {
+            await runIdeModelCurrent(io, options);
+            return;
+        }
+        // No verb supplied — Commander would normally show help; we
+        // emit a structured error instead so the JSON envelope stays
+        // consistent for LLM callers.
+        printResult(io, fail('ide.model', 'MISSING_VERB', 'Specify a verb: --current. Future slices may add --configured / --default.', { registeredAdapters: listAdapterIds() }, ['Rerun with --current to read the runtime-detected model id.']), options.json);
+    }));
+}
+async function runIdeModelCurrent(io, options) {
+    try {
+        const modelId = await detectCurrentIdeModel();
+        if (modelId === undefined) {
+            printResult(io, ok('ide.model.current', {
+                modelId: null,
+                detected: false,
+                registeredAdapters: listAdapterIds(),
+            }), options.json);
+            return;
+        }
+        printResult(io, ok('ide.model.current', {
+            modelId,
+            detected: true,
+            registeredAdapters: listAdapterIds(),
+        }), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('ide.model.current', 'DETECTION_FAILED', 'Runtime model detection failed; falling back to configured model. See logs.', { error: error instanceof Error ? error.message : String(error) }, ['Check `PEAKS_LOG_LEVEL=debug peaks ide model --current` for the underlying error.']), options.json);
+    }
+}