peaks-loop 3.0.0

package/dist/src/cli/commands/fork-commands.js

@@ -0,0 +1,163 @@
+/**
+ * v2.15.0 follow-up — G11: fork sync CLI.
+ *
+ *   - `peaks fork status`               — show baseline + drift + last sync
+ *   - `peaks fork upstream-check`       — recommend next stable tag
+ *   - `peaks fork sync-plan`            — generate a sync plan
+ *   - `peaks fork sync`                 — record a sync execution
+ *   - `peaks fork sync-verify`          — mark a sync as verified / failed
+ *
+ * All 5 commands are pure local reads/writes against
+ * `.peaks/fork-state.json`. The actual git fetch + merge is out of
+ * scope for this slice (deferred to 2.15.x).
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { appendSyncRecord, buildForkStatusReport, makeSyncId, readForkState, recommendStableTags, updateSyncRecordStatus, writeForkState } from '../../services/fork/fork-sync-state.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerForkCommands(program, io) {
+    const fork = program
+        .command('fork')
+        .description('v2.15.0 follow-up G11: manage upstream tag sync for forked projects (hermes-style).');
+    // 1. status
+    addJsonOption(fork
+        .command('status')
+        .description('Show the current fork baseline (upstream + tag + drift) and the most recent sync. ' +
+        'Pure read of `.peaks/fork-state.json`.')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const report = buildForkStatusReport(state);
+        printResult(io, ok('fork.status', { projectRoot, report: serializeReport(report) }, [], [
+            report.driftWarning
+                ? 'Drift exceeds 30 commits — consider `peaks fork upstream-check` to plan a sync.'
+                : 'No sync action recommended at this time.'
+        ]), opts.json ?? false);
+    });
+    // 2. upstream-check
+    addJsonOption(fork
+        .command('upstream-check')
+        .description('Recommend stable upstream tags to sync to, given a list of available tags. ' +
+        '`--tags` is a comma-separated list; pre-release tags (alpha/beta/rc/dev/preview) are filtered out. ' +
+        'Returns the list of stable tags newer than the current baseline.')
+        .requiredOption('--tags <list>', 'comma-separated list of available upstream tags')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const availableTags = opts.tags.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        const state = readForkState(projectRoot);
+        const baselineTag = state.baseline?.basedOn ?? null;
+        const recommended = recommendStableTags(availableTags, baselineTag);
+        printResult(io, ok('fork.upstream-check', {
+            projectRoot,
+            currentBaseline: baselineTag,
+            totalAvailableTags: availableTags.length,
+            recommendedTags: recommended,
+            nextRecommended: recommended[0] ?? null
+        }, [], [
+            recommended.length === 0
+                ? 'No stable tags newer than the current baseline.'
+                : `Recommended next sync target: ${recommended[0]}`
+        ]), opts.json ?? false);
+    });
+    // 3. sync-plan
+    addJsonOption(fork
+        .command('sync-plan')
+        .description('Generate a sync plan for the given upstream tag. Records the plan in `.peaks/fork-state.json`. ' +
+        'Returns the plan id used to invoke `peaks fork sync`. Pure local write; no git operations.')
+        .requiredOption('--upstream <tag>', 'target upstream tag (e.g. v1.20.0)')
+        .option('--conflicts <list>', 'comma-separated predicted conflict file globs')
+        .option('--patches <list>', 'comma-separated business patch identifiers to replay')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const syncId = makeSyncId(opts.upstream);
+        const conflicts = opts.conflicts ? opts.conflicts.split(',').map((s) => s.trim()).filter((s) => s.length > 0) : [];
+        const patches = opts.patches ? opts.patches.split(',').map((s) => s.trim()).filter((s) => s.length > 0) : [];
+        const record = {
+            syncId,
+            targetTag: opts.upstream,
+            plannedAt: new Date().toISOString(),
+            predictedConflicts: conflicts,
+            businessPatches: patches,
+            status: 'planned'
+        };
+        const next = appendSyncRecord(state, record);
+        writeForkState(projectRoot, next);
+        printResult(io, ok('fork.sync-plan', { projectRoot, syncId, record }, [], [
+            `Run \`peaks fork sync --sync-id ${syncId}\` to mark execution start.`,
+            `Run \`peaks fork sync-verify --sync-id ${syncId} --status verified\` after the sync completes.`
+        ]), opts.json ?? false);
+    });
+    // 4. sync (mark execution)
+    addJsonOption(fork
+        .command('sync')
+        .description('Mark a planned sync as in-progress. Records the execution start. ' +
+        'This slice does NOT perform the actual git fetch + merge — the LLM / operator runs those, ' +
+        'then calls `sync-verify` to record the result.')
+        .requiredOption('--sync-id <id>', 'sync plan id from `peaks fork sync-plan`')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const target = state.history.find((r) => r.syncId === opts.syncId);
+        if (!target) {
+            printResult(io, fail('fork.sync', 'NOT_FOUND', `sync id "${opts.syncId}" not found in fork-state.json`, { projectRoot }, [
+                'Run `peaks fork sync-plan` first to generate a plan.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const next = updateSyncRecordStatus(state, opts.syncId, 'in-progress');
+        writeForkState(projectRoot, next);
+        printResult(io, ok('fork.sync', { projectRoot, syncId: opts.syncId, status: 'in-progress', targetTag: target.targetTag }, [], [
+            'Now run the actual git fetch + merge, then call `peaks fork sync-verify` to record the result.'
+        ]), opts.json ?? false);
+    });
+    // 5. sync-verify
+    addJsonOption(fork
+        .command('sync-verify')
+        .description('Mark a sync as verified (success) or failed. Optionally records verification notes. ' +
+        'On success, the current baseline is also updated to the synced tag.')
+        .requiredOption('--sync-id <id>', 'sync plan id')
+        .requiredOption('--status <verified|failed>', 'sync verification outcome')
+        .option('--notes <text>', 'optional verification notes')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        if (opts.status !== 'verified' && opts.status !== 'failed') {
+            printResult(io, fail('fork.sync-verify', 'INVALID_STATUS', `status must be "verified" or "failed" (got "${opts.status}")`, { projectRoot: opts.project ?? '' }, [
+                'Pass --status verified on success, --status failed on failure.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const target = state.history.find((r) => r.syncId === opts.syncId);
+        if (!target) {
+            printResult(io, fail('fork.sync-verify', 'NOT_FOUND', `sync id "${opts.syncId}" not found`, { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        let next = updateSyncRecordStatus(state, opts.syncId, opts.status, opts.notes);
+        if (opts.status === 'verified') {
+            const baseline = {
+                upstream: state.baseline?.upstream ?? 'unknown',
+                basedOn: target.targetTag,
+                recordedAt: new Date().toISOString(),
+                commitsAhead: 0,
+                filesChanged: 0
+            };
+            next = { ...next, baseline };
+        }
+        writeForkState(projectRoot, next);
+        printResult(io, ok('fork.sync-verify', {
+            projectRoot,
+            syncId: opts.syncId,
+            status: opts.status,
+            notes: opts.notes ?? null,
+            newBaseline: next.baseline
+        }, [], [
+            opts.status === 'verified'
+                ? 'Baseline updated to the synced tag.'
+                : 'Sync marked as failed. Re-run `peaks fork sync-plan` to retry.'
+        ]), opts.json ?? false);
+    });
+}
+function serializeReport(r) {
+    return r;
+}

package/dist/src/cli/commands/gate-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerGateCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,117 @@
+import { enforceBashCommand, recordGateBypass, GateBypassError } from '../../services/sop/gate-enforce-service.js';
+import { fail, ok } from '../../shared/result.js';
+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/src/cli/commands/heartbeat-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerHeartbeatCommand(parent: Command, io: ProgramIO): void;

package/dist/src/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 '../../shared/result.js';
+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/src/cli/commands/hook-handle.d.ts

@@ -0,0 +1,17 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * `peaks hook handle` —— peaks 自有 hook 协议的单一入口。
+ *
+ * 该命令是 peaks-cli 拥有的 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 declare function registerHookHandleCommand(program: Command, io: ProgramIO): void;

package/dist/src/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 { evaluateSoloCodeBan } from '../../services/audit/enforcers/solo-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 '../../shared/result.js';
+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-cli 拥有的 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: solo-code-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 soloDecision = evaluateSoloCodeBan({ skill: activeSkill.skill, command: fallbackCommand });
+                    if (soloDecision.denied) {
+                        const formatted = formatDecisionResponse(ide, 'deny', soloDecision.reason);
+                        emitDecision(io, formatted.stdout);
+                        if (options.json === true) {
+                            emitHint(io, JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: soloDecision.reason, enforcer: 'solo-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 solo-code-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/src/cli/commands/hooks-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerHooksCommands(program: Command, io: ProgramIO): void;