peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/hooks/worktree-authorization-gate.js

@@ -0,0 +1,492 @@
+/**
+ * peaks-loop Worktree Authorization Gate (slice 2026-07-27-worktree-user-auth).
+ *
+ * Project-level red line: no autonomous LLM path is allowed to create a
+ * Git worktree, switch Claude Code's Agent isolation to "worktree",
+ * or fabricate a clean-tree baseline via `git stash` — unless the user
+ * has, in the *current task / current session*, explicitly authorized
+ * that exact operation. Authorization is recorded by
+ * `peaks worktree auth grant` (see `worktree-auth-commands.ts`) and is
+ * scoped to:
+ *
+ *   - sessionId: the active peaks session at grant time
+ *   - requestId: the active peaks request at grant time (if any)
+ *   - operation: one of the OperationType values
+ *   - expiresAt: hard deadline (default +5 min from grant)
+ *   - consumed: single-use vs multi-use (gate calls `consume()` on use)
+ *
+ * The gate is invoked from `peaks gate enforce` (the PreToolUse hook
+ * command) for every Bash / Agent / EnterWorktree tool call. It is
+ * fail-closed: a malformed grant file, a missing scope, an expired
+ * token, or any other evaluation error → deny with a structured
+ * `WORKTREE_USER_AUTH_REQUIRED` reason.
+ *
+ * Why this is a service, not just a regex: a regex can match the
+ * command but cannot check "did the current user just say so". The
+ * user-originated authorization is a current-task file artifact;
+ * the gate is its consumer.
+ *
+ * Why single-use by default: an LLM can pass the gate once per
+ * authorized intent. If the same LLM needs to run a second
+ * `git worktree add` later, it must `peaks worktree auth grant`
+ * again — which is exactly the moment the user can say no. Multi-use
+ * is a deliberate opt-in via `--multi`.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { deserializeLease, isLeaseActive, leaseFilePath, } from '../worktree/worktree-lease.js';
+import { containerLeaseFilePath, deserializeContainerLease, isContainerLeaseActive, } from '../container/container-lease.js';
+export const WORKTREE_AUTH_FILE = 'worktree-auth.json';
+/** Stable identifier of the current "user authorization" — derived from session + tool + key args. */
+export function currentAuthFingerprint(input) {
+    // 16 hex chars is enough for tie-breaking; the gate never uses this as a security boundary, only as a
+    // log-correlation key.
+    const seed = `${input.sessionId}|${input.toolName}|${input.command ?? ''}|${input.isolation ?? ''}`;
+    return createHash('sha1').update(seed).digest('hex').slice(0, 16);
+}
+/** The file the gate reads. Default location: `.peaks/_runtime/<sessionId>/worktree-auth.json`. */
+export function worktreeAuthFilePath(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, WORKTREE_AUTH_FILE);
+}
+/**
+ * Read + validate the on-disk grant file. Returns `null` for "no file" (not an error — just no auth
+ * recorded yet). Throws `WorktreeAuthFileInvalidError` for malformed JSON / wrong shape / wrong
+ * sessionId — the gate treats this as deny, not allow. We never silently fail open.
+ */
+export function readAuthorization(projectRoot, sessionId) {
+    const path = worktreeAuthFilePath(projectRoot, sessionId);
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new WorktreeAuthFileInvalidError(`worktree-auth.json: invalid JSON (${error.message})`, { path });
+    }
+    if (!isAuthorizationFile(parsed)) {
+        throw new WorktreeAuthFileInvalidError('worktree-auth.json: shape does not match AuthorizationFile', { path });
+    }
+    if (parsed.sessionId !== sessionId) {
+        throw new WorktreeAuthFileInvalidError(`worktree-auth.json: sessionId mismatch (file=${parsed.sessionId}, caller=${sessionId})`, { path });
+    }
+    return parsed;
+}
+export class WorktreeAuthFileInvalidError extends Error {
+    path;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'WorktreeAuthFileInvalidError';
+        this.path = opts.path;
+    }
+}
+function isAuthorizationFile(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (v.schemaVersion !== 1)
+        return false;
+    if (typeof v.sessionId !== 'string')
+        return false;
+    if (typeof v.createdAt !== 'string')
+        return false;
+    if (!Array.isArray(v.grants))
+        return false;
+    return v.grants.every(isWorktreeAuthorization);
+}
+function isWorktreeAuthorization(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const g = value;
+    if (typeof g.operation !== 'string')
+        return false;
+    if (!isOperationType(g.operation))
+        return false;
+    if (typeof g.reason !== 'string')
+        return false;
+    if (g.promptHash !== null && typeof g.promptHash !== 'string')
+        return false;
+    if (g.requestId !== null && typeof g.requestId !== 'string')
+        return false;
+    if (typeof g.issuedAt !== 'string')
+        return false;
+    if (typeof g.expiresAt !== 'string')
+        return false;
+    if (typeof g.consume !== 'boolean')
+        return false;
+    if (typeof g.consumed !== 'boolean')
+        return false;
+    return true;
+}
+function isOperationType(value) {
+    return (value === 'git-worktree' ||
+        value === 'agent-isolation-worktree' ||
+        value === 'git-stash-mutating' ||
+        value === 'git-worktree-other');
+}
+/** The narrow set of worktree-mutating `git` commands the gate actually blocks. Tightly scoped on purpose. */
+const GIT_WORKTREE_REGEX = /^\s*git\s+worktree(?:\s+(add|remove|prune|lock|unlock|move|repair))?\b/;
+const GIT_STASH_MUTATING_REGEX = /^\s*git\s+stash(?:\s+(push|pop|save|create|drop|store|clear|apply))(?:\s+|$)/;
+/**
+ * Map the actual tool call to an `OperationType` the gate should look up. Returns `null` for tool calls
+ * the gate does not care about (e.g. `Read`, `Glob`, or `Bash` running `ls`). The regex is deliberately
+ * conservative: anything ambiguous returns `null` (allow).
+ */
+export function classifyToolCall(input) {
+    if (input.toolName === 'Agent') {
+        return input.isolation === 'worktree' ? 'agent-isolation-worktree' : null;
+    }
+    if (input.toolName === 'EnterWorktree') {
+        // Claude Code's explicit EnterWorktree tool — same authorization as the Agent isolation worktree path.
+        return 'agent-isolation-worktree';
+    }
+    if (input.toolName === 'Workflow') {
+        // Future-proofing: if an IDE ever exposes a worktree-creating Workflow tool, route it through the same
+        // gate. No Claude-Code tool currently exists, so this is a defensive default.
+        return null;
+    }
+    if (input.toolName === 'Bash') {
+        if (typeof input.command !== 'string' || input.command.length === 0)
+            return null;
+        if (GIT_STASH_MUTATING_REGEX.test(input.command))
+            return 'git-stash-mutating';
+        if (GIT_WORKTREE_REGEX.test(input.command))
+            return 'git-worktree';
+        return null;
+    }
+    return null;
+}
+/**
+ * Core gate decision. Pure: takes a `WorktreeAuthCheckInput` + the parsed `AuthorizationFile`,
+ * returns `WorktreeAuthDecision`. Side effects (consume / file rewrite) are NOT performed here — see
+ * `evaluateWorktreeAuth` for the write-then-evaluate pattern that `peaks gate enforce` uses.
+ */
+export function decideFromAuthorization(input, operation, file) {
+    if (file === null) {
+        return {
+            allow: false,
+            code: 'WORKTREE_USER_AUTH_REQUIRED',
+            reason: `No current-task user authorization for "${operation}" (session=${input.sessionId}).`,
+            remediation: `Ask the user to explicitly authorize this worktree-mutating operation, then run \`peaks worktree auth grant --operation ${operation} --reason "<why>"\` ` +
+                `before the tool call retries. Re-running with --consume=false and a longer --ttl is allowed but should be rare.`
+        };
+    }
+    const now = Date.now();
+    // First try to find a requestId-matched, non-consumed, unexpired grant. If none is found,
+    // we drop the requestId filter and look again — that gives us a clean two-tier distinction
+    // between "this rid is scoped to a different rid" and "all grants are stale/expired".
+    const requestMatched = file.grants
+        .filter((g) => g.operation === operation)
+        .filter((g) => !g.consumed)
+        .filter((g) => Date.parse(g.expiresAt) > now)
+        .find((g) => g.requestId === null || g.requestId === input.requestId);
+    if (requestMatched !== undefined) {
+        return { allow: true, authorization: requestMatched, remaining: file.grants.length, viaLease: null };
+    }
+    // No live grant matched the current rid (or the caller's rid is null). Diagnose why.
+    const sameOpAnyState = file.grants.filter((g) => g.operation === operation);
+    if (sameOpAnyState.length === 0) {
+        return {
+            allow: false,
+            code: 'WORKTREE_USER_AUTH_REQUIRED',
+            reason: `No grant for operation "${operation}" in this session.`,
+            remediation: `Run \`peaks worktree auth grant --operation ${operation} --reason "<why>"\` from the LLM after the user has explicitly asked for the operation.`
+        };
+    }
+    const ridScoped = sameOpAnyState.find((g) => g.requestId !== null);
+    const ridMatchesScope = ridScoped !== undefined && (input.requestId === null || ridScoped.requestId === input.requestId);
+    if (ridScoped !== undefined && !ridMatchesScope) {
+        return {
+            allow: false,
+            code: 'WORKTREE_USER_AUTH_REQUEST_MISMATCH',
+            reason: `Grant for "${operation}" is scoped to requestId=${ridScoped.requestId} but the current tool call carries requestId=${input.requestId ?? 'null'}.`,
+            remediation: `Either drop the requestId scope from the grant (\`peaks worktree auth grant --operation ${operation} --no-request-id\`) or operate under the scoped request.`
+        };
+    }
+    // Otherwise: every grant for the operation is either consumed or expired.
+    const hasUnexpired = sameOpAnyState.some((g) => Date.parse(g.expiresAt) > now);
+    if (!hasUnexpired) {
+        return {
+            allow: false,
+            code: 'WORKTREE_USER_AUTH_EXPIRED',
+            reason: `All grants for operation "${operation}" in this session have expired.`,
+            remediation: `Re-run \`peaks worktree auth grant --operation ${operation} --reason "<why>"\` (default TTL 5 min) before the tool call retries.`
+        };
+    }
+    // Grants exist and at least one is unexpired, but every non-expired one is consumed.
+    return {
+        allow: false,
+        code: 'WORKTREE_USER_AUTH_REQUIRED',
+        reason: `All unexpired grants for operation "${operation}" in this session are already consumed.`,
+        remediation: `Re-run \`peaks worktree auth grant --operation ${operation} --reason "<why>"\` to issue a fresh grant (or pass --multi to make it multi-use).`
+    };
+}
+/**
+ * Public entry point used by `peaks gate enforce`. Reads the auth file, decides, and (when consume=true
+ * and the call is allowed) atomically rewrites the file with `consumed: true` on the matching grant.
+ *
+ * Returns `deny` on any internal error: malformed file, IO failure, missing session binding, etc. The
+ * gate is fail-closed — never allow on error.
+ */
+export function evaluateWorktreeAuth(input) {
+    const operation = classifyToolCall(input);
+    if (operation === null) {
+        // Pass-through (Read, Glob, etc., and any Bash that isn't worktree-mutating).
+        return {
+            allow: true,
+            authorization: syntheticAllow(),
+            remaining: 0,
+            viaLease: null
+        };
+    }
+    let file;
+    try {
+        file = readAuthorization(input.projectRoot, input.sessionId);
+    }
+    catch (error) {
+        if (error instanceof WorktreeAuthFileInvalidError) {
+            return {
+                allow: false,
+                code: 'WORKTREE_USER_AUTH_FILE_INVALID',
+                reason: `worktree-auth.json present but invalid: ${error.message}`,
+                remediation: `Delete the malformed file (\`rm ${error.path}\`) and re-run \`peaks worktree auth grant --operation ${operation} --reason "<why>"\`. ` +
+                    `For security, the gate never fails open on a malformed grant file.`
+            };
+        }
+        return {
+            allow: false,
+            code: 'WORKTREE_USER_AUTH_FILE_INVALID',
+            reason: `worktree-auth.json IO error: ${error.message}`,
+            remediation: `Re-run \`peaks worktree auth grant --operation ${operation} --reason "<why>"\` and retry.`
+        };
+    }
+    const decision = decideFromAuthorization(input, operation, file);
+    if (decision.allow) {
+        if (decision.authorization !== null && decision.authorization.consume) {
+            try {
+                markConsumed(input.projectRoot, input.sessionId, decision.authorization);
+            }
+            catch (error) {
+                // Best-effort: the gate already issued an allow. We do NOT revoke; the next call will see the
+                // un-consumed grant and try again. This is preferable to denying a legitimate operation because
+                // of a write failure.
+                return {
+                    allow: true,
+                    authorization: decision.authorization,
+                    remaining: 0,
+                    viaLease: null
+                };
+            }
+        }
+        return decision;
+    }
+    // Auth denied — try the lease fallback. The lease is a SECOND authorization path that sub-agents
+    // that have adopted the spawn/release CLI (Part 1 + 2.A) use; sub-agents that still rely on
+    // `peaks worktree auth grant` are unaffected (their grants already allowed above).
+    if (input.leaseId === null || input.leaseId === undefined || input.leaseId.length === 0) {
+        // Part 19: try the container lease fallback before giving up.
+        if (input.containerLeaseId !== null && input.containerLeaseId !== undefined && input.containerLeaseId.length > 0) {
+            return decideFromContainerLease(input);
+        }
+        return decision;
+    }
+    const leaseResult = decideFromLease(input);
+    if (leaseResult.allow)
+        return leaseResult;
+    // Part 19: if the worktree lease did not allow, try the container
+    // lease as a second lease path (sub-agents with container
+    // isolation).
+    if (input.containerLeaseId !== null && input.containerLeaseId !== undefined && input.containerLeaseId.length > 0) {
+        return decideFromContainerLease(input);
+    }
+    return leaseResult;
+}
+/**
+ * Part 19: L4 container lease fallback. Reads the container
+ * lease file at `.peaks/_runtime/<sid>/container-leases/<id>.json`
+ * and permits the operation iff the lease is `isContainerLeaseActive`
+ * and its `rid` matches the current peaks request. Mirrors
+ * `decideFromLease` for the L4 container surface; the L2 worktree
+ * lease is the L2 path, this is the L4 path.
+ *
+ * On malformed file / non-active / rid mismatch the function
+ * fails closed with the new error codes
+ * (CONTAINER_LEASE_FILE_INVALID / NOT_ACTIVE / REQUEST_MISMATCH).
+ */
+export function decideFromContainerLease(input) {
+    const containerLeaseId = input.containerLeaseId ?? '';
+    const file = containerLeaseFilePath(`${input.projectRoot}/.peaks/_runtime/${input.sessionId}`, containerLeaseId);
+    if (!existsSync(file)) {
+        return {
+            allow: false,
+            code: 'CONTAINER_LEASE_FILE_INVALID',
+            reason: `No container lease at ${file} (leaseId=${containerLeaseId}).`,
+            remediation: `Run \`peaks container spawn --rid <rid> --role <role> --purpose "<why>"\` to create the lease, then re-run. The PEAKS_CONTAINER_LEASE_ID env is the source of truth (dispatch injects it).`
+        };
+    }
+    let lease;
+    try {
+        lease = deserializeContainerLease(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        return {
+            allow: false,
+            code: 'CONTAINER_LEASE_FILE_INVALID',
+            reason: `Container lease at ${file} is unreadable / malformed: ${err.message}`,
+            remediation: `Delete the malformed lease file (\`rm ${file}\`) and re-spawn. The gate never fails open on a malformed lease.`
+        };
+    }
+    if (input.requestId !== null && lease.rid !== input.requestId) {
+        return {
+            allow: false,
+            code: 'CONTAINER_LEASE_REQUEST_MISMATCH',
+            reason: `Container lease rid=${lease.rid} does not match current requestId=${input.requestId}.`,
+            remediation: `Either re-spawn a container lease for the current rid, or operate under the lease's own rid.`
+        };
+    }
+    if (!isContainerLeaseActive(lease)) {
+        return {
+            allow: false,
+            code: 'CONTAINER_LEASE_NOT_ACTIVE',
+            reason: `Container lease ${lease.leaseId} is not active (status=${lease.status}, remainingMs=${lease.expiresAt - Date.now()}).`,
+            remediation: `Run \`peaks container release --lease-id ${lease.leaseId}\` to clean up, then \`peaks container spawn ...\` to create a new lease.`
+        };
+    }
+    return { allow: true, authorization: null, remaining: 0, viaLease: lease };
+}
+/**
+ * Pure: consult the lease file referenced by `input.leaseId` and decide
+ * whether the operation may proceed under the lease. Mirrors the
+ * `decideFromAuthorization` contract: malformed lease → fail-closed;
+ * rid mismatch → deny; non-active lease → deny.
+ */
+export function decideFromLease(input) {
+    const leaseId = input.leaseId ?? '';
+    // `leaseFilePath` expects the per-session runtime dir as its first
+    // argument, NOT the project root. Compose the same path the spawn
+    // CLI writes to (`<projectRoot>/.peaks/_runtime/<sid>`).
+    const runtimeDir = `${input.projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${input.sessionId}`;
+    const file = leaseFilePath(runtimeDir, leaseId);
+    if (!existsSync(file)) {
+        return {
+            allow: false,
+            code: 'WORKTREE_USER_AUTH_REQUIRED',
+            reason: `No worktree auth grant AND no lease at ${file} (leaseId=${leaseId}).`,
+            remediation: `Either run \`peaks worktree auth grant --operation <op> --reason "<why>"\` or ` +
+                `run \`peaks worktree spawn --rid <rid> --role <role> --purpose "<why>"\` to create the lease.`
+        };
+    }
+    let lease;
+    try {
+        lease = deserializeLease(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return {
+            allow: false,
+            code: 'WORKTREE_LEASE_FILE_INVALID',
+            reason: `Lease file at ${file} is unreadable/malformed: ${error.message}`,
+            remediation: `Delete the malformed lease (\`rm ${file}\`) and re-spawn. The gate never fails open on a malformed lease.`
+        };
+    }
+    if (input.requestId !== null && lease.rid !== input.requestId) {
+        return {
+            allow: false,
+            code: 'WORKTREE_LEASE_REQUEST_MISMATCH',
+            reason: `Lease rid=${lease.rid} does not match current requestId=${input.requestId}.`,
+            remediation: `Either re-spawn a lease for the current rid, or operate under the lease's own rid.`
+        };
+    }
+    if (!isLeaseActive(lease)) {
+        return {
+            allow: false,
+            code: 'WORKTREE_LEASE_NOT_ACTIVE',
+            reason: `Lease ${lease.leaseId} is not active (status=${lease.status}, remainingMs=${lease.expiresAt - Date.now()}).`,
+            remediation: `Run \`peaks worktree renew --lease-id ${lease.leaseId}\` to extend, or \`peaks worktree spawn ...\` to create a new lease.`
+        };
+    }
+    return { allow: true, authorization: null, remaining: 0, viaLease: lease };
+}
+/** Mark a single-use grant as consumed. Writes the whole file back atomically (write to .tmp + rename). */
+function markConsumed(projectRoot, sessionId, consumed) {
+    const path = worktreeAuthFilePath(projectRoot, sessionId);
+    if (!existsSync(path)) {
+        // Race: the file vanished between read and write. Treat as "already consumed" — re-running
+        // `peaks worktree auth grant` is the recovery path; we do not write a partial file.
+        return;
+    }
+    const file = readAuthorization(projectRoot, sessionId);
+    if (file === null)
+        return;
+    const next = {
+        ...file,
+        grants: file.grants.map((g) => g === consumed || isSameGrant(g, consumed) ? { ...g, consumed: true } : g)
+    };
+    writeAuthorizationAtomic(path, next);
+}
+function isSameGrant(a, b) {
+    return (a.operation === b.operation &&
+        a.issuedAt === b.issuedAt &&
+        a.expiresAt === b.expiresAt &&
+        a.reason === b.reason);
+}
+function writeAuthorizationAtomic(path, file) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // The on-disk schema is plain JSON; we keep the same writer used by other peaks artifacts to make
+    // diffs and recovery tools work the same way.
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, 'utf8');
+    // fs.renameSync is atomic on POSIX and best-effort on Windows — the same caveat every other peaks
+    // artifact writer has; we accept it for parity.
+    renameSync(tmp, path);
+}
+/** A synthetic "allow" decision returned for tool calls the gate does not inspect. Uses a real
+ *  far-future date (year 9999) so the timestamp serializes safely. */
+function syntheticAllow() {
+    return {
+        operation: 'git-worktree',
+        reason: 'passthrough',
+        promptHash: null,
+        requestId: null,
+        issuedAt: '1970-01-01T00:00:00.000Z',
+        expiresAt: '9999-12-31T23:59:59.999Z',
+        consume: false,
+        consumed: true
+    };
+}
+/** CLI writer used by `peaks worktree auth grant`. Replaces (does not merge) the grant list — pass
+ *  the existing grants through if you want a multi-grant file. */
+export function writeAuthorization(projectRoot, sessionId, authorization) {
+    const existing = readAuthorization(projectRoot, sessionId);
+    const next = {
+        schemaVersion: 1,
+        sessionId,
+        createdAt: existing?.createdAt ?? new Date().toISOString(),
+        grants: [...(existing?.grants ?? []), authorization]
+    };
+    const path = worktreeAuthFilePath(projectRoot, sessionId);
+    writeAuthorizationAtomic(path, next);
+}
+/** Revoke (delete) every unconsumed grant in the file. Used by `peaks worktree auth revoke`. */
+export function clearAllGrants(projectRoot, sessionId) {
+    const file = readAuthorization(projectRoot, sessionId);
+    if (file === null)
+        return { removed: 0 };
+    const remaining = file.grants.filter((g) => g.consumed);
+    const removed = file.grants.length - remaining.length;
+    if (remaining.length === 0) {
+        const path = worktreeAuthFilePath(projectRoot, sessionId);
+        if (existsSync(path)) {
+            unlinkSync(path);
+        }
+        return { removed };
+    }
+    writeAuthorizationAtomic(worktreeAuthFilePath(projectRoot, sessionId), {
+        ...file,
+        grants: remaining
+    });
+    return { removed };
+}

package/dist/services/ide/adapters/claude-code-adapter.d.ts

@@ -0,0 +1,18 @@
+import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Claude Code adapter —— peaks-loop 的"起源 IDE"。
+ *
+ * 该 adapter 从原 `src/services/skills/hooks-settings-service.ts` 提取,保持
+ * 字节级兼容:用户在 Claude Code 环境下跑 `peaks hooks install` 产出的
+ * `.claude/settings.json` 与 refactor 前逐字节相同。
+ *
+ * 字段解释(见 PRD AC-1):
+ *   - dirName = '.claude'           : Claude Code 项目根下的 settings 目录
+ *   - settingsFileName = 'settings.json'
+ *   - envVar = 'CLAUDE_PROJECT_DIR' : Claude Code 注入的 env 变量,用于 ${...} 占位
+ *   - hookEvent = 'PreToolUse'      : Claude Code hook 数组 key
+ *   - toolMatcher = 'Bash' | 'Task' : PreToolUse 数组元素的 matcher 字段
+ *
+ * 不可消除的 per-IDE 字段(见 tech-doc.md §1.3)。
+ */
+export declare const CLAUDE_CODE_ADAPTER: IdeAdapter;

package/dist/services/ide/adapters/claude-code-adapter.js

@@ -0,0 +1,103 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { claudeCodeSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
+/**
+ * Claude Code adapter —— peaks-loop 的"起源 IDE"。
+ *
+ * 该 adapter 从原 `src/services/skills/hooks-settings-service.ts` 提取,保持
+ * 字节级兼容:用户在 Claude Code 环境下跑 `peaks hooks install` 产出的
+ * `.claude/settings.json` 与 refactor 前逐字节相同。
+ *
+ * 字段解释(见 PRD AC-1):
+ *   - dirName = '.claude'           : Claude Code 项目根下的 settings 目录
+ *   - settingsFileName = 'settings.json'
+ *   - envVar = 'CLAUDE_PROJECT_DIR' : Claude Code 注入的 env 变量,用于 ${...} 占位
+ *   - hookEvent = 'PreToolUse'      : Claude Code hook 数组 key
+ *   - toolMatcher = 'Bash' | 'Task' : PreToolUse 数组元素的 matcher 字段
+ *
+ * 不可消除的 per-IDE 字段(见 tech-doc.md §1.3)。
+ */
+export const CLAUDE_CODE_ADAPTER = {
+    id: 'claude-code',
+    displayName: 'Claude Code',
+    settings: {
+        dirName: '.claude',
+        settingsFileName: 'settings.json',
+        resolveSettingsFile: (scope, projectRoot) => {
+            const root = scope === 'global' ? homedir() : resolve(projectRoot ?? homedir());
+            return join(root, '.claude', 'settings.json');
+        },
+        supportsScope: () => true,
+    },
+    envVar: 'CLAUDE_PROJECT_DIR',
+    hookEvent: 'PreToolUse',
+    toolMatcher: 'Bash',
+    // Slice #009: Claude Code uses the `Task` tool for sub-agent dispatch.
+    // The CLI calls `claudeCodeSubAgentDispatcher.buildToolCall` to construct
+    // the exact args shape the `Task` tool expects.
+    subAgentDispatcher: claudeCodeSubAgentDispatcher,
+    // Slice #010 G9: Claude Code supports the PreToolUse hook event in a
+    // form that can wrap `peaks sub-agent-dispatch-guard` as a sub-command.
+    // Opt in to the G9 hook install.
+    promptSizeAware: true,
+    installHints: [
+        'Restart Claude Code (or reload the window) so the PreToolUse hooks take effect.'
+    ],
+    capabilities: {
+        gateEnforce: true,
+        statusline: true,
+    },
+    // v2.13.0 AC-1 + AC-3 MVP, slice 2026-07-02-auto-compact-zero-pause:
+    // Claude Code is the first IDE to fill the `compact` profile.
+    // Future adapters (trae / codex / cursor / qoder / tongyi-lingma /
+    // hermes / openclaw) follow the same shape — peaks-loop reads the
+    // env-var and dispatches the command via `IdeAdapter.compact`, with
+    // zero hard-coded IDE names anywhere in the orchestrator. If your
+    // IDE exposes a context-percent env-var and a slash-style compact
+    // command, register `compact` here and the auto-compact protocol
+    // activates.
+    //
+    // Pathway = 'ide-native' (not 'shell-exec') so the dispatcher
+    // routes main-session compacts through the PreToolUse hook in
+    // `.claude/settings.local.json`. The hook fires
+    // `peaks compact auto` on the NEXT Bash/Task tool
+    // call from the runner, which in-band spawns `claude --compact`
+    // against the CURRENT runner — not a child process (the
+    // shell-exec spawn-new-claude bug documented in
+    // `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`).
+    // Sub-agent shells still get the legacy shell-exec pathway via
+    // `dispatchIdeCompact({ target: 'sub-agent' })`.
+    compact: {
+        envVarForContextPercent: 'CLAUDE_CONTEXT_USAGE_PERCENT',
+        compactCommand: 'claude --compact',
+        compactPathway: 'ide-native',
+        postCompactDetectCommand: 'peaks compact auto --json'
+    },
+    // Slice #011: standards profile. Claude Code reads its constitution at
+    // CLAUDE.md + module-level rules under .claude/rules/**. The values mirror
+    // the hardcoded paths in `src/services/standards/project-standards-service.ts`
+    // (line 147 = '.claude', line 417/421 = 'CLAUDE.md' + '.claude/rules/...')
+    // and the postinstall target in `scripts/install-skills.mjs` (line 427 =
+    // '~/.claude/skills'). Filling the profile here makes the dispatch layer
+    // route to the SAME paths, so byte-stability on `peaks standards init` for
+    // Claude Code projects is preserved.
+    standardsProfile: {
+        rootFile: 'CLAUDE.md',
+        rulesDir: '.claude/rules',
+        rulesFileGlob: '**/*.md',
+        autoLoaded: true,
+        format: 'markdown',
+        migrationHint: 'Standards live at CLAUDE.md + .claude/rules/** for Claude Code.',
+    },
+    // Slice #011: skill install profile. The postinstall script symlinks
+    // bundled skills to `~/.claude/skills` and writes output-styles to
+    // `~/.claude/output-styles`, matching the existing hardcoded
+    // install-skills.mjs lines 427 + 488. The env-var back-compat name
+    // matches the legacy `PEAKS_CLAUDE_SKILLS_DIR` / `PEAKS_CLAUDE_OUTPUT_STYLES_DIR`.
+    skillInstall: {
+        skillsDir: join(homedir(), '.claude', 'skills'),
+        outputStylesDir: join(homedir(), '.claude', 'output-styles'),
+        installStrategy: 'symlink',
+        envVarOverride: 'PEAKS_CLAUDE_SKILLS_DIR',
+    },
+};

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

@@ -0,0 +1,46 @@
+import type { IdeAdapter } from '../ide-types.js';
+/**
+ * Codex (OpenAI CLI IDE) adapter —— peaks-loop 的第四个内置 IDE 适配器(slice #13, 2.4.0)。
+ *
+ * 不可消除的 per-IDE 字段(slice #1 锁定,same shape as trae-adapter.ts / cursor-adapter.ts):
+ *   - settings.dirName = '.codex'        : Codex 项目根下的配置目录
+ *   - settings.settingsFileName = 'settings.json'
+ *   - envVar = 'CODEX_PROJECT_DIR'  : Codex 注入的项目根 env 变量(用于 ${...} 占位)
+ *   - hookEvent = 'pre_tool_use'    : Codex 的 lowercase snake_case hook event(UNVERIFIED — see R-3)
+ *   - toolMatcher = 'shell'         : Codex 的 shell command matcher
+ *
+ * Slice #13 status (2026-06-17, 2.4.0):
+ *   - Adapter is the fourth built-in IDE in peaks-loop after Claude Code (#1),
+ *     Trae (#2), and Cursor (#12). It further confirms the slice #1 + slice #2
+ *     architecture scales linearly: registering a new IDE is a one-entry fill
+ *     of the slim `IdeAdapter` shape with no dispatch-chokepoint changes.
+ *   - 2 UNVERIFIED fields: `hookEvent` (Codex's `pre_tool_use` is the standard
+ *     lowercase snake_case pattern but not confirmed against a live Codex
+ *     install; see PRD R-3) and `envVar` (Codex's `CODEX_PROJECT_DIR` is the
+ *     most likely candidate). Both are annotated; the framework's fallback
+ *     path (legacy Claude Code install + stderr warning) handles UNVERIFIED
+ *     adapters without codepath changes.
+ *   - `promptSizeAware: false` — Codex's hook event semantics differ from
+ *     Claude's. Opt out of the G9 prompt-size gate until real-install
+ *     dogfood confirms hook layer compatibility (PRD R-3). The CLI 兜底
+ *     layer in `peaks sub-agent dispatch` still enforces the threshold
+ *     regardless — `promptSizeAware` only controls the hook layer.
+ *   - `capabilities.statusline: false` — Codex CLI does not have a
+ *     statusline UI surface. `peaks statusline install --ide codex` will
+ *     exit non-zero with a clear stderr message (CLI does NOT crash;
+ *     capability-check contract preserved per slice #008 P-5).
+ *   - Sub-agent dispatcher reuses `claudeCodeSubAgentDispatcher` by design
+ *     (slice #009 rationale — byte-level identical across adapters; per-IDE
+ *     divergence can be filled in a follow-up slice if Codex's sub-agent
+ *     shape is confirmed to differ).
+ *   - `standardsProfile` and `skillInstall` are intentionally UNVERIFIED —
+ *     real Codex install dogfood required. Until then, the bundled-skills
+ *     postinstall writes to `~/.claude/skills/` (legacy Claude Code fallback
+ *     per slice #011 framework), with a stderr warning. Users on Codex who
+ *     want skills visible to Codex's auto-loader must move the symlinks
+ *     to `~/.codex/skills/` manually (the warning text says so).
+ *   - L1 install scope default = `project` (writes to `<projectRoot>/.codex/settings.json`).
+ *     `--scope global` is the explicit global path; the L1 default is the
+ *     safer opt-in per slice #012 PRD scope clarification.
+ */
+export declare const CODEX_ADAPTER: IdeAdapter;