@compaction/cli 0.2.0 → 0.3.1

package/dist/core/capture-record.js

@@ -0,0 +1,55 @@
+/**
+ * Shared content-free record step for the unified capture→compact→record→report flow (PUBLIC CLI/SDK).
+ * Design: `docs/design/unified-run-flow.md` (accepted 2026-06-28).
+ *
+ * After any tool's capture (Codex live wrapper, Claude Code capture/hook, …) this records a CONTENT-FREE
+ * usage event to the hosted control-plane: `provider_metadata {tool, provider, model}` + `token_usage`
+ * with **input and output counted SEPARATELY** and an honest **`token_source`**
+ * (provider-reported | local-estimate). It uploads NO trace content (metrics_only) and only runs when the
+ * user has configured the hosted path (URL + key) — never a default network call.
+ *
+ * Honesty rails (founder D2, 2026-06-28): the three axes stay distinct — provider-reported vs
+ * locally-observed/estimated vs SAVINGS. This records tokens (input + output) with their source; it does
+ * NOT compute or send any output-savings figure (output savings stay unavailable until the output-shaping
+ * policy family produces measured + eval-confirmed evidence).
+ */
+import { buildOptimizeRequest, sendRequest } from "./api-client/index.js";
+/** Map a capture's UsageMetadata to the honest wire token source. */
+export function captureTokenSource(usage) {
+    if (usage.provider_reported_tokens)
+        return "provider-reported";
+    if (usage.estimated_tokens)
+        return "local-estimate";
+    return "unknown";
+}
+/** Build the CONTENT-FREE (`metrics_only`) record request. Input/output sent separately; honest source. */
+export function buildCaptureRecordRequest(opts) {
+    return buildOptimizeRequest({
+        trace: { redacted: true, reference: opts.reference },
+        payloadClass: "metrics_only",
+        tokenSource: captureTokenSource(opts.usage),
+        ...(typeof opts.usage.input_tokens === "number" ? { inputTokens: opts.usage.input_tokens } : {}),
+        ...(typeof opts.usage.output_tokens === "number" ? { outputTokens: opts.usage.output_tokens } : {}),
+        ...(opts.usage.provider ? { provider: opts.usage.provider } : {}),
+        ...(opts.usage.model ? { model: opts.usage.model } : {}),
+        tool: opts.tool,
+        optimizationMode: "recommend"
+    });
+}
+/**
+ * Send the content-free record. Best-effort: a transport/HTTP failure returns `recorded: false` with a
+ * sanitized reason (never the key, headers, or body) — it must NEVER fail the user's capture.
+ */
+export async function recordCaptureContentFree(config, opts) {
+    const source = captureTokenSource(opts.usage);
+    try {
+        const response = await sendRequest(config, "/v0/optimize", buildCaptureRecordRequest(opts));
+        if (!response.ok)
+            return { recorded: false, reason: `hosted record rejected (HTTP ${response.status})` };
+        return { recorded: true, tool: opts.tool, source };
+    }
+    catch {
+        return { recorded: false, reason: "could not reach the hosted API (transport error)" };
+    }
+}
+//# sourceMappingURL=capture-record.js.map

package/dist/core/claude-code-before-call.d.ts

@@ -0,0 +1,37 @@
+import { type ActivityEvent } from "./activity-event.js";
+import { type AvoidableContextResult } from "./before-call.js";
+/**
+ * The proven apply blocker for the Claude Code before-call surface (run-13). Recorded verbatim on every
+ * recommendation event's caveats so no reader upgrades a recommendation into an apply claim.
+ */
+export declare const CLAUDE_CODE_BEFORE_CALL_APPLY_BLOCKER: string;
+/** The parsed, content-free-by-caller fields of a UserPromptSubmit hook payload. */
+export interface ClaudeCodePromptHookPayload {
+    /** The submitted user prompt text (analyzed IN-PROCESS; NEVER persisted). */
+    prompt: string;
+    /** The project working directory the hook ran in (activity is scoped under `<cwd>/.compaction`). */
+    cwd?: string;
+    /** The Claude Code session id (content-free identity), when present. */
+    sessionId?: string;
+}
+/**
+ * Parse the UserPromptSubmit hook JSON (from stdin). FAIL-CLOSED: returns `null` on any problem (not
+ * JSON, not an object, wrong `hook_event_name`, or no string `prompt`) so a malformed payload records
+ * nothing and can never break the fail-open hook. Only the fields we need are read; unknown keys ignored.
+ */
+export declare function parseUserPromptSubmitPayload(raw: string): ClaudeCodePromptHookPayload | null;
+/**
+ * Build ONE content-free `claude_code` BEFORE-CALL RECOMMENDATION activity event from the tool-agnostic
+ * analysis `result`. RECOMMENDATION-ONLY in every field:
+ * - input is a LOCAL-ESTIMATE (chars/4) pre-call figure; output is unavailable-with-reason (no output
+ *   exists before the call). Never provider-reported, never billing-confirmed, never a saving.
+ * - `approval_status: "not-required"` — nothing was applied, so nothing needed approval (and nothing
+ *   COULD be approved: apply is a proven blocker on this surface).
+ * - `auto_apply.applied_automatically: false` (auto-apply is OFF, structurally).
+ * - `recovery.original_retained: true` — the original prompt ran UNCHANGED (never mutated).
+ * - `sync_status: "local-only"`.
+ * The apply blocker rides verbatim on the caveats. CONTENT-FREE: only counts/policy/labels/opaque ids.
+ */
+export declare function buildClaudeCodeBeforeCallEvent(result: AvoidableContextResult, opts?: {
+    sessionId?: string;
+}): ActivityEvent;

package/dist/core/claude-code-before-call.js

@@ -0,0 +1,120 @@
+/**
+ * Claude Code BEFORE-CALL recommendation core (PUBLIC CLI/SDK code — engine-free, ships in the npm
+ * package). Charter 2026-07-04-run-13 — the FIRST genuine before-call surface for Claude Code.
+ *
+ * Run-8 gave Claude Code always-on MEASUREMENT via the **Stop hook**, which fires at session END — it
+ * cannot observe a call before it happens. Run-13 uses a DIFFERENT, genuinely pre-call hook:
+ * **UserPromptSubmit**, which fires when the user submits a prompt, BEFORE Claude processes it
+ * (empirically verified against Claude Code 2.1.198: the payload carries `prompt`, `transcript_path`,
+ * `cwd`, `session_id`; exit 2 blocks the prompt before any model call).
+ *
+ * SCOPE = RECOMMENDATION-ONLY, and APPLY IS A PROVEN BLOCKER on this surface:
+ * - No Claude Code hook can make the model receive a REDUCED/compacted context. `UserPromptSubmit` can
+ *   only ADD context (`additionalContext`) or BLOCK (exit 2); there is no `updatedPrompt`/context-reduce
+ *   field on any hook (`PreToolUse` rewrites TOOL input only, not the conversation; `PreCompact` can only
+ *   block). So Compaction cannot safely mutate what the model receives — apply is fail-closed.
+ * - Hooks are NON-INTERACTIVE (stdin carries the JSON payload; there is no TTY), so the ask-before-apply
+ *   `[y/n/v]` UX that Codex's stdin path uses is impossible here. There is nothing to approve because
+ *   nothing can be applied.
+ *
+ * This module therefore only OBSERVES the pending prompt (in-process, content-free), runs the SAME
+ * deterministic duplicate-context detector, and — when avoidable context is present — records ONE
+ * metrics-only `claude_code` activity event surfacing the recommendation. The original prompt ALWAYS
+ * runs UNCHANGED. This is NOT the Stop-hook path and makes NO before-call claim on the Stop hook.
+ */
+import { createHash } from "node:crypto";
+import { createUsageMetadata } from "./usage-metadata.js";
+import { buildRunFlowTokenReport } from "./run-flow-report.js";
+import { buildRunCrossSurfaceEvent } from "./cross-surface-event.js";
+import { computeActivityEventId } from "./activity-event.js";
+import { BEFORE_CALL_REDUCTION_LABEL } from "./before-call.js";
+/**
+ * The proven apply blocker for the Claude Code before-call surface (run-13). Recorded verbatim on every
+ * recommendation event's caveats so no reader upgrades a recommendation into an apply claim.
+ */
+export const CLAUDE_CODE_BEFORE_CALL_APPLY_BLOCKER = "before-call APPLY is UNAVAILABLE on Claude Code hooks: no hook can make the model receive reduced " +
+    "context (UserPromptSubmit can only ADD context or BLOCK — there is no updatedPrompt/context-reduce " +
+    "field; PreToolUse rewrites TOOL input only; PreCompact can only block), and hooks are non-interactive " +
+    "so ask-before-apply is impossible. This is RECOMMENDATION-ONLY; the original prompt runs UNCHANGED.";
+/** The honest reason the OUTPUT axis is unavailable at pre-call time on the Claude Code surface. */
+const OUTPUT_UNAVAILABLE_REASON = "no output tokens exist before the call; Claude Code reports usage only after the model responds";
+/**
+ * Parse the UserPromptSubmit hook JSON (from stdin). FAIL-CLOSED: returns `null` on any problem (not
+ * JSON, not an object, wrong `hook_event_name`, or no string `prompt`) so a malformed payload records
+ * nothing and can never break the fail-open hook. Only the fields we need are read; unknown keys ignored.
+ */
+export function parseUserPromptSubmitPayload(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const p = parsed;
+    // If a hook_event_name is present it MUST be UserPromptSubmit (defensive against a mis-wired hook).
+    if (p.hook_event_name !== undefined && p.hook_event_name !== "UserPromptSubmit")
+        return null;
+    if (typeof p.prompt !== "string")
+        return null;
+    return {
+        prompt: p.prompt,
+        ...(typeof p.cwd === "string" ? { cwd: p.cwd } : {}),
+        ...(typeof p.session_id === "string" ? { sessionId: p.session_id } : {})
+    };
+}
+/** A content-free, deterministic run id from the local-estimate counts (never any content). */
+function contentFreeRunId(before, after) {
+    const digest = createHash("sha256").update(`before-call|claude_code|${before}|${after}`).digest("hex");
+    return `before-call-claude_code-${digest.slice(0, 16)}`;
+}
+/**
+ * Build ONE content-free `claude_code` BEFORE-CALL RECOMMENDATION activity event from the tool-agnostic
+ * analysis `result`. RECOMMENDATION-ONLY in every field:
+ * - input is a LOCAL-ESTIMATE (chars/4) pre-call figure; output is unavailable-with-reason (no output
+ *   exists before the call). Never provider-reported, never billing-confirmed, never a saving.
+ * - `approval_status: "not-required"` — nothing was applied, so nothing needed approval (and nothing
+ *   COULD be approved: apply is a proven blocker on this surface).
+ * - `auto_apply.applied_automatically: false` (auto-apply is OFF, structurally).
+ * - `recovery.original_retained: true` — the original prompt ran UNCHANGED (never mutated).
+ * - `sync_status: "local-only"`.
+ * The apply blocker rides verbatim on the caveats. CONTENT-FREE: only counts/policy/labels/opaque ids.
+ */
+export function buildClaudeCodeBeforeCallEvent(result, opts = {}) {
+    const usage = createUsageMetadata({
+        inputTokens: result.input_tokens_before,
+        providerReportedTokens: false,
+        estimatedTokens: true,
+        limitations: [BEFORE_CALL_REDUCTION_LABEL]
+    });
+    const tokenReport = buildRunFlowTokenReport({ tool: "claude-code", usage, outputStatus: "unavailable" });
+    const base = buildRunCrossSurfaceEvent("claude_code", {
+        runId: contentFreeRunId(result.input_tokens_before, result.input_tokens_after_estimate),
+        tokenReport,
+        reasons: { output: OUTPUT_UNAVAILABLE_REASON }
+    });
+    const withSession = opts.sessionId ? { ...base, session_id: opts.sessionId } : base;
+    const activity = {
+        ...withSession,
+        // The compacted local-estimate is the pre-call INPUT AFTER figure — a recommended (un-applied)
+        // local-estimate delta, never a saving, never provider-reported.
+        input_after: result.input_tokens_after_estimate,
+        policy_used: result.policy,
+        evidence_level: result.evidence_label,
+        caveats: [
+            ...(base.caveats ?? []),
+            "before-call RECOMMENDATION-ONLY (Claude Code UserPromptSubmit hook, a genuine PRE-call event — " +
+                "NOT the post-session Stop hook): the original prompt runs UNCHANGED; nothing was applied",
+            CLAUDE_CODE_BEFORE_CALL_APPLY_BLOCKER,
+            "local-estimate pre-call delta (chars/4), NOT a saving / NOT provider-reported / NOT billing-confirmed"
+        ],
+        approval_status: "not-required",
+        auto_apply: { eligible: result.has_avoidable_context, preference: "ask-each-time", applied_automatically: false },
+        recovery: { original_retained: true },
+        sync_status: "local-only"
+    };
+    return { ...activity, activity_event_id: computeActivityEventId(activity) };
+}
+//# sourceMappingURL=claude-code-before-call.js.map

package/dist/core/claude-code-connect.d.ts

@@ -0,0 +1,31 @@
+import { type ClaudeSettings } from "./claude-code-hooks.js";
+/** The outcome of a connect attempt. `verified` is the ONLY thing a "connected" claim may rest on. */
+export type ConnectClaudeCodeStatus = "installed" | "already-present" | "dry-run" | "verify-failed" | "error";
+export interface ConnectClaudeCodeResult {
+    status: ConnectClaudeCodeStatus;
+    /** The settings file targeted (project `.claude/settings.json` by default, or `~/.claude/...`). */
+    settingsPath: string;
+    /** Whether the settings file already existed before this attempt. */
+    existed: boolean;
+    /** TRUE only when a re-read of the file confirms Compaction's Stop hook is present. */
+    verified: boolean;
+    /** The exact hook command that was (or would be) installed. */
+    hookCommand: string;
+    /** Present on `error`: the honest reason the install was refused (nothing was written). */
+    error?: string;
+    /** Present on `dry-run`: the settings that WOULD be written (nothing was written). */
+    wouldWrite?: ClaudeSettings;
+}
+export interface ConnectClaudeCodeOptions {
+    /** The settings file to install into. */
+    settingsPath: string;
+    /** Preview only: compute + report the merge, write NOTHING. */
+    dryRun?: boolean;
+}
+/**
+ * Install (or confirm) Compaction's Claude Code Stop hook in `settingsPath`, then VERIFY by
+ * re-reading the file. Returns a structured result; NEVER throws for the malformed-settings case
+ * (that is reported as `status: "error"` with nothing written) so the connect UX stays a clean
+ * one-liner. The only status the caller may present as "connected" is one with `verified: true`.
+ */
+export declare function connectClaudeCodeHook(options: ConnectClaudeCodeOptions): Promise<ConnectClaudeCodeResult>;

package/dist/core/claude-code-connect.js

@@ -0,0 +1,87 @@
+/**
+ * Connect-once installer for the Claude Code Stop hook (PUBLIC CLI/SDK code, engine-free).
+ *
+ * `compaction init --connect 1` uses this to ACTUALLY install the consented Stop hook (reusing the
+ * same pure `installStopHook` merge that `compaction hooks install` uses) and then VERIFY the write
+ * landed by RE-READING the settings file and confirming Compaction's hook entry is present. The
+ * connect flow may only claim "connected" when `verified` is true — a failed or unverified install
+ * is reported honestly with the one exact command to run manually, never as success.
+ *
+ * Consent + safety (identical posture to `hooks install`): running the connect command IS the
+ * consent; the merge NEVER replaces existing settings and is idempotent; `--dry-run` writes nothing;
+ * a malformed settings file is refused (left untouched), not clobbered. Local file I/O only — no
+ * network, no new dependency.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CLAUDE_CODE_HOOK_COMMAND, hasCompactionStopHook, installStopHook } from "./claude-code-hooks.js";
+async function readSettings(file) {
+    try {
+        const raw = await readFile(file, "utf8");
+        const parsed = JSON.parse(raw);
+        return { settings: parsed && typeof parsed === "object" ? parsed : {}, existed: true };
+    }
+    catch {
+        return { settings: {}, existed: false };
+    }
+}
+async function writeSettings(file, settings) {
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+/**
+ * Install (or confirm) Compaction's Claude Code Stop hook in `settingsPath`, then VERIFY by
+ * re-reading the file. Returns a structured result; NEVER throws for the malformed-settings case
+ * (that is reported as `status: "error"` with nothing written) so the connect UX stays a clean
+ * one-liner. The only status the caller may present as "connected" is one with `verified: true`.
+ */
+export async function connectClaudeCodeHook(options) {
+    const { settingsPath, dryRun = false } = options;
+    const { settings, existed } = await readSettings(settingsPath);
+    let merged;
+    try {
+        merged = installStopHook(settings);
+    }
+    catch (error) {
+        return {
+            status: "error",
+            settingsPath,
+            existed,
+            verified: false,
+            hookCommand: CLAUDE_CODE_HOOK_COMMAND,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+    if (merged.alreadyPresent) {
+        return {
+            status: "already-present",
+            settingsPath,
+            existed,
+            verified: true, // the hook is present in the file we just read
+            hookCommand: CLAUDE_CODE_HOOK_COMMAND
+        };
+    }
+    if (dryRun) {
+        return {
+            status: "dry-run",
+            settingsPath,
+            existed,
+            verified: false,
+            hookCommand: CLAUDE_CODE_HOOK_COMMAND,
+            wouldWrite: merged.settings
+        };
+    }
+    await writeSettings(settingsPath, merged.settings);
+    // VERIFY: re-read from disk and confirm the entry actually landed. A write that did not take
+    // (odd filesystem, permissions, a racing writer) must NOT be reported as connected.
+    const reread = await readSettings(settingsPath);
+    const verified = reread.existed && hasCompactionStopHook(reread.settings);
+    return {
+        status: verified ? "installed" : "verify-failed",
+        settingsPath,
+        existed,
+        verified,
+        hookCommand: CLAUDE_CODE_HOOK_COMMAND
+    };
+}
+//# sourceMappingURL=claude-code-connect.js.map

package/dist/core/claude-code-hook-record.d.ts

@@ -0,0 +1,71 @@
+import type { TokenSource } from "./api-client/index.js";
+import type { UsageMetadata } from "./usage-metadata.js";
+export declare const CLAUDE_CODE_HOOK_RECORD_SCHEMA: "compaction.claude-code-hook-record.v1";
+export declare const CLAUDE_CODE_HOOK_LEDGER_SCHEMA: "compaction.claude-code-hook-ledger.v1";
+/** The Stop hook payload shape (validated 2026-06-29). Only the fields we use are typed. */
+export interface StopHookPayload {
+    session_id?: string;
+    transcript_path?: string;
+    hook_event_name?: string;
+    stop_hook_active?: boolean;
+    /** NEVER read or stored — listed only to document that it exists and is deliberately ignored. */
+    last_assistant_message?: unknown;
+    [key: string]: unknown;
+}
+/** Fail-safe parse of the Stop payload JSON from stdin. Returns null on any parse error (fail-open). */
+export declare function parseStopPayload(raw: string): StopHookPayload | null;
+/** The transcript path to parse, or null when the payload does not carry one (then the hook is a no-op). */
+export declare function resolveTranscriptPath(payload: StopHookPayload | null): string | null;
+export interface DedupKeyInput {
+    sessionId: string | undefined;
+    /** Content-free one-way digest of the normalized trace (preferred — stable per session-state). */
+    fingerprint: string | undefined;
+    messageCount: number;
+    inputTokens: number | null;
+    outputTokens: number | null;
+}
+/**
+ * Deterministic, content-free dedup key. Prefers the trace fingerprint (a SHA-256 over normalized content
+ * that re-captures reproduce, so the SAME Stop/session state yields the SAME key). Falls back to a signature
+ * over message count + token totals when no fingerprint is available. Same state ⇒ same key ⇒ no double-record.
+ */
+export declare function computeDedupKey(input: DedupKeyInput): string;
+export interface ClaudeCodeHookLedger {
+    schema: typeof CLAUDE_CODE_HOOK_LEDGER_SCHEMA;
+    entries: Array<{
+        dedupKey: string;
+        sessionId?: string;
+        recordedAt: string;
+    }>;
+}
+export declare function emptyLedger(): ClaudeCodeHookLedger;
+export declare function isAlreadyRecorded(ledger: ClaudeCodeHookLedger, dedupKey: string): boolean;
+/** Honest wire token source from usage (mirrors capture-record; kept local to stay a pure leaf). */
+export declare function hookTokenSource(usage: UsageMetadata): TokenSource;
+/** CONTENT-FREE record. Token counts + honest source + ids only; no message/prompt/completion content. */
+export interface ClaudeCodeHookRecord {
+    schema: typeof CLAUDE_CODE_HOOK_RECORD_SCHEMA;
+    tool: "claude-code";
+    sessionId?: string;
+    dedupKey: string;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadInputTokens: number | null;
+    cacheCreationInputTokens: number | null;
+    totalTokens: number | null;
+    providerReported: boolean;
+    tokenSource: TokenSource;
+    provider?: string;
+    model?: string;
+    messageCount: number;
+    recordedAt: string;
+}
+export interface BuildHookRecordInput {
+    usage: UsageMetadata;
+    sessionId?: string;
+    messageCount: number;
+    dedupKey: string;
+    recordedAt: string;
+}
+/** Build the content-free record. Missing token counts stay null (never invented as 0). */
+export declare function buildClaudeCodeHookRecord(input: BuildHookRecordInput): ClaudeCodeHookRecord;

package/dist/core/claude-code-hooks.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Claude Code hook install/uninstall — PURE settings merge (PUBLIC CLI/SDK code, engine-free).
+ * Used by `compaction hooks install|uninstall` and the connect flow. All IO (read/write the settings
+ * file, stdin, dry-run printing) lives in the CLI; this module only transforms a parsed settings object
+ * so it is trivially testable: merge-not-replace, idempotent, and removal that touches ONLY Compaction's
+ * own hook entries.
+ *
+ * Two hooks, two events, two purposes:
+ * - **Stop** (`--from-hook`, run-8): MEASUREMENT. Fires at session END; parses the session JSONL via the
+ *   Stop payload's `transcript_path` and records CONTENT-FREE usage.
+ * - **UserPromptSubmit** (`--from-prompt-hook`, run-13): the first genuine BEFORE-CALL surface. Fires
+ *   before Claude processes the prompt; records a CONTENT-FREE before-call RECOMMENDATION (apply is a
+ *   proven blocker on this surface — hooks cannot reduce the model's context and are non-interactive).
+ *
+ * Both hooks are fail-open by contract (they must never break Claude Code if Compaction fails).
+ */
+/** The command the **Stop** (measurement) hook runs. Session JSONL found via the Stop payload's transcript_path. */
+export declare const CLAUDE_CODE_HOOK_COMMAND = "compaction capture claude-code --from-hook";
+/**
+ * The command the **before-call** hook runs (charter run-13). Installed on the **UserPromptSubmit** event
+ * — a genuine PRE-call hook (fires before Claude processes the prompt), NOT the post-session Stop hook.
+ * NOTE: `--from-prompt-hook` does NOT substring-match `--from-hook`, so the two hooks are never confused.
+ */
+export declare const CLAUDE_CODE_BEFORE_CALL_HOOK_COMMAND = "compaction capture claude-code --from-prompt-hook";
+/** The Claude Code hook event a Compaction hook installs on. */
+export type ClaudeHookEvent = "Stop" | "UserPromptSubmit";
+type HookGroup = {
+    matcher?: string;
+    hooks?: Array<{
+        type?: string;
+        command?: string;
+    }>;
+};
+/** A Claude Code settings object (only the shape we touch is typed; unknown keys are preserved as-is). */
+export interface ClaudeSettings {
+    hooks?: {
+        Stop?: HookGroup[];
+        UserPromptSubmit?: HookGroup[];
+        [event: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** True when a hook command is Compaction's own Claude Code **Stop** (measurement) hook. */
+export declare function isCompactionHookCommand(command: string | undefined): boolean;
+/** True when a hook command is Compaction's own Claude Code **before-call** (UserPromptSubmit) hook. */
+export declare function isCompactionBeforeCallHookCommand(command: string | undefined): boolean;
+/** True when the settings object already contains Compaction's own **Stop** hook. */
+export declare function hasCompactionStopHook(settings: ClaudeSettings): boolean;
+/** True when the settings object already contains Compaction's own **before-call** hook. */
+export declare function hasCompactionBeforeCallHook(settings: ClaudeSettings): boolean;
+export interface InstallResult {
+    settings: ClaudeSettings;
+    /** True when the settings changed (the hook was newly added). */
+    changed: boolean;
+    /** True when Compaction's hook was already present (idempotent no-op). */
+    alreadyPresent: boolean;
+}
+/**
+ * MERGE Compaction's **Stop** (measurement) hook into the settings. Preserves everything; idempotent.
+ */
+export declare function installStopHook(input: ClaudeSettings, command?: string): InstallResult;
+/**
+ * MERGE Compaction's **before-call** hook onto the UserPromptSubmit event. Preserves everything;
+ * idempotent. This is a genuine PRE-call hook — it never touches the Stop (measurement) hook.
+ */
+export declare function installBeforeCallHook(input: ClaudeSettings, command?: string): InstallResult;
+export interface UninstallResult {
+    settings: ClaudeSettings;
+    changed: boolean;
+    /** Number of Compaction hook entries removed. */
+    removedCount: number;
+}
+/** Remove ONLY Compaction's **Stop** hook entries; preserve all other hooks and settings. */
+export declare function uninstallStopHook(input: ClaudeSettings): UninstallResult;
+/** Remove ONLY Compaction's **before-call** (UserPromptSubmit) hook entries; preserve everything else. */
+export declare function uninstallBeforeCallHook(input: ClaudeSettings): UninstallResult;
+export {};

package/dist/core/claude-code-hooks.js

@@ -0,0 +1,141 @@
+/**
+ * Claude Code hook install/uninstall — PURE settings merge (PUBLIC CLI/SDK code, engine-free).
+ * Used by `compaction hooks install|uninstall` and the connect flow. All IO (read/write the settings
+ * file, stdin, dry-run printing) lives in the CLI; this module only transforms a parsed settings object
+ * so it is trivially testable: merge-not-replace, idempotent, and removal that touches ONLY Compaction's
+ * own hook entries.
+ *
+ * Two hooks, two events, two purposes:
+ * - **Stop** (`--from-hook`, run-8): MEASUREMENT. Fires at session END; parses the session JSONL via the
+ *   Stop payload's `transcript_path` and records CONTENT-FREE usage.
+ * - **UserPromptSubmit** (`--from-prompt-hook`, run-13): the first genuine BEFORE-CALL surface. Fires
+ *   before Claude processes the prompt; records a CONTENT-FREE before-call RECOMMENDATION (apply is a
+ *   proven blocker on this surface — hooks cannot reduce the model's context and are non-interactive).
+ *
+ * Both hooks are fail-open by contract (they must never break Claude Code if Compaction fails).
+ */
+/** The command the **Stop** (measurement) hook runs. Session JSONL found via the Stop payload's transcript_path. */
+export const CLAUDE_CODE_HOOK_COMMAND = "compaction capture claude-code --from-hook";
+/**
+ * The command the **before-call** hook runs (charter run-13). Installed on the **UserPromptSubmit** event
+ * — a genuine PRE-call hook (fires before Claude processes the prompt), NOT the post-session Stop hook.
+ * NOTE: `--from-prompt-hook` does NOT substring-match `--from-hook`, so the two hooks are never confused.
+ */
+export const CLAUDE_CODE_BEFORE_CALL_HOOK_COMMAND = "compaction capture claude-code --from-prompt-hook";
+/** True when a hook command is Compaction's own Claude Code **Stop** (measurement) hook. */
+export function isCompactionHookCommand(command) {
+    if (typeof command !== "string")
+        return false;
+    // Require all three so a third-party command that merely mentions "capture claude-code --from-hook" is not
+    // mistaken for ours (uninstall removes ONLY our own hook). `--from-hook` is NOT a substring of
+    // `--from-prompt-hook`, so this never matches the before-call hook.
+    return command.includes("compaction") && command.includes("capture claude-code") && command.includes("--from-hook");
+}
+/** True when a hook command is Compaction's own Claude Code **before-call** (UserPromptSubmit) hook. */
+export function isCompactionBeforeCallHookCommand(command) {
+    if (typeof command !== "string")
+        return false;
+    return command.includes("compaction") && command.includes("capture claude-code") && command.includes("--from-prompt-hook");
+}
+/** True when `settings` already contains a Compaction hook (matched by `isOurs`) on `event`. Pure read. */
+function hasCompactionHookOnEvent(settings, event, isOurs) {
+    const groups = settings.hooks?.[event];
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => (group.hooks ?? []).some((h) => isOurs(h.command)));
+}
+/** True when the settings object already contains Compaction's own **Stop** hook. */
+export function hasCompactionStopHook(settings) {
+    return hasCompactionHookOnEvent(settings, "Stop", isCompactionHookCommand);
+}
+/** True when the settings object already contains Compaction's own **before-call** hook. */
+export function hasCompactionBeforeCallHook(settings) {
+    return hasCompactionHookOnEvent(settings, "UserPromptSubmit", isCompactionBeforeCallHookCommand);
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * MERGE (never replace) a Compaction hook (identified by `isOurs`) onto `event` with `command`. Preserves
+ * all existing keys, hooks, and other entries. Idempotent: if our hook is already present, returns the
+ * settings unchanged. Refuses (throws) rather than clobber a malformed `hooks` / `hooks[event]`.
+ */
+function installHookOnEvent(input, event, command, isOurs) {
+    const settings = clone(input);
+    if (settings.hooks !== undefined && (typeof settings.hooks !== "object" || settings.hooks === null || Array.isArray(settings.hooks))) {
+        throw new Error("existing settings.hooks is malformed (not an object) — refusing to modify; fix the settings file manually.");
+    }
+    const hooks = (settings.hooks ??= {});
+    if (hooks[event] !== undefined && !Array.isArray(hooks[event])) {
+        throw new Error(`existing settings.hooks.${event} is malformed (not an array) — refusing to modify; fix the settings file manually.`);
+    }
+    const groups = (hooks[event] ??= []);
+    const alreadyPresent = groups.some((group) => (group.hooks ?? []).some((h) => isOurs(h.command)));
+    if (alreadyPresent) {
+        return { settings: input, changed: false, alreadyPresent: true };
+    }
+    groups.push({ hooks: [{ type: "command", command }] });
+    return { settings, changed: true, alreadyPresent: false };
+}
+/**
+ * MERGE Compaction's **Stop** (measurement) hook into the settings. Preserves everything; idempotent.
+ */
+export function installStopHook(input, command = CLAUDE_CODE_HOOK_COMMAND) {
+    return installHookOnEvent(input, "Stop", command, isCompactionHookCommand);
+}
+/**
+ * MERGE Compaction's **before-call** hook onto the UserPromptSubmit event. Preserves everything;
+ * idempotent. This is a genuine PRE-call hook — it never touches the Stop (measurement) hook.
+ */
+export function installBeforeCallHook(input, command = CLAUDE_CODE_BEFORE_CALL_HOOK_COMMAND) {
+    return installHookOnEvent(input, "UserPromptSubmit", command, isCompactionBeforeCallHookCommand);
+}
+/**
+ * Remove ONLY Compaction's own hook entries (matched by `isOurs`) from `event`; preserve all other hooks
+ * and settings. Cleans up empty containers (an emptied group, an empty event array, an empty hooks
+ * object) so nothing dangling is left, but never touches another tool's hooks.
+ */
+function uninstallHookFromEvent(input, event, isOurs) {
+    const settings = clone(input);
+    const groups = settings.hooks?.[event];
+    if (!Array.isArray(groups)) {
+        return { settings: input, changed: false, removedCount: 0 };
+    }
+    let removedCount = 0;
+    const next = groups
+        .map((group) => {
+        const inner = group.hooks ?? [];
+        const kept = inner.filter((h) => {
+            const drop = isOurs(h.command);
+            if (drop)
+                removedCount += 1;
+            return !drop;
+        });
+        return { group, kept };
+    })
+        // drop groups that became empty ONLY because we removed our hook (preserve groups that were already empty/other)
+        .filter(({ group, kept }) => kept.length > 0 || (group.hooks ?? []).length === 0)
+        .map(({ group, kept }) => (group.hooks ? { ...group, hooks: kept } : group));
+    if (removedCount === 0) {
+        return { settings: input, changed: false, removedCount: 0 };
+    }
+    if (next.length === 0) {
+        delete settings.hooks[event];
+    }
+    else {
+        settings.hooks[event] = next;
+    }
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    return { settings, changed: true, removedCount };
+}
+/** Remove ONLY Compaction's **Stop** hook entries; preserve all other hooks and settings. */
+export function uninstallStopHook(input) {
+    return uninstallHookFromEvent(input, "Stop", isCompactionHookCommand);
+}
+/** Remove ONLY Compaction's **before-call** (UserPromptSubmit) hook entries; preserve everything else. */
+export function uninstallBeforeCallHook(input) {
+    return uninstallHookFromEvent(input, "UserPromptSubmit", isCompactionBeforeCallHookCommand);
+}
+//# sourceMappingURL=claude-code-hooks.js.map