@compaction/cli 0.2.0 → 0.3.1

package/README.md

@@ -1,17 +1,53 @@
 # @compaction/cli
 
-**The free, local-first CLI for capturing and measuring AI agent traces.** It captures
-supported agent sessions on your own machine, shows input/output tokens and estimated spend
-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, local-first CLI for the Compaction Gateway — a local, OpenAI-compatible proxy that
+measures your AI traffic without changing it.** Point your OpenAI-compatible client's base URL at
+the local gateway (or launch your workflow through it) and it forwards traffic to your provider and
+records **content-free** token/cache receipts — counts and labels only, never prompt/response
+content. Your provider key stays on the client. The CLI also captures and measures agent traces
+locally. Everything runs on your machine — **no account, no telemetry, no upload to Compaction.**
+
+> The free CLI runs the **local Gateway** (byte-safe **record** mode + content-free receipts, plus
+> an **explicit, experimental deterministic apply/recovery**), captures and measures agent traces,
+> and performs deterministic local compaction with the basic policies (`compact`) — writing honest
+> before/after artifacts. The **learned context model (LCM), learned optimization engine, hosted /
+> team control plane, verified-savings logic, and advanced proprietary evals are NOT in the npm /
+> free CLI** — they are the **opt-in Compaction API**, which is **not a live hosted service yet**.
+
+## The Gateway (local, byte-safe)
+
+The Compaction **Gateway** is a **local, OpenAI-compatible reverse proxy for OpenAI-compatible
+clients**. Point your client's base URL at it, or launch your workflow through it, and it forwards
+traffic to your provider and records **content-free** token/cache receipts (counts / structure /
+labels only — never prompt/response content). Your provider key rides straight through to the
+provider and is **never read, stored, or logged**. Set it up from onboarding (`compaction` →
+**Gateway setup**), or directly:
 
-> **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**.
-
-## What the CLI does
+```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
+compaction gateway activate                # print env exports:  eval "$(compaction gateway activate)"
+```
 
-Everything below runs on your machine and writes local files only:
+- **Record mode is byte-safe** — it forwards your request and the provider's response
+  **byte-for-byte** and never changes either. Receipts are content-free and local-only (gitignored).
+- **Explicit, experimental deterministic apply** (`--mode apply --policy deterministic-dedupe`) can
+  remove **exact-duplicate large blocks** from known-safe requests. It is **off by default**,
+  opt-in, and **retains the original locally** (`compaction gateway recover <id>`). Unknown/complex
+  shapes **fail closed** (forwarded unchanged); system/developer instructions and tool schemas are
+  never touched; the **response is never changed**.
+- **No hosted/managed proxy or model routing.** The local Gateway is an OpenAI-compatible reverse
+  proxy for compatible clients — it runs on your machine.
+- **Claim boundary.** The gateway reports **provider-reported** token/cache counts (or
+  `unavailable`) — it makes **no cost-savings, no output-token-savings, and no billing-confirmed
+  claim**. A model-visible **input** reduction is stated only when apply actually changed the
+  request (a **local-estimate** before/after; the original is retained) — never a cost or
+  output-token figure, and never a "no context lost" claim.
+
+## Trace / capture utilities (other local tools)
+
+Beyond the Gateway, the free CLI captures and measures agent traces locally — local files only:
 
 - **Capture supported agent sessions.** Claude Code is the primary supported workflow
   (`capture claude-code`); OpenAI Agents SDK (`capture openai-agents`) and Codex / local-file
@@ -22,59 +58,64 @@ 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
   items from a captured/imported trace into a local, size-capped store; `context get`
   deterministically retrieves and assembles the active context for a query under a token budget,
-  printing it **with source pointers** plus local retrieval **diagnostics** (what was
-  considered / included / dropped, the recoverable fraction, latency). Local-only and
-  deterministic — **no model, no embeddings, no network**. It reports **diagnostics only** (no
-  quality or sufficiency verdict on your data) and makes **no savings claim** (see `spend` /
-  `summary` for cost).
-- **Write local reports.** `analyze` writes local JSON + Markdown reports under an
-  operator-chosen output directory. Local files only.
+  printing it **with source pointers** plus local retrieval **diagnostics**. Local-only and
+  deterministic — **no model, no embeddings, no network**. It reports **diagnostics only** and
+  makes **no savings claim**.
+- **Write local reports.** `analyze` writes local JSON + Markdown reports under an operator-chosen
+  output directory. Local files only.
 - **Create redacted, content-free share bundles.** `feedback --redact` writes a redacted,
   privacy-safe bundle as a **local file only — never uploaded**, and only with an explicit write
   gesture (`--yes`).
-- **No upload by default.** There is **no telemetry**. The **only** network call in the free CLI
-  is the explicitly operator-invoked, read-only `capture provider-usage` (credential supplied via
-  an environment variable only; aggregate usage/cost figures only, no prompt/completion content).
 
-The free CLI deliberately answers the first-value question — *"where is my context being wasted,
-and roughly what does it cost?"* — entirely locally, with honest labels.
+## Free (npm) vs. private (opt-in API)
 
-## What requires the Compaction API (opt-in — not in the free CLI)
+**In the free / local CLI (npm):**
 
-These are **not** part of the free local CLI:
+- the **local Gateway** — record mode, `status`, content-free receipts, `gateway run`,
+- **explicit deterministic apply / dry-run / recover** (experimental, opt-in),
+- **capture / import / analyze / spend / compact / context / feedback** (local trace utilities).
 
-- **Optimization** — producing a compacted context from a captured trace.
-- **Advanced verification** — stronger checks on what a compacted context retains.
-- **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.
+**NOT in the npm / free CLI** (these are the opt-in Compaction API — **not a live hosted service
+yet**):
 
-> **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
-> the free CLI. The honesty rails carry over unchanged: cost stays an **estimate** unless
-> billing-confirmed (no figure carries that label today); verification is **deterministic
-> recoverability, NOT semantic/meaning preservation**; and there is **no auto-apply** — every
-> application is an explicit operator gesture.
+- the **LCM / learned context model**,
+- the **learned optimization engine**,
+- the **hosted / team control plane**,
+- **verified-savings** logic,
+- **advanced proprietary evals** (and recommendation / advanced verification / apply-guidance / advanced policies).
+
+> **The Compaction API is not broadly hosted yet.** There is **no live hosted service today**. The
+> honesty rails carry over unchanged: cost stays an **estimate** unless billing-confirmed (no figure
+> carries that label today); verification is **deterministic recoverability, NOT semantic/meaning
+> preservation**; and there is **no auto-apply** — every application is an explicit operator gesture.
 
 ## Install
 
-A local-first CLI. It makes no network calls by default; the only command that reaches the
-network is the explicitly operator-invoked `capture provider-usage`. There is no telemetry.
+A local-first CLI. **No telemetry and no upload to Compaction.** Network happens only when you
+explicitly call provider-usage (`capture provider-usage`) or route your own provider traffic through
+the local gateway (which forwards it to your provider). Nothing else reaches the network.
 
 ### npm / npx
 
 ```bash
-npm install -g @compaction/cli   # then: compaction init
+npm install -g @compaction/cli   # then: compaction
 npx @compaction/cli init         # no global install
 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.1`) and `compaction --help`. Run `compaction` (no args) to open
+onboarding, including **Gateway setup**.
 
 ### curl one-liner
 
@@ -94,23 +135,29 @@ curl -fsSL https://cli.compaction.dev/install | sh -s -- --dry-run
 
 ## Quick start
 
-Run on **your own** captured/imported workflow — not a demo. The recommended free local loop is
-**capture → analyze → (local report) → redact / share**:
+Two local loops, both on **your own** workflow — not a demo.
+
+**Route your traffic through the local Gateway** (byte-safe; content-free receipts):
 
 ```bash
-compaction init                  # one-time local scaffold (writes nothing until you capture)
-# 1. Capture a real workflow (Claude Code shown; --discover lists local sessions):
-compaction capture claude-code --discover
+compaction gateway start                  # start the local gateway (RECORD mode)
+compaction gateway run -- npm run dev      # or point your OpenAI client's baseURL at the listen address + /v1
+compaction gateway status                  # see requests observed + the content-free receipts rollup
+```
+
+**Capture + measure an agent trace** (local files only):
+
+```bash
+compaction init                           # one-time local scaffold (writes nothing until you capture)
+compaction capture claude-code --discover # list local Claude Code sessions
 compaction capture claude-code --session <session.jsonl> --out ./my-trace
-# 2. Measure tokens + estimated spend, and see where it came from:
-compaction analyze ./my-trace/captured-trace.json
-compaction spend ./my-trace/captured-trace.json
-# 3. Share a redacted, content-free bundle (local file only, never uploaded):
-compaction feedback --redact --yes
+compaction analyze ./my-trace/captured-trace.json   # tokens + estimated spend, honestly labeled
+compaction feedback --redact --yes        # redacted, content-free bundle (local file only, never uploaded)
 ```
 
-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.
+Advanced verification, recommendation, and apply guidance are the opt-in Compaction API — not steps
+of the free local CLI.
 
 ## Supported local workflows
 
@@ -126,14 +173,29 @@ free local CLI.
   `codex exec --json` export) and normalizes it. **Level 1.** Codex token counts on this path are
   **locally estimated (chars/4)**, not provider-reported. `compaction import --list-sources` lists
   supported sources.
+- **OpenAI-compatible clients via the local Gateway** — any OpenAI-compatible client can route
+  through `compaction gateway` for content-free receipts (and, opt-in, explicit deterministic apply).
 
-There is **no** native/Level 3 SDK instrumentation, no production proxy, no model routing, and no
+There is **no** native/Level 3 SDK instrumentation, **no hosted/managed proxy or model routing**
+(the local Gateway is an OpenAI-compatible reverse proxy for compatible clients), and no
 consumer-app (ChatGPT/Claude desktop) support.
 
 ## Commands
 
 ```bash
+compaction                                       # onboarding (workflow chooser + Gateway setup)
 compaction init                                  # one-time local scaffold
+
+# Gateway (local, byte-safe):
+compaction gateway start                         # start the local gateway (RECORD mode)
+compaction gateway run -- <command>              # run a command through the gateway
+compaction gateway status                        # requests observed + content-free receipts rollup
+compaction gateway activate                      # print env exports (eval-able); prints only, no mutation
+compaction gateway configure                     # approval-gated: propose a project baseURL (diff, no write without --apply)
+compaction gateway recover <recovery_id>         # recover the original request retained by apply mode
+compaction gateway stop                          # stop a running local gateway
+
+# Trace / capture utilities:
 compaction capture claude-code --session <session.jsonl> [--include-subagents] --out <dir>
 compaction capture claude-code --discover [--projects-dir <path>]
 compaction capture openai-agents --out <dir> -- <command> [args...]
@@ -141,6 +203,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
@@ -149,15 +212,20 @@ compaction aggregate                             # per-session / cross-session l
 compaction feedback --redact [--yes]             # redacted, local-only share bundle
 ```
 
-`compaction --help` lists the free local commands.
+`compaction --help` lists the free local commands; `compaction gateway --help` lists the gateway commands.
 
 ## Privacy and security
 
-- **No telemetry; no upload by default.** The free CLI is local-first and file-based.
-- **One network call only.** `capture provider-usage` is explicitly operator-invoked and read-only;
-  its credential comes from an **environment variable only** (never a flag value, never logged,
-  never written into artifacts), and it captures **aggregate** usage/cost figures only — no
-  prompt/completion content. Its absence is a clean refusal.
+- **No telemetry; no upload to Compaction.** The free CLI is local-first and file-based.
+- **Network only on explicit action.** Network happens only when you explicitly call
+  `capture provider-usage` (read-only; credential via an **environment variable only**, never a flag
+  value, never logged, never written into artifacts; **aggregate** usage/cost figures only — no
+  prompt/completion content) **or** route your own provider traffic through the local gateway (which
+  forwards it to your provider; your provider key stays on the client and is never read or stored).
+- **Content-free gateway receipts.** Gateway receipts record token/cache counts and labels only —
+  never prompt/response content; they are local-only (gitignored). Apply mode retains the original
+  request **locally** (restrictive permissions) so it is recoverable; that original is referenced
+  from receipts by id only.
 - **Captured traces can contain local content.** Capturing a session may include local file
   content — review a trace before sharing it.
 - **Redacted sharing.** `feedback --redact` produces a redacted, content-free bundle as a local
@@ -171,17 +239,24 @@ Every figure this tool produces carries one of these labels — and nothing stro
 | Label | Meaning |
 |---|---|
 | **local estimate** | chars/4 token heuristics and price-table cost approximations computed locally |
-| **provider-reported token delta** | token counts read from the provider's own API response/usage metadata (operator-entered or captured); input tokens are deterministic for a fixed context+prompt |
+| **provider-reported token delta** | token counts read from the provider's own API response/usage metadata (operator-entered, captured, or via the gateway); input tokens are deterministic for a fixed context+prompt |
 | **token-estimated cost** | a price-table estimate applied to provider-reported token counts (`price_table_estimate`) — an estimate, never a billed figure |
 | **operator-entered billing record** | billed costs the operator read from their own provider console; recorded, not provider-verified by this tool |
 | **billing-confirmed** | only with real provider billing/invoice evidence **AND** the accepted measurement criterion met on those billed runs (N ≥ 3 runs per arm AND the delta-of-means ±2·SE interval excludes zero) — the statistical criterion alone is a bar on operator-entered figures, not proof of billing, so it is never sufficient by itself — **no figure in this repository currently carries this label** |
 
-**What is NOT claimed:** no billing-confirmed savings claim; no invoice savings claim; no general savings claim (all results are workflow-scoped and caveated); no auto-apply (every application is an explicit operator gesture); no hosted service or control plane (the free CLI is local-first, file-based); no universal "no context is lost" claim; no semantic/meaning preservation claim (it stays `not_evaluated`); no native/production/Level 3 integration claim.
+**What is NOT claimed:** no billing-confirmed savings claim; no invoice savings claim; no
+output-token savings claim unless measured before/after **and** eval-confirmed; no general savings
+claim (all results are workflow-scoped and caveated); no auto-apply (every application is an explicit
+operator gesture); no hosted service or control plane, and **no hosted-live claim** (the free CLI +
+Gateway are local-first, file-based); no universal "no context is lost" claim; no semantic/meaning
+preservation claim (it stays `not_evaluated`); no native/production/Level 3 integration claim.
 
 ## 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** —
+- **The free CLI runs the local Gateway, captures/measures traces, and compacts deterministically;
+  it does not perform advanced verification.** The LCM / learned optimization engine, hosted/team
+  control plane, verified savings, advanced proprietary evals, recommendation, advanced verification
+  (incl. `compact --eval`), apply guidance, and advanced policies 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/
@@ -189,14 +264,17 @@ Every figure this tool produces carries one of these labels — and nothing stro
 - **Token counts are local estimates unless provider-reported usage is captured.** The default is a
   chars/4 estimate, labeled as such. Unknown stays unknown — output tokens, provider, or cost the
   data does not carry are never inferred.
+- **Gateway apply is experimental, deterministic, and opt-in.** It removes only exact-duplicate large
+  blocks from known-safe request shapes, retains the original locally, and fails closed on anything
+  else; it makes no output-token or cost claim, and never claims meaning preservation or "no context
+  lost". Record mode is the byte-safe default.
 - **Integrations are Level 1/2, not native/production.** Claude Code and OpenAI Agents capture are
   Level 2 local command-wrappers; Codex/local-file import is Level 1. There is **no** native/Level 3
-  SDK instrumentation, no production proxy, no model routing, and no consumer-app support.
+  SDK instrumentation, **no hosted/managed proxy or model routing**, and no consumer-app support.
 - **Verification (opt-in API) is deterministic recoverability, not semantic preservation.** Where
   the opt-in API verifies a compacted context, it checks deterministic recoverability for a
   supported workflow; it does **not** evaluate meaning or task equivalence and does **not** re-run
-  your agent through a model. Semantic / meaning preservation remains **not evaluated**; true model
-  replay is future work.
+  your agent through a model. Semantic / meaning preservation remains **not evaluated**.
 - **No universal "no context is lost" guarantee.** Any apply-guidance verdict from the opt-in API
   is **fail-closed and scoped** to supported developer-agent workflows — never a universal
   guarantee, and never a semantic/meaning claim.

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).