@compaction/cli 0.2.0 → 0.3.0

package/README.md

@@ -5,9 +5,11 @@ supported agent sessions on your own machine, shows input/output tokens and esti
 with honest labels, and writes local reports and redacted share bundles. Everything runs
 locally and writes local files only — **no account, no telemetry, no upload by default.**
 
-> **The free CLI captures, measures, inspects, reports, and redacts.** Optimization, advanced
-> verification, apply guidance, policies, and team reporting are **not** in the free CLI — they
-> are the **opt-in Compaction API**, which is **not a live hosted service yet**.
+> **The free CLI captures, measures, inspects, reports, redacts — and performs deterministic
+> local compaction with the basic policies (`compact`), writing honest before/after artifacts.**
+> Advanced verification, recommendation and apply guidance, advanced policies, and team
+> reporting are **not** in the free CLI — they are the **opt-in Compaction API**, which is
+> **not a live hosted service yet**.
 
 ## What the CLI does
 
@@ -22,6 +24,11 @@ Everything below runs on your machine and writes local files only:
   run carries provider usage metadata; otherwise they are a **local estimate (chars/4)**. Cost is
   a **price-table estimate** labeled `local estimate` / `token-estimated cost` — **never
   billing-confirmed**.
+- **Compact deterministically, locally.** `compact` applies the basic deterministic policies
+  (e.g. `stale_tool_output_to_state_capsule`) to a captured/imported trace and writes honest
+  before/after artifacts locally (report, safety/recoverability report, state capsules). The
+  original trace is retained, token figures stay **local estimates** unless provider-reported,
+  and **nothing is applied to your workflow automatically**.
 - **Inspect spend and roll up runs.** `spend`, `summary`, and `aggregate` summarize where context
   spend came from and roll up local runs — local files only, no hosted dashboard.
 - **Build a local context store and retrieve from it.** `context add` accumulates source-pointed
@@ -48,10 +55,11 @@ and roughly what does it cost?"* — entirely locally, with honest labels.
 
 These are **not** part of the free local CLI:
 
-- **Optimization** — producing a compacted context from a captured trace.
-- **Advanced verification** — stronger checks on what a compacted context retains.
+- **Recommendation** — a recommended-policy verdict (`recommend`) for a captured trace.
+- **Advanced verification** — stronger checks on what a compacted context retains (incl. `compact --eval`).
 - **Apply guidance** — a readiness verdict and a review/approval path before any context is applied.
-- **Policies & team reporting** — configurable behavior controls and cross-run / team reporting.
+- **Advanced policies & team reporting** — configurable behavior controls beyond the basic
+  deterministic policies, and cross-run / team reporting.
 
 > **The Compaction API is not broadly hosted yet.** There is **no live hosted service today**.
 > Until the API is available, these capabilities are **on the roadmap / opt-in**, not present in
@@ -74,7 +82,7 @@ npx @compaction/cli --help       # no install at all
 ```
 
 The installed binary is `compaction`. After a global install, sanity-check with
-`compaction --version` (→ `0.2.0`) and `compaction --help`.
+`compaction --version` (→ `0.3.0`) and `compaction --help`.
 
 ### curl one-liner
 
@@ -109,8 +117,27 @@ compaction spend ./my-trace/captured-trace.json
 compaction feedback --redact --yes
 ```
 
-Optimization, verification, and apply guidance are the opt-in Compaction API — not steps of the
-free local CLI.
+Deterministic basic compaction (`compaction compact <trace> --out <dir>`) also runs locally in
+the free CLI. Advanced verification, recommendation, and apply guidance are the opt-in
+Compaction API — not steps of the free local CLI.
+
+## Gateway (local, byte-safe)
+
+The Compaction **Gateway** is a local, OpenAI-compatible reverse proxy. Point your OpenAI client at it
+(or launch your workflow through it) and it forwards traffic to the provider and records **content-free**
+token/cache receipts — no prompt/response content, and your provider key stays on the client. Set it up
+from onboarding (`compaction` → **Gateway setup**), or directly:
+
+```bash
+compaction gateway start                     # start the local gateway (RECORD mode; byte-safe, no mutation)
+compaction gateway run -- npm run dev         # run a command through the gateway (no baseURL copy-paste)
+compaction gateway status                     # requests observed + a content-free receipts rollup
+```
+
+Record mode never changes your request or response. An **experimental**, explicit-opt-in deterministic
+`apply` mode (`--mode apply --policy deterministic-dedupe`) can remove exact-duplicate large blocks from
+known-safe requests, retaining the original locally (`compaction gateway recover <id>`). Nothing is called
+a saving — the gateway reports provider-reported token/cache counts (or "unavailable"), never a cost figure.
 
 ## Supported local workflows
 
@@ -141,6 +168,7 @@ compaction capture provider-usage --endpoint <url> [--credential-env-var <NAME>]
 compaction import <trace-file> --source <source> --out <dir>
 compaction import --list-sources
 compaction analyze <trace-file>
+compaction compact <trace-file> --out <dir>      # deterministic local compaction (basic policies) + honest artifacts
 compaction context add <trace-file>             # build a local context store from a captured/imported trace
 compaction context get "<query>"                # retrieve + assemble the active context (with source pointers)
 compaction spend <trace-or-optimization-path>   # context-spend attribution
@@ -180,9 +208,10 @@ Every figure this tool produces carries one of these labels — and nothing stro
 
 ## Known limitations
 
-- **The free CLI captures and measures; it does not optimize or verify.** Optimization, advanced
-  verification, apply guidance, policies, and team reporting are the **opt-in Compaction API** —
-  not the free local CLI. The API is **not broadly hosted yet**.
+- **The free CLI captures, measures, and compacts deterministically; it does not perform
+  advanced verification.** Recommendation, advanced verification (incl. `compact --eval`), apply
+  guidance, advanced policies, and team reporting are the **opt-in Compaction API** — not the
+  free local CLI. The API is **not broadly hosted yet**.
 - **Cost figures are estimates or operator-entered records, not billing-confirmed.** Locally
   computed cost figures are price-table estimates; provider-usage records carry operator-entered/
   captured console figures (not provider-verified by this tool). **No figure is billing-confirmed.**

package/dist/cli/commands/activity.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `compaction activity` — READ-ONLY, metrics-only view of recent runs from the local activity
+ * store (`.compaction/activity/activity.jsonl`). Content-free: it renders only the counts/labels
+ * the events already carry; it never reads or prints prompt/response content, and it writes
+ * NOTHING. Empty store → a friendly message, exit 0.
+ */
+export declare function registerActivityCommand(program: Command): void;

package/dist/cli/commands/activity.js

@@ -0,0 +1,35 @@
+import chalk from "chalk";
+import { readActivityEvents } from "../../core/activity-store.js";
+import { DEFAULT_ACTIVITY_LIMIT, buildActivityJson, buildActivityRows, formatActivityTable } from "../../core/activity-view.js";
+/**
+ * `compaction activity` — READ-ONLY, metrics-only view of recent runs from the local activity
+ * store (`.compaction/activity/activity.jsonl`). Content-free: it renders only the counts/labels
+ * the events already carry; it never reads or prints prompt/response content, and it writes
+ * NOTHING. Empty store → a friendly message, exit 0.
+ */
+export function registerActivityCommand(program) {
+    program
+        .command("activity")
+        .description("Show recent runs recorded in the local metrics-only activity store (read-only, content-free).")
+        .option("--limit <n>", `Max runs to show, most recent first (default ${DEFAULT_ACTIVITY_LIMIT})`)
+        .option("--surface <surface>", "Only show runs from this surface (e.g. cursor, codex, cli, claude_code)")
+        .option("--json", "Machine-readable JSON output")
+        .action(async (options) => {
+        const limit = options.limit !== undefined ? Number.parseInt(options.limit, 10) : DEFAULT_ACTIVITY_LIMIT;
+        if (Number.isNaN(limit) || limit < 0) {
+            console.error(`Invalid --limit "${options.limit}": expected a non-negative integer.`);
+            process.exitCode = 1;
+            return;
+        }
+        const { events, skipped } = await readActivityEvents();
+        const rows = buildActivityRows(events, { limit, surface: options.surface });
+        const meta = { totalEvents: events.length, limit, surface: options.surface, skippedCount: skipped.length };
+        if (options.json) {
+            console.log(JSON.stringify(buildActivityJson(rows, meta), null, 2));
+            return;
+        }
+        const table = formatActivityTable(rows, meta);
+        console.log(rows.length === 0 ? chalk.yellow(table) : chalk.cyan(table));
+    });
+}
+//# sourceMappingURL=activity.js.map

package/dist/cli/commands/apply-context.js

@@ -1,11 +1,27 @@
 import path from "node:path";
 import chalk from "chalk";
 import { Option } from "commander";
+import { AUTO_APPLY_QUESTION_LINES, formatSavedPreferenceConfirmation, resolveAutoApplyOffer } from "../../core/auto-apply-ask.js";
+import { savePolicyPreference } from "../../core/policy-preferences.js";
 import { parseTraceFile } from "../../core/trace-parser.js";
 import { runEngineCommand } from "../engine-degrade.js";
 function defaultOutputDir(artifactRoot, traceId) {
     return path.join(artifactRoot, traceId);
 }
+/**
+ * Infer the SAFEST workflow tool for the auto-apply preference scope. Prefers the explicit
+ * `--workflow-tool` flag; otherwise maps an unambiguous trace source to its tool. Returns undefined
+ * when it cannot infer safely (then the offer fails closed and saves nothing — never guesses global).
+ */
+function inferWorkflowTool(explicit, traceSource) {
+    if (explicit && explicit.trim() !== "")
+        return explicit.trim();
+    if (traceSource === "codex_import")
+        return "codex";
+    if (traceSource === "cursor_import")
+        return "cursor";
+    return undefined;
+}
 /**
  * `compaction apply-context <trace-file> --out <dir>` — LEVEL-5 IN-WORKFLOW APPLY, Form A.
  *
@@ -26,6 +42,12 @@ export function registerApplyContextCommand(program) {
         .addOption(new Option("--approve-skill-injection-policy", "EXPLICITLY also authorize the approval-required repeated_skill_injection_to_state_capsule policy. Default off; no auto-apply."))
         .addOption(new Option("--attest-used", "OPTIONAL operator attestation: AFTER an approval, the operator records that they used the approved context in a live call. Stored as operator-ATTESTED provenance (the operator's own claim), never observed by compaction.dev."))
         .option("--attest-note <text>", "Optional free-text note recorded with the operator attestation")
+        .addOption(new Option("--offer-auto-apply", "OPT-IN. AFTER an explicit approval, offer the ONE binary question 'apply this automatically next time when safety gates pass?' (default no). Saving a preference records intent only — it NEVER applies anything (no auto-apply engine exists)."))
+        .addOption(new Option("--remember-auto-apply", "Non-interactive answer YES to the auto-apply offer (requires --offer-auto-apply and a prior approval). Saves a preference for the inferred safest scope; applies nothing now."))
+        .addOption(new Option("--no-remember", "Non-interactive answer NO to the auto-apply offer (the default): save nothing, keep asking each time."))
+        .option("--workflow-tool <tool>", "Tool/workflow to scope a saved auto-apply preference to (never global/cross-tool). Inferred from the trace source when omitted.")
+        .option("--workflow-repo <repo>", "Optional content-free repo identifier to narrow a saved auto-apply preference's scope.")
+        .option("--policy-type <type>", "Policy type a saved auto-apply preference concerns (defaults to the approved policy name).")
         .action(async (traceFile, options) => {
         await runEngineCommand(async () => {
             // Lazy-load the proprietary engine: present in-repo/API, excluded from the public package.
@@ -70,6 +92,52 @@ export function registerApplyContextCommand(program) {
                 }
             }
             console.log(chalk.green(`Output directory: ${result.outputDirectory}`));
+            // OPT-IN post-approval auto-apply OFFER (§11a block 4/5). This offer is made ONLY after an
+            // explicit in-workflow approval already emitted an approved context. It APPLIES NOTHING: on
+            // yes it records a PREFERENCE (intent for the future gated slice) via the #598 store; on
+            // no/default it saves nothing. It never touches apply execution semantics.
+            if (options.offerAutoApply === true && result.approvedContextEmitted) {
+                console.log("");
+                for (const line of AUTO_APPLY_QUESTION_LINES)
+                    console.log(chalk.cyan(line));
+                const answer = options.rememberAutoApply === true ? "yes" : "no";
+                const decision = resolveAutoApplyOffer({
+                    approvedInWorkflow: true,
+                    answer,
+                    scope: {
+                        tool: inferWorkflowTool(options.workflowTool, trace.source),
+                        repo: options.workflowRepo,
+                        policyType: options.policyType ?? result.review.policies_applied[0]
+                    }
+                });
+                if (decision.action === "save") {
+                    const saved = await savePolicyPreference({
+                        scope: decision.scope,
+                        preference: decision.preference,
+                        gates_required: decision.gatesRequired
+                    });
+                    if (saved.saved) {
+                        console.log("");
+                        console.log(chalk.green(formatSavedPreferenceConfirmation(saved.preference)));
+                    }
+                    else {
+                        console.log("");
+                        console.log(chalk.yellow("Preference NOT saved (fail-closed) — nothing was applied:"));
+                        for (const problem of saved.problems)
+                            console.log(chalk.yellow(`  - ${problem}`));
+                    }
+                }
+                else if (decision.action === "blocked") {
+                    console.log("");
+                    console.log(chalk.yellow("Preference NOT saved — could not infer a safe (non-global, non-cross-tool) scope. Nothing applied:"));
+                    for (const problem of decision.problems)
+                        console.log(chalk.yellow(`  - ${problem}`));
+                    console.log(chalk.dim("  Pass --workflow-tool <tool> (and optionally --policy-type / --workflow-repo) to record a preference."));
+                }
+                else {
+                    console.log(chalk.dim("No auto-apply preference saved — Compaction will keep asking each time (the default)."));
+                }
+            }
             // Exit non-zero when no approved context was emitted (refusal / review-only), mirroring apply/approve.
             if (!result.approvedContextEmitted) {
                 process.exitCode = 1;

package/dist/cli/commands/billing-delta.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
-import { addRun, computeReport, initMeasurementRecord, BILLING_DELTA_CRITERION, BILLING_DELTA_RECORD_ROOT } from "../../core/billing-delta/billing-delta-record.js";
+import { addRun, computeReport, initMeasurementRecord, API_METERED_BILLING_CONFIRMED_CRITERIA, BILLING_DELTA_CRITERION, BILLING_DELTA_FIXED_PLAN_NOTE, BILLING_DELTA_RECORD_ROOT } from "../../core/billing-delta/billing-delta-record.js";
 const PRIVACY_NOTE = "Operator-run, local-first. compaction.dev makes NO provider call, reads NO credential, and has NO network access. " +
     "All billing figures are operator-entered (read from YOUR provider console/billing export) and are NOT provider-verified by this tool. " +
     "Aggregate cost only — no prompt/completion content is stored.";
@@ -81,6 +81,17 @@ function buildReportMarkdown(report) {
         "",
         `- ${report.criterion}`,
         "",
+        "## API-metered billing-confirmed criteria (cross-surface contract §5, D6 — checklist only)",
+        "",
+        "> A billing-confirmed figure is possible ONLY on api_metered workflows, ONLY through this",
+        "> billing-delta flow, and ONLY when ALL of the criteria below hold. This report does NOT verify",
+        "> them and NEVER carries billing_confirmed: true. Even when all criteria hold, the claim is",
+        "> workflow-scoped only — generalized billing-confirmed = future only.",
+        ">",
+        `> ${BILLING_DELTA_FIXED_PLAN_NOTE}`,
+        "",
+        ...API_METERED_BILLING_CONFIRMED_CRITERIA.map((c, i) => `${i + 1}. ${c}`),
+        "",
         "## Verdict notes",
         "",
         ...report.verdict_notes.map((n) => `- ${n}`),

package/dist/cli/commands/capture-claude-code.d.ts

@@ -1,3 +1,4 @@
+import type { UsageMetadata } from "../../core/usage-metadata.js";
 interface DiscoverClaudeCodeOptions {
     projectsDir?: string;
 }
@@ -8,6 +9,49 @@ interface CaptureClaudeCodeOptions {
     includeSubagents?: boolean;
 }
 export declare function captureClaudeCodeCommand(options: CaptureClaudeCodeOptions): Promise<void>;
+/** A normalized usage summary for the hook path — usage + a content-free fingerprint + message count. */
+interface HookNormalizeResult {
+    usage: UsageMetadata;
+    messageCount: number;
+    fingerprint?: string;
+}
+export interface FromHookDeps {
+    readStdin?: () => Promise<string>;
+    normalize?: (transcriptPath: string) => Promise<HookNormalizeResult>;
+    cwd?: string;
+    now?: () => string;
+    hostedConfigured?: () => boolean;
+}
+export interface FromHookOptions {
+    dryRun?: boolean;
+}
+/**
+ * `compaction capture claude-code --from-hook`. Reads the Stop payload from stdin, resolves the session
+ * JSONL via `transcript_path`, and records CONTENT-FREE usage only — never message content, never
+ * `last_assistant_message`. Idempotent via a content-free dedup ledger. FAIL-OPEN by contract: any error is
+ * swallowed and the process exits 0 so the hook can never break Claude Code.
+ */
+export declare function captureClaudeCodeFromHook(options?: FromHookOptions, deps?: FromHookDeps): Promise<void>;
+export interface FromPromptHookDeps {
+    readStdin?: () => Promise<string>;
+    cwd?: string;
+}
+/**
+ * `compaction capture claude-code --from-prompt-hook` — the BEFORE-CALL recommendation path (charter
+ * 2026-07-04-run-13). The Claude Code **UserPromptSubmit** hook runs this BEFORE the model processes the
+ * prompt (a genuine pre-call event — NOT the post-session Stop hook). It reads the UserPromptSubmit
+ * payload from stdin, analyzes the pending PROMPT for avoidable duplicated context IN-PROCESS
+ * (content-free), and — when present — records ONE metrics-only `claude_code` before-call RECOMMENDATION
+ * activity event so it appears in `compaction activity`. Apply is a PROVEN BLOCKER on this surface (no
+ * hook can reduce the model's context; hooks are non-interactive) → recommendation-only; the original
+ * prompt ALWAYS runs UNCHANGED.
+ *
+ * CRITICAL: this path writes NOTHING to stdout — on UserPromptSubmit, a hook's stdout is ADDED to the
+ * model's context, so injecting anything would be both intrusive and self-defeating for a compaction
+ * tool. It is silent and transparent; the recommendation lives in `compaction activity`. FAIL-OPEN +
+ * CONTENT-FREE: any error is swallowed and the process exits 0; the prompt text is never persisted.
+ */
+export declare function captureClaudeCodeFromPromptHook(deps?: FromPromptHookDeps): Promise<void>;
 /**
  * Discover local Claude Code sessions (metadata only) and print, for each, the
  * ready-to-run `capture claude-code --session <path>` command (guided capture).

package/dist/cli/commands/capture-claude-code.js

@@ -1,6 +1,18 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
 import { ClaudeCodeAdapter, PRIVACY_WARNING } from "../../core/adapters/claude-code-adapter.js";
 import { discoverClaudeCodeSessions, DISCOVERY_PRIVACY_NOTE } from "../../core/adapters/claude-code-discovery.js";
+import { recordCaptureContentFree } from "../../core/capture-record.js";
+import { buildRunFlowTokenReport, formatRunFlowTokenReport } from "../../core/run-flow-report.js";
+import { buildRunCrossSurfaceEvent } from "../../core/cross-surface-event.js";
+import { buildMeasureOnlyActivityEvent } from "../../core/activity-event.js";
+import { appendActivityEvent } from "../../core/activity-store.js";
+import { detectAvoidableContext } from "../../core/before-call.js";
+import { parseUserPromptSubmitPayload, buildClaudeCodeBeforeCallEvent } from "../../core/claude-code-before-call.js";
+import { resolveApiConfig } from "../../core/api-client/index.js";
+import { hostedConfigured } from "./optimize-hosted.js";
+import { buildClaudeCodeHookRecord, computeDedupKey, emptyLedger, isAlreadyRecorded, parseStopPayload, resolveTranscriptPath } from "../../core/claude-code-hook-record.js";
 function buildOutputDir(sessionPath, out) {
     if (out)
         return out;
@@ -120,6 +132,16 @@ export async function captureClaudeCodeCommand(options) {
         console.log("      figures shown by 'spend' and 'compact' are deterministic LOCAL ESTIMATES (chars/4) — a");
         console.log("      different measurement, labeled there as local estimates; neither figure is billing-confirmed.");
     }
+    // 6b-iii. Shared UNIFIED-FLOW honest token report (docs/design/unified-run-flow.md, D1/D3): the SAME
+    // block that `run codex` / `run cursor` print, so all three tools present ONE honest `token_source`
+    // summary. Claude Code usage is PROVIDER-REPORTED and whole (no per-field unavailable split, like
+    // Codex), so outputStatus is "present"; when a session lacks provider usage the shared builder honestly
+    // downgrades to local-estimate / unavailable — it never labels anything stronger than the evidence. This
+    // is a reporting surface only: input/output are shown SEPARATELY with an explicit source, and output is
+    // shown as TOKENS ONLY (never a saving). No logic, adapter, or record behavior changes here.
+    const runFlowReport = buildRunFlowTokenReport({ tool: "claude-code", usage, outputStatus: "present" });
+    for (const line of formatRunFlowTokenReport(runFlowReport))
+        console.log(line);
     // 6c. Per-run distinctness fingerprint (a one-way digest over canonical normalized
     // content — NOT raw content). Lets a re-capture of the same session be told apart
     // from a genuinely new one; when unavailable, distinctness is `not_verified`.
@@ -138,6 +160,20 @@ export async function captureClaudeCodeCommand(options) {
     await writeTextArtifact(outDir, "capture-report.md", markdownReport);
     // 7. Print artifacts written
     console.log(`Artifacts written to: ${outDir}/`);
+    // Unified flow (docs/design/unified-run-flow.md): content-free record (input/output separate +
+    // honest source) when hosted-configured. No default network call — only when COMPACTION_API_URL +
+    // COMPACTION_API_KEY are set. Claude Code session usage is provider-reported.
+    if (hostedConfigured()) {
+        const rec = await recordCaptureContentFree(resolveApiConfig(), {
+            usage,
+            tool: "claude-code",
+            reference: `${outDir}/captured-trace.json`
+        });
+        console.log(rec.recorded ? `Recorded content-free usage (tool=claude-code, source=${rec.source}).` : `Not recorded: ${rec.reason}.`);
+    }
+    else {
+        console.log("Not recorded (set COMPACTION_API_URL + COMPACTION_API_KEY to record content-free usage).");
+    }
     // 8. Print next step — chain into the verified strong-MVP Claude Code flow:
     //    spend (where the spend goes) → compact --eval (compaction + strong apply-readiness:
     //    deterministic recoverability + commitment-preservation + fixture task-check + token/cost).
@@ -151,6 +187,176 @@ export async function captureClaudeCodeCommand(options) {
     console.log("     # fixture task-check, and token/cost accounting — nothing is applied automatically.");
     console.log(`  (or: compaction analyze ${outDir}/captured-trace.json   for a quick read-only estimate)`);
 }
+async function readAllStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function defaultHookNormalize(transcriptPath) {
+    const adapter = new ClaudeCodeAdapter();
+    const { trace, usage, provenance } = await adapter.normalize({ sourcePath: transcriptPath });
+    return {
+        usage,
+        messageCount: trace.messages.length,
+        ...(provenance.traceFingerprint ? { fingerprint: provenance.traceFingerprint.content_sha256 } : {})
+    };
+}
+function hookDir(cwd) {
+    return path.join(cwd, ".compaction", "hooks", "claude-code");
+}
+async function loadLedger(cwd) {
+    try {
+        const raw = await readFile(path.join(hookDir(cwd), "ledger.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.entries) ? parsed : emptyLedger();
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+/**
+ * Append ONE metrics-only activity event for a Stop-hook capture (the always-on bridge). Builds the
+ * `claude_code` cross-surface event from the SAME honest token report the record uses, then the
+ * measure-only activity extension, and appends it to `.compaction/activity/` under the hook's cwd
+ * (so tmp-cwd tests and real projects both scope correctly). Content-free and best-effort: any
+ * local failure is swallowed here so it can NEVER break the fail-open hook.
+ */
+async function appendClaudeCodeHookActivity(input) {
+    try {
+        // outputStatus "present": buildRunFlowTokenReport honestly downgrades a missing output axis to
+        // unavailable — a genuinely-absent field is never labeled provider-reported (no silent zero).
+        const tokenReport = buildRunFlowTokenReport({ tool: "claude-code", usage: input.usage, outputStatus: "present" });
+        const crossSurfaceEvent = buildRunCrossSurfaceEvent("claude_code", {
+            // run_id is the deterministic content-free dedup key → deterministic activity_event_id → the
+            // store dedupes a re-captured session (same state = one event).
+            runId: `claude-code-${input.dedupKey}`,
+            tokenReport,
+            reasons: {
+                input: "the Claude Code session usage did not report input tokens for this session state",
+                output: "the Claude Code session usage did not report output tokens for this session state"
+            },
+            ...(input.usage.model ? { modelLabel: input.usage.model } : {})
+        });
+        // session_id rides on the event too (content-free identity), when the Stop payload carried one.
+        const eventWithSession = input.sessionId
+            ? { ...crossSurfaceEvent, session_id: input.sessionId }
+            : crossSurfaceEvent;
+        // Measurement only: nothing was applied or retained by Compaction, so original_retained=false.
+        const activityEvent = buildMeasureOnlyActivityEvent(eventWithSession, { original_retained: false });
+        const result = await appendActivityEvent(activityEvent, path.join(input.cwd, ".compaction", "activity"));
+        console.log(result.appended
+            ? `compaction hook: recorded metrics-only activity (surface=claude_code, id ${result.activity_event_id.slice(0, 12)}…) — see 'compaction activity'.`
+            : `compaction hook: activity not appended (${result.reason}).`);
+    }
+    catch {
+        // Best-effort local append — never fail the fail-open hook on a filesystem/store error.
+    }
+}
+/**
+ * `compaction capture claude-code --from-hook`. Reads the Stop payload from stdin, resolves the session
+ * JSONL via `transcript_path`, and records CONTENT-FREE usage only — never message content, never
+ * `last_assistant_message`. Idempotent via a content-free dedup ledger. FAIL-OPEN by contract: any error is
+ * swallowed and the process exits 0 so the hook can never break Claude Code.
+ */
+export async function captureClaudeCodeFromHook(options = {}, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const now = deps.now ?? (() => new Date().toISOString());
+    const readStdin = deps.readStdin ?? readAllStdin;
+    const normalize = deps.normalize ?? defaultHookNormalize;
+    const hostedIsConfigured = deps.hostedConfigured ?? hostedConfigured;
+    try {
+        const payload = parseStopPayload(await readStdin());
+        const transcriptPath = resolveTranscriptPath(payload);
+        if (!transcriptPath) {
+            console.log("compaction hook: no transcript_path in the Stop payload — nothing recorded (content-free).");
+            return;
+        }
+        const sessionId = typeof payload?.session_id === "string" ? payload.session_id : undefined;
+        const { usage, messageCount, fingerprint } = await normalize(transcriptPath);
+        const dedupKey = computeDedupKey({
+            sessionId,
+            fingerprint,
+            messageCount,
+            inputTokens: typeof usage.input_tokens === "number" ? usage.input_tokens : null,
+            outputTokens: typeof usage.output_tokens === "number" ? usage.output_tokens : null
+        });
+        const ledger = await loadLedger(cwd);
+        if (isAlreadyRecorded(ledger, dedupKey)) {
+            console.log(`compaction hook: already recorded this session state (dedup ${dedupKey.slice(0, 8)}…) — skipped.`);
+            return;
+        }
+        const record = buildClaudeCodeHookRecord({ usage, ...(sessionId ? { sessionId } : {}), messageCount, dedupKey, recordedAt: now() });
+        if (options.dryRun) {
+            console.log("compaction hook --dry-run: would record (content-free, nothing written):");
+            console.log(JSON.stringify(record, null, 2));
+            return;
+        }
+        const dir = hookDir(cwd);
+        await mkdir(path.join(dir, "records"), { recursive: true });
+        await writeFile(path.join(dir, "records", `${dedupKey}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+        ledger.entries.push({ dedupKey, ...(sessionId ? { sessionId } : {}), recordedAt: record.recordedAt });
+        await writeFile(path.join(dir, "ledger.json"), `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
+        console.log(`compaction hook: recorded content-free usage (source=${record.tokenSource}, dedup ${dedupKey.slice(0, 8)}…).`);
+        // ALWAYS-ON BRIDGE (charter 2026-07-04-run-8): the Stop hook runs this command at session end,
+        // so the SAME content-free usage ALSO appends ONE metrics-only activity event to the local
+        // activity store (.compaction/activity/). THIS is what makes a subsequent Claude Code session
+        // appear in `compaction activity` with NO manual import. Honesty: surface "claude_code",
+        // provider "anthropic", token axes copied VERBATIM from the SAME token report (provider-reported
+        // where the session usage carried them, else unavailable-with-reason — never a silent zero);
+        // measure-only, so approval "not-required", auto_apply OFF (not eligible, "ask-each-time",
+        // applied_automatically false — no auto-apply logic exists), sync "local-only", recovery
+        // original_retained=false (measurement only — Compaction modified/retained nothing). The event
+        // id is DETERMINISTIC from session state (run_id = the content-free dedup key), so a re-captured
+        // session yields the SAME id and the store dedupes it. Best-effort + content-free; a local
+        // filesystem failure here never breaks the hook.
+        await appendClaudeCodeHookActivity({ cwd, usage, dedupKey, sessionId });
+        if (hostedIsConfigured()) {
+            const rec = await recordCaptureContentFree(resolveApiConfig(), { usage, tool: "claude-code", reference: `hook:${dedupKey}` });
+            console.log(rec.recorded ? `compaction hook: also recorded to hosted (source=${rec.source}).` : `compaction hook: hosted not recorded: ${rec.reason}.`);
+        }
+    }
+    catch (error) {
+        // FAIL-OPEN: never propagate — the hook must not break Claude Code.
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`compaction hook: skipped (non-fatal: ${message}).`);
+    }
+}
+/**
+ * `compaction capture claude-code --from-prompt-hook` — the BEFORE-CALL recommendation path (charter
+ * 2026-07-04-run-13). The Claude Code **UserPromptSubmit** hook runs this BEFORE the model processes the
+ * prompt (a genuine pre-call event — NOT the post-session Stop hook). It reads the UserPromptSubmit
+ * payload from stdin, analyzes the pending PROMPT for avoidable duplicated context IN-PROCESS
+ * (content-free), and — when present — records ONE metrics-only `claude_code` before-call RECOMMENDATION
+ * activity event so it appears in `compaction activity`. Apply is a PROVEN BLOCKER on this surface (no
+ * hook can reduce the model's context; hooks are non-interactive) → recommendation-only; the original
+ * prompt ALWAYS runs UNCHANGED.
+ *
+ * CRITICAL: this path writes NOTHING to stdout — on UserPromptSubmit, a hook's stdout is ADDED to the
+ * model's context, so injecting anything would be both intrusive and self-defeating for a compaction
+ * tool. It is silent and transparent; the recommendation lives in `compaction activity`. FAIL-OPEN +
+ * CONTENT-FREE: any error is swallowed and the process exits 0; the prompt text is never persisted.
+ */
+export async function captureClaudeCodeFromPromptHook(deps = {}) {
+    const readStdin = deps.readStdin ?? readAllStdin;
+    try {
+        const payload = parseUserPromptSubmitPayload(await readStdin());
+        if (!payload)
+            return; // malformed/absent payload → nothing recorded (fail-open)
+        const result = detectAvoidableContext(payload.prompt);
+        if (!result.has_avoidable_context)
+            return; // honest no-op → no activity noise, no stdout
+        const cwd = payload.cwd ?? deps.cwd ?? process.cwd();
+        const event = buildClaudeCodeBeforeCallEvent(result, payload.sessionId ? { sessionId: payload.sessionId } : {});
+        await appendActivityEvent(event, path.join(cwd, ".compaction", "activity"));
+        // No stdout (would inject into the model context); the recommendation is in `compaction activity`.
+    }
+    catch {
+        // FAIL-OPEN: never propagate — the before-call hook must not break Claude Code.
+    }
+}
 /**
  * Discover local Claude Code sessions (metadata only) and print, for each, the
  * ready-to-run `capture claude-code --session <path>` command (guided capture).