peaks-loop 4.1.2 → 4.1.3

package/dist/services/distribution/plugin-manifest.d.ts

@@ -0,0 +1,97 @@
+import { type SkillMetadata } from '../skills/skill-registry.js';
+/** Where the generator writes, relative to the package root. */
+export declare const PLUGIN_MANIFEST_RELATIVE_PATH = ".claude-plugin/marketplace.json";
+/**
+ * The server key peaks registers itself under. It is OUR key, not a harness's —
+ * the adapter profiles that name it (`IdeMcpInstallProfile.serverName`) and the
+ * tool-name templates that match it (`IdeAdapter.mcp`) must agree with this one,
+ * which is why it is declared once.
+ */
+export declare const MCP_SERVER_KEY = "peaks";
+/** The subset of `package.json` this render reads. */
+interface PackageManifest {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly author?: string;
+    readonly homepage?: string;
+    readonly repository?: {
+        readonly url?: string;
+    } | string;
+    readonly license?: string;
+    readonly keywords?: readonly string[];
+}
+/** One plugin entry's skill list item — the shape `peaks skill:visibility` reads. */
+interface PluginSkillEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly description: string;
+    readonly userInvocable?: boolean;
+}
+interface GeneratedPluginManifest {
+    readonly metadata: {
+        readonly pluginRoot: string;
+        readonly version: string;
+    };
+    readonly plugins: readonly {
+        readonly name: string;
+        readonly description: string;
+        readonly version: string;
+        readonly author: {
+            readonly name: string;
+        };
+        readonly homepage: string;
+        readonly repository: string;
+        readonly license: string;
+        readonly keywords: readonly string[];
+        /**
+         * Declared, and deliberately not brought live: the plugin channel is not
+         * published by this slice (PRD non-goal), so this is the statement of what
+         * the channel WOULD run, kept true by generation rather than by memory.
+         *
+         * The command is the CLI's own name and subcommand, with no path in it: a
+         * manifest is built on one machine and read on another, so an absolute
+         * interpreter path resolved here would be the build host's. The RUNTIME
+         * registration is a different artefact with a different consumer and does
+         * resolve the pair — see `mcp-install.ts::resolveMcpServerArgv`.
+         */
+        readonly mcpServers: Record<string, {
+            readonly command: string;
+            readonly args: readonly string[];
+        }>;
+        readonly skills: readonly PluginSkillEntry[];
+    }[];
+}
+/** `package.json`, parsed. A missing version is a refusal, not a default. */
+export declare function loadPackageManifest(root?: string): PackageManifest;
+/**
+ * The skill entries, in the registry's order.
+ *
+ * `visibility: internal` is the skill's own declaration that it is an internal
+ * role rather than a front door, and it is the ONE source for `userInvocable` —
+ * the field is emitted only when it is `false`, which is the contract
+ * `skill:visibility` reads ("internal: userInvocable false; public: omitted").
+ */
+export declare function skillEntriesOf(skills: readonly SkillMetadata[]): readonly PluginSkillEntry[];
+/**
+ * Render the manifest. `skills` is passed in rather than loaded here so the one
+ * caller that must fail loudly on an unreadable SKILL.md can do so once.
+ */
+export declare function generatePluginManifest(manifest: PackageManifest, skills: readonly SkillMetadata[]): GeneratedPluginManifest;
+/** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
+export declare function serializePluginManifest(manifest: GeneratedPluginManifest): string;
+/** Absolute path of the committed artifact for a package root. */
+export declare function pluginManifestPath(root?: string): string;
+/**
+ * The whole render for a package root: read the two sources, refuse a skill tree
+ * that did not fully parse, and serialize.
+ *
+ * The `failures` refusal is the load-bearing part. `loadSkillRegistry` reports an
+ * unreadable `SKILL.md` in a `failures` array instead of throwing, so a render
+ * that ignored it would DROP a skill from the manifest and still be
+ * byte-stable — a green CI over a manifest that had silently lost entries. A
+ * drift assertion cannot be stronger than its input, so the input is required to
+ * be complete.
+ */
+export declare function renderPluginManifest(root?: string): Promise<string>;
+export {};

package/dist/services/distribution/plugin-manifest.js

@@ -0,0 +1,126 @@
+// src/services/distribution/plugin-manifest.ts
+//
+// The plugin/distribution manifest as a GENERATED artefact (spec §4.1). One
+// source, two renders: the whitelist artifact is what the read-only claim is
+// made of, and this file is what the distribution channel is told.
+//
+// WHY IT IS GENERATED. The hand-authored `.claude-plugin/marketplace.json` had
+// rotted in the only two fields anybody could check and nobody did: it declared
+// version `2.0.3` while the package was `4.1.2`, and 12 skills while the tree
+// held 22. Root cause is not carelessness — it is that the current distribution
+// channel is `npm i -g`, so nothing ever read the plugin manifest and no failure
+// could be observed from it. A file whose author is a human and whose reader is
+// nobody will drift; the fix is to remove the human from the loop, not to be
+// more careful.
+//
+// CHANGE THE SOURCE, NOT THIS FILE. Everything below is derived, and
+// `tests/unit/services/distribution/plugin-manifest.test.ts` fails the moment
+// the committed artefact differs from a fresh render. A hand edit is therefore
+// not merely overwritten, it is RED. To change the manifest, change
+// `package.json` (a plugin-level field) or the skill's own `SKILL.md`
+// (a skill entry) and re-run `pnpm plugin:manifest`.
+//
+// DETERMINISM. No timestamp, no `Date`, no unordered iteration: skills come back
+// from `loadSkillRegistry`, which sorts by name, and every plugin-level field is
+// copied from `package.json` in a fixed order. Two consecutive runs are
+// byte-identical, which is what makes the CI equality assertion mean something.
+import { readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { repoRoot } from 'peaks-loop-shared/paths';
+import { loadSkillRegistry } from '../skills/skill-registry.js';
+/** Where the generator writes, relative to the package root. */
+export const PLUGIN_MANIFEST_RELATIVE_PATH = '.claude-plugin/marketplace.json';
+/**
+ * The server key peaks registers itself under. It is OUR key, not a harness's —
+ * the adapter profiles that name it (`IdeMcpInstallProfile.serverName`) and the
+ * tool-name templates that match it (`IdeAdapter.mcp`) must agree with this one,
+ * which is why it is declared once.
+ */
+export const MCP_SERVER_KEY = 'peaks';
+/** `package.json`, parsed. A missing version is a refusal, not a default. */
+export function loadPackageManifest(root = repoRoot) {
+    const parsed = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
+        throw new Error('package.json version must be a non-empty string');
+    }
+    return parsed;
+}
+/** A repository URL as a manifest reads it: npm's `.git` suffix is not part of the link. */
+function repositoryUrl(manifest) {
+    const raw = typeof manifest.repository === 'string' ? manifest.repository : manifest.repository?.url;
+    return (raw ?? '').replace(/\.git$/, '');
+}
+/** POSIX-separated, so the artifact is byte-identical whichever OS generated it. */
+function posix(value) {
+    return value.split('\\').join('/');
+}
+/**
+ * The skill entries, in the registry's order.
+ *
+ * `visibility: internal` is the skill's own declaration that it is an internal
+ * role rather than a front door, and it is the ONE source for `userInvocable` —
+ * the field is emitted only when it is `false`, which is the contract
+ * `skill:visibility` reads ("internal: userInvocable false; public: omitted").
+ */
+export function skillEntriesOf(skills) {
+    return skills
+        .filter((skill) => skill.name.startsWith('peaks-'))
+        .map((skill) => ({
+        name: skill.name,
+        path: `./${posix(relative(repoRoot, dirname(skill.skillPath)))}`,
+        description: skill.description,
+        ...(skill.visibility === 'internal' ? { userInvocable: false } : {})
+    }));
+}
+/**
+ * Render the manifest. `skills` is passed in rather than loaded here so the one
+ * caller that must fail loudly on an unreadable SKILL.md can do so once.
+ */
+export function generatePluginManifest(manifest, skills) {
+    return {
+        metadata: { pluginRoot: '.', version: manifest.version },
+        plugins: [
+            {
+                name: manifest.name,
+                description: manifest.description ?? '',
+                version: manifest.version,
+                author: { name: manifest.author ?? '' },
+                homepage: manifest.homepage ?? '',
+                repository: repositoryUrl(manifest),
+                license: manifest.license ?? '',
+                keywords: [...(manifest.keywords ?? [])],
+                mcpServers: {
+                    [MCP_SERVER_KEY]: { command: MCP_SERVER_KEY, args: ['mcp', 'serve'] }
+                },
+                skills: skillEntriesOf(skills)
+            }
+        ]
+    };
+}
+/** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
+export function serializePluginManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+/** Absolute path of the committed artifact for a package root. */
+export function pluginManifestPath(root = repoRoot) {
+    return join(root, PLUGIN_MANIFEST_RELATIVE_PATH);
+}
+/**
+ * The whole render for a package root: read the two sources, refuse a skill tree
+ * that did not fully parse, and serialize.
+ *
+ * The `failures` refusal is the load-bearing part. `loadSkillRegistry` reports an
+ * unreadable `SKILL.md` in a `failures` array instead of throwing, so a render
+ * that ignored it would DROP a skill from the manifest and still be
+ * byte-stable — a green CI over a manifest that had silently lost entries. A
+ * drift assertion cannot be stronger than its input, so the input is required to
+ * be complete.
+ */
+export async function renderPluginManifest(root = repoRoot) {
+    const skills = await loadSkillRegistry(join(root, 'skills'));
+    if (skills.failures.length > 0) {
+        const named = skills.failures.map((failure) => failure.skillPath).join(', ');
+        throw new Error(`Refusing to render the plugin manifest: unreadable skill(s): ${named}`);
+    }
+    return serializePluginManifest(generatePluginManifest(loadPackageManifest(root), skills.skills));
+}

package/dist/services/hooks/mcp-surface-gate.d.ts

@@ -0,0 +1,19 @@
+import type { ProgramIO } from '../../cli/cli-helpers.js';
+import type { IdeAdapter } from '../ide/ide-types.js';
+/** The tool names the proven surface declares. */
+export type McpSurfaceLookup = () => readonly string[];
+/** The production lookup. Injectable so a test can make it throw and watch the refusal. */
+export declare function lookupAllowedMcpTools(): readonly string[];
+/** The adapter whose harness sent this payload. */
+export declare function detectAdapter(parsedStdin: unknown): IdeAdapter;
+/** The deny emission, in the shape the host already treats as a hard block. */
+export declare function emitMcpDeny(io: ProgramIO, code: string, reason: string): void;
+/**
+ * Run the MCP branch over one parsed hook payload.
+ *
+ * @returns `true` when the call was BLOCKED (a deny has already been emitted).
+ *          `false` means "this is not an MCP call for this surface" — every
+ *          other tool name, and every harness declaring no MCP naming, lands
+ *          there and keeps the allow/deny result it had before.
+ */
+export declare function handleMcpSurfaceGate(io: ProgramIO, parsedStdin: unknown, lookup?: McpSurfaceLookup, adapterOf?: (payload: unknown) => IdeAdapter): boolean;

package/dist/services/hooks/mcp-surface-gate.js

@@ -0,0 +1,87 @@
+// src/services/hooks/mcp-surface-gate.ts
+//
+// L3 for the read-only MCP surface: the pre-tool branch that covers MCP tool
+// calls (spec §6.1, §6.2, §6.3).
+//
+// WHY IT IS ITS OWN MODULE. It shares an entry point with the Bash and worktree
+// branches but nothing else: different surface (an MCP tool name, not a command
+// text), different failure direction (fail-CLOSED, where the others fail open),
+// and a different thing it polices. Keeping it beside them made the interceptor
+// file carry three unrelated decisions; it lives here so the file that owns the
+// hook's control flow stays the file that owns the hook's control flow.
+//
+// WHAT IT POLICES, AND WHAT IT DOES NOT. It does not second-guess what a tool
+// would return. It answers one question: "is this MCP tool call one the proven
+// surface declares?" It exists for DRIFT — a stale server process, a hand-edited
+// harness config pointing somewhere else, a tool added to a config that was
+// never proved read-only. The read-only proof itself is L2's job; this is the
+// belt over it.
+//
+// FAIL-CLOSED, AND THE ASYMMETRY WITH THE BASH BRANCH IS DELIBERATE. The Bash
+// branch guards command TEXT, where a false block interrupts real work, so it
+// fails open. This branch guards CONFIG CONSISTENCY, where a false block costs
+// one call that should have been consistent while a false allow costs a call
+// that bypassed the chain. The costs are not the same size, so they do not share
+// a direction — and they do not share a `catch` either.
+//
+// IT READS THE SURFACE AS DATA, NEVER AS CODE. The allowed tool names come from
+// the generated whitelist artifact through its loader, so this branch keeps
+// working when `src/services/mcp/` is deleted (spec §1) — which is also what
+// `tests/unit/standards/no-mcp-source-import.test.ts` enforces mechanically.
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { emitBlock } from './output.js';
+import { getAdapter } from '../ide/ide-registry.js';
+import { detectIdeFromContext, parseClaudeShapeStdin } from '../ide/hook-translator.js';
+import { matchMcpToolName } from '../ide/mcp-tool-matcher.js';
+import { loadReadOnlyWhitelist, toolIdsOf } from '../readonly-surface/readonly-whitelist.js';
+/** The production lookup. Injectable so a test can make it throw and watch the refusal. */
+export function lookupAllowedMcpTools() {
+    return toolIdsOf(loadReadOnlyWhitelist());
+}
+/** The adapter whose harness sent this payload. */
+export function detectAdapter(parsedStdin) {
+    const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin });
+    return getAdapter(ide);
+}
+/** The deny emission, in the shape the host already treats as a hard block. */
+export function emitMcpDeny(io, code, reason) {
+    emitBlock(io, `[mcp-surface-gate:${code}] ${reason}. Blocked by fail-closed policy — ` +
+        'run the read-only command through the CLI instead, or add its argv to ' +
+        'contracts/readonly-surface.json and regenerate the whitelist.');
+}
+/**
+ * Run the MCP branch over one parsed hook payload.
+ *
+ * @returns `true` when the call was BLOCKED (a deny has already been emitted).
+ *          `false` means "this is not an MCP call for this surface" — every
+ *          other tool name, and every harness declaring no MCP naming, lands
+ *          there and keeps the allow/deny result it had before.
+ */
+export function handleMcpSurfaceGate(io, parsedStdin, lookup = lookupAllowedMcpTools, adapterOf = detectAdapter) {
+    let adapter;
+    try {
+        adapter = adapterOf(parsedStdin);
+    }
+    catch (error) {
+        // Detection itself failed. Falling through would let the call pass
+        // unchecked, which is the one outcome this branch exists to prevent.
+        emitMcpDeny(io, 'IDE_DETECTION_FAILED', `the harness could not be identified (${getErrorMessage(error)})`);
+        return true;
+    }
+    const { toolName } = parseClaudeShapeStdin(parsedStdin);
+    const match = toolName === undefined ? undefined : matchMcpToolName(adapter, toolName);
+    if (match === undefined)
+        return false;
+    let allowed;
+    try {
+        allowed = lookup();
+    }
+    catch (error) {
+        emitMcpDeny(io, 'SURFACE_UNREADABLE', `the read-only surface could not be read (${getErrorMessage(error)})`);
+        return true;
+    }
+    if (allowed.includes(match.toolId))
+        return false;
+    emitMcpDeny(io, 'NOT_IN_READONLY_SURFACE', `"${toolName}" is not one of the read-only tools this project declares (${allowed.join(', ') || 'none'})`);
+    return true;
+}

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

@@ -1,39 +1,8 @@
 import type { IdeAdapter } from '../ide-types.js';
-/**
- * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
- * session id, searching `~/.claude/projects/**` recursively.
- *
- * `peaks code context-audit` reuses THIS locator instead of re-implementing
- * the recursive find. Returns `null` when the transcript does not exist —
- * callers MUST treat that as "unavailable", never as an error.
- */
-export declare function resolveClaudeTranscriptPath(outerSessionId: string, projectsDir?: string): string | null;
-/**
- * Resolve the currently-active Claude Code model id from a runtime env map.
- * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or
- * `undefined` when none is present. Pure + exported for tests; the caller falls
- * back to the transcript `message.model` when this returns undefined.
- */
-export declare function resolveClaudeModelFromEnv(env: NodeJS.ProcessEnv | undefined): string | undefined;
-/**
- * Model-aware context-window size in tokens.
- *
- * Detection rule (documented):
- *   1. Empty / unknown model → DEFAULT_CONTEXT_WINDOW_TOKENS (200_000).
- *   2. Suffix heuristic — a model id containing `1m` (case-insensitive) is
- *      treated as 1M-context.
- *   3. Explicit allowlist — known 1M Claude model ids
- *      (ONE_MILLION_CONTEXT_MODELS).
- *   4. Everything else → 200_000 (the safe default).
- *
- * Callers MAY additionally infer ≥1M from the observed token count: if
- * `contextTokens > DEFAULT_CONTEXT_WINDOW_TOKENS`, the model cannot be a
- * 200K model and must be ≥1M (see `readClaudeTranscriptEstimate`).
- *
- * This is the HEURISTIC layer only. Explicit user overrides sit ABOVE it —
- * see `resolveContextWindow`, which is what the probe actually calls.
- */
-export declare function modelContextWindowTokens(model: string): number;
+import { resolveClaudeTranscriptPath } from './claude-code-local-state.js';
+import { modelContextWindowTokens, resolveClaudeModelFromEnv } from './claude-code-model-window.js';
+export { resolveClaudeTranscriptPath };
+export { modelContextWindowTokens, resolveClaudeModelFromEnv };
 /**
  * the context-window size in tokens. Third-party / proxied models whose id
  * carries no `[1M]` suffix (and is absent from the hardcoded allowlist) are

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

@@ -1,7 +1,16 @@
-import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { claudeCodeSubAgentDispatcher } from '../../dispatch/sub-agent-dispatcher.js';
+import { findTranscriptJsonl, readClaudeStatuslinePercent, resolveClaudeTranscriptPath } from './claude-code-local-state.js';
+import { DEFAULT_CONTEXT_WINDOW_TOKENS, ONE_MILLION_CONTEXT_TOKENS, modelContextWindowTokens, resolveClaudeModelFromEnv } from './claude-code-model-window.js';
+// Re-exported so the public surface of this module is unchanged by the split:
+// the readers live in `claude-code-local-state.ts` now, but every existing
+// importer keeps resolving them from here.
+export { resolveClaudeTranscriptPath };
+// Likewise the model-id / window-size pair, which moved into
+// `claude-code-model-window.ts` to make room for `mcpInstall` below.
+export { modelContextWindowTokens, resolveClaudeModelFromEnv };
 /**
  * Claude Code adapter —— peaks-loop 的"起源 IDE"。
  *
@@ -17,178 +26,8 @@ import { claudeCodeSubAgentDispatcher } from '../../dispatch/sub-agent-dispatche
  *
  * 不可消除的 per-IDE 字段(见 tech-doc.md §1.3)。
  */
-/**
- * Read Claude Code's statusline state file
- * (`~/.claude/statusline-state.json`) and parse a context-percent key.
- * Moved from the generic reader in slice
- * only in the Claude Code adapter.
- */
-function readClaudeStatuslinePercent() {
-    const path = join(homedir(), '.claude', 'statusline-state.json');
-    if (!existsSync(path))
-        return null;
-    try {
-        const json = JSON.parse(readFileSync(path, 'utf8'));
-        const candidates = ['contextPercent', 'context_usage_percent', 'contextPercentUsed'];
-        for (const key of candidates) {
-            const raw = json[key];
-            if (typeof raw === 'number' && Number.isFinite(raw)) {
-                return raw > 1.5 ? raw / 100 : Math.max(0, Math.min(1, raw));
-            }
-        }
-    }
-    catch (err) {
-        // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
-        if (err instanceof ReferenceError)
-            throw err; // surface module-load bugs
-        if (err instanceof SyntaxError)
-            throw err; // surface parse bugs (e.g. broken statusline JSON)
-        return null; // only swallow IO errors
-    }
-    return null;
-}
-/**
- * Recursive search for `<outerSessionId>.jsonl` under `projectsDir`. The
- * Mac layout encodes the cwd as a single hash directory; on Mac Claude Code
- * nests the transcript under that hash with an extra level of subdirectory we
- * cannot predict ahead of time. A flat readdir misses that branch and returns
- * null — the silent-failure mode this recursion closes.
- *
- * Moved from the generic reader in slice
- * session id (Claude Code names its transcript by the outer session UUID),
- * NOT the peaks session id.
- */
-function findTranscriptJsonl(projectsDir, outerSessionId) {
-    if (!existsSync(projectsDir))
-        return null;
-    try {
-        const stack = [projectsDir];
-        while (stack.length > 0) {
-            const dir = stack.pop();
-            if (dir === undefined)
-                break;
-            const entries = readdirSync(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                const full = join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    stack.push(full);
-                }
-                else if (entry.isFile() && entry.name === `${outerSessionId}.jsonl`) {
-                    return full;
-                }
-            }
-        }
-    }
-    catch (err) {
-        // TODO(g2): legacy silent catch — now narrows to IO errors only (grace: 1 minor release, v2.14.0)
-        if (err instanceof ReferenceError)
-            throw err; // surface module-load bugs
-        if (err instanceof SyntaxError)
-            throw err; // surface parse bugs
-        return null; // only swallow IO errors
-    }
-    return null;
-}
-/**
- * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
- * session id, searching `~/.claude/projects/**` recursively.
- *
- * `peaks code context-audit` reuses THIS locator instead of re-implementing
- * the recursive find. Returns `null` when the transcript does not exist —
- * callers MUST treat that as "unavailable", never as an error.
- */
-export function resolveClaudeTranscriptPath(outerSessionId, projectsDir = join(homedir(), '.claude', 'projects')) {
-    if (typeof outerSessionId !== 'string' || outerSessionId.length === 0)
-        return null;
-    return findTranscriptJsonl(projectsDir, outerSessionId);
-}
-/** 1M-context window size in tokens (documented single choice: 1,000,000). */
-const ONE_MILLION_CONTEXT_TOKENS = 1_000_000;
-/** Safe-default (non-1M) context window size in tokens. */
-const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
 /** Reverse-scan chunk size in bytes (keeps memory bounded on multi-MB transcripts). */
 const TRANSCRIPT_SCAN_CHUNK_BYTES = 64 * 1024;
-/**
- * Known 1M-context Claude model id prefixes whose ids do NOT carry a `1m`
- * suffix (e.g. `claude-sonnet-4-5-20250929`). The substring match is
- * intentionally generous — every `claude-sonnet-4*` / `claude-opus-4*`
- * variant is 1M-context.
- */
-const ONE_MILLION_CONTEXT_MODELS = ['claude-opus-4', 'claude-sonnet-4'];
-/**
- * Claude Code runtime env vars that may carry the currently-active model id,
- * in documented precedence order (first non-empty value wins):
- *   1. ANTHROPIC_MODEL                — explicit per-run model override
- *   2. ANTHROPIC_DEFAULT_OPUS_MODEL   — default Opus fallback
- *   3. ANTHROPIC_DEFAULT_SONNET_MODEL — default Sonnet fallback
- *   4. ANTHROPIC_DEFAULT_HAIKU_MODEL  — default Haiku fallback
- *   5. ANTHROPIC_DEFAULT_FABLE_MODEL  — default Fable fallback
- *   6. CLAUDE_CODE_SUBAGENT_MODEL     — sub-agent model (used when the others
- *                                       are absent, e.g. a sub-agent-only env)
- *
- * Why env-first: the transcript's `message.model` often drops Claude Code's
- * `[1M]` / `[200K]` suffix marker (observed: `deepseek-v4-flash`), while the
- * runtime env vars above carry it (`deepseek-v4-flash[1M]`). Reading them
- * first lets the window resolver see the true context window. This family is
- * vendor-specific, so it lives ONLY in the claude-code adapter.
- */
-const CLAUDE_CODE_MODEL_ENV_VARS = [
-    'ANTHROPIC_MODEL',
-    'ANTHROPIC_DEFAULT_OPUS_MODEL',
-    'ANTHROPIC_DEFAULT_SONNET_MODEL',
-    'ANTHROPIC_DEFAULT_HAIKU_MODEL',
-    'ANTHROPIC_DEFAULT_FABLE_MODEL',
-    'CLAUDE_CODE_SUBAGENT_MODEL'
-];
-/**
- * Resolve the currently-active Claude Code model id from a runtime env map.
- * Returns the first non-empty `CLAUDE_CODE_MODEL_ENV_VARS` value (trimmed), or
- * `undefined` when none is present. Pure + exported for tests; the caller falls
- * back to the transcript `message.model` when this returns undefined.
- */
-export function resolveClaudeModelFromEnv(env) {
-    if (!env)
-        return undefined;
-    for (const name of CLAUDE_CODE_MODEL_ENV_VARS) {
-        const value = env[name];
-        if (typeof value === 'string') {
-            const trimmed = value.trim();
-            if (trimmed.length > 0)
-                return trimmed;
-        }
-    }
-    return undefined;
-}
-/**
- * Model-aware context-window size in tokens.
- *
- * Detection rule (documented):
- *   1. Empty / unknown model → DEFAULT_CONTEXT_WINDOW_TOKENS (200_000).
- *   2. Suffix heuristic — a model id containing `1m` (case-insensitive) is
- *      treated as 1M-context.
- *   3. Explicit allowlist — known 1M Claude model ids
- *      (ONE_MILLION_CONTEXT_MODELS).
- *   4. Everything else → 200_000 (the safe default).
- *
- * Callers MAY additionally infer ≥1M from the observed token count: if
- * `contextTokens > DEFAULT_CONTEXT_WINDOW_TOKENS`, the model cannot be a
- * 200K model and must be ≥1M (see `readClaudeTranscriptEstimate`).
- *
- * This is the HEURISTIC layer only. Explicit user overrides sit ABOVE it —
- * see `resolveContextWindow`, which is what the probe actually calls.
- */
-export function modelContextWindowTokens(model) {
-    const m = model.trim().toLowerCase();
-    if (m.length === 0)
-        return DEFAULT_CONTEXT_WINDOW_TOKENS;
-    if (m.includes('1m'))
-        return ONE_MILLION_CONTEXT_TOKENS;
-    for (const known of ONE_MILLION_CONTEXT_MODELS) {
-        if (m.includes(known))
-            return ONE_MILLION_CONTEXT_TOKENS;
-    }
-    return DEFAULT_CONTEXT_WINDOW_TOKENS;
-}
 /**
  * the context-window size in tokens. Third-party / proxied models whose id
  * carries no `[1M]` suffix (and is absent from the hardcoded allowlist) are
@@ -602,6 +441,44 @@ export const CLAUDE_CODE_ADAPTER = {
     envVar: 'CLAUDE_PROJECT_DIR',
     hookEvent: 'PreToolUse',
     toolMatcher: 'Bash',
+    // BOTH channels a peaks MCP server can reach this harness through. The hook
+    // entry installed below covers the pair, and the pre-tool branch matches
+    // against the pair; one template would leave the other channel unenforced and
+    // nobody would notice, because a matcher that never fires looks like a clean
+    // call.
+    mcp: {
+        toolNameTemplates: ['mcp__peaks__*', 'mcp__plugin_peaks-loop_peaks__*']
+    },
+    // How this harness REGISTERS a peaks MCP server. The entry
+    // is the harness's OWN verb, not a hand-edit of its config file, which is
+    // full of the user's state (spec §8.3). The shape is recorded in spec §13 —
+    // it is read off that table, not invented here:
+    //   - the `--` before the server argv is LOAD-BEARING: everything after it is
+    //     passed to the server verbatim, otherwise the harness reads the server's
+    //     own flags as its own;
+    //   - the verb is NOT idempotent — same name, same scope fails, with no
+    //     `--force` and no `update` — which is why the engine removes first.
+    // `scopes` is `user` alone: that is the scope a peaks install writes (spec
+    // §8.4), and sweeping a scope peaks never wrote would delete a user's own
+    // entry under the same name.
+    mcpInstall: {
+        serverName: 'peaks',
+        scopes: ['user'],
+        targetScope: 'user',
+        addArgv: [
+            'claude',
+            'mcp',
+            'add',
+            '--scope',
+            '<scope>',
+            '--transport',
+            'stdio',
+            '<name>',
+            '--',
+            '<server-argv>'
+        ],
+        removeArgv: ['claude', 'mcp', 'remove', '<name>', '--scope', '<scope>']
+    },
     // 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.

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

@@ -0,0 +1,28 @@
+/**
+ * Read Claude Code's statusline state file
+ * (`~/.claude/statusline-state.json`) and parse a context-percent key.
+ * Moved from the generic reader in slice
+ * only in the Claude Code adapter.
+ */
+export declare function readClaudeStatuslinePercent(): number | null;
+/**
+ * Recursive search for `<outerSessionId>.jsonl` under `projectsDir`. The
+ * Mac layout encodes the cwd as a single hash directory; on Mac Claude Code
+ * nests the transcript under that hash with an extra level of subdirectory we
+ * cannot predict ahead of time. A flat readdir misses that branch and returns
+ * null — the silent-failure mode this recursion closes.
+ *
+ * Moved from the generic reader in slice
+ * session id (Claude Code names its transcript by the outer session UUID),
+ * NOT the peaks session id.
+ */
+export declare function findTranscriptJsonl(projectsDir: string, outerSessionId: string): string | null;
+/**
+ * Resolve the absolute path of a Claude Code transcript jsonl by OUTER
+ * session id, searching `~/.claude/projects/**` recursively.
+ *
+ * `peaks code context-audit` reuses THIS locator instead of re-implementing
+ * the recursive find. Returns `null` when the transcript does not exist —
+ * callers MUST treat that as "unavailable", never as an error.
+ */
+export declare function resolveClaudeTranscriptPath(outerSessionId: string, projectsDir?: string): string | null;