openlimiter 0.2.0 → 1.2.0

package/README.md

@@ -16,6 +16,27 @@ openlimiter demo
 
 The demo uses synthetic data and does not read a provider account.
 
+## Agent context hooks
+
+Install or remove a user scoped hook explicitly:
+
+```bash
+openlimiter hooks install codex
+openlimiter hooks uninstall codex
+openlimiter hooks status codex
+openlimiter hooks repair codex
+```
+
+Installation preserves unrelated agent configuration, writes a recoverable backup, performs no network request, and refuses a version below the tested minimum or an unsafe configuration path. A newer version remains enabled and `hooks status` prints one warning line. Hook execution reads only the short lived local snapshot and the protected desktop trust bridge, then fails open with no context on any invalid or missing input.
+
+Antigravity CLI injection is excluded because `agy 1.1.23` did not fire the IDE hook shapes in a real prompt fixture. Kimi Code CLI installation stays gated because `1.50.0` fired `UserPromptSubmit` but discarded successful hook stdout instead of adding it to model context.
+
+Grok Build does not currently expose a documented dynamic context surface. Its `UserPromptSubmit` hook discards successful stdout, so OpenLimiter does not install a Grok hook or claim injection support. Use the explicit command instead:
+
+```bash
+openlimiter status --agent-context
+```
+
 ## Provider inputs
 
 | Provider | How data reaches OpenLimiter |

package/dist/bin.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { createInterface } from "node:readline/promises";
+import { HOOK_INPUT_MAX_BYTES } from "@openlimiter/adapters";
 import { runCli } from "./cli.js";
-import { readStandardInputText } from "./ingest.js";
+import { readStandardInputBuffer, readStandardInputText } from "./ingest.js";
+import { decodeWrappedStatuslineCommand, runStatuslineWrapper } from "./statusline-wrapper.js";
 async function promptForSecret() {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         return "";
@@ -16,13 +18,42 @@ async function promptForSecret() {
         interfaceHandle.close();
     }
 }
-const result = await runCli(process.argv.slice(2), {
-    promptForSecret,
-    readStandardInput: () => readStandardInputText()
-});
-if (result.stdout !== "")
-    process.stdout.write(result.stdout + "\n");
-if (result.stderr !== "")
-    process.stderr.write(result.stderr + "\n");
-process.exitCode = result.exitCode;
+const argumentsList = process.argv.slice(2);
+const wrapperRequested = argumentsList[0] === "statusline" && argumentsList[1] === "--wrap";
+const wrapped = wrapperRequested
+    ? decodeWrappedStatuslineCommand(argumentsList[2] ?? "")
+    : null;
+if (wrapperRequested && wrapped === null) {
+    /* A damaged wrapper command must fail invisibly, never fall through to the
+       OpenLimiter renderer and replace the user's visible status line. */
+    process.exitCode = 0;
+}
+else if (wrapped !== null) {
+    const payload = await readStandardInputBuffer();
+    const result = await runStatuslineWrapper(payload, wrapped, {
+        ingest: async (buffer) => {
+            await runCli(["statusline"], {
+                readStandardInput: async () => buffer.toString("utf8")
+            });
+        }
+    });
+    if (result.stdout.length > 0)
+        process.stdout.write(result.stdout);
+    if (result.stderr.length > 0)
+        process.stderr.write(result.stderr);
+    process.exitCode = result.exitCode;
+}
+else {
+    const result = await runCli(argumentsList, {
+        promptForSecret,
+        readStandardInput: (signal) => argumentsList[0] === "hook"
+            ? readStandardInputText(process.stdin, HOOK_INPUT_MAX_BYTES, undefined, signal)
+            : readStandardInputText()
+    });
+    if (result.stdout !== "")
+        process.stdout.write(result.stdout + "\n");
+    if (result.stderr !== "")
+        process.stderr.write(result.stderr + "\n");
+    process.exitCode = result.exitCode;
+}
 //# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,KAAK,UAAU,eAAe;IAC5B,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAC7D,MAAM,eAAe,GAAG,eAAe,CAAC;QACtC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,eAAe,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAC5D,CAAC;YAAS,CAAC;QACT,eAAe,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACjD,eAAe;IACf,iBAAiB,EAAE,GAAG,EAAE,CAAC,qBAAqB,EAAE;CACjD,CAAC,CAAC;AACH,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE;IAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AACrE,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE;IAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AACrE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 import { type ProviderFailure, type Snapshot } from "@openlimiter/core";
+import { type AgentId, type AgentInstallation, type HostedContextTrust, type HostedTrustLoadOptions } from "@openlimiter/adapters";
 import { type CredentialStore } from "./credentials.js";
 import { type QuotaServerHandle } from "./serve.js";
 export interface CliDependencies {
@@ -15,7 +16,7 @@ export interface CliDependencies {
      * reader, which keeps every command deterministic when it is called in
      * process by a test or another tool.
      */
-    readStandardInput: () => Promise<string | null>;
+    readStandardInput: (signal?: AbortSignal) => Promise<string | null>;
     /**
      * Whether output may carry terminal colour.
      *
@@ -26,6 +27,22 @@ export interface CliDependencies {
      * capture redirected into a file carries no control characters at all.
      */
     colorOutput: boolean;
+    homeDirectory: string;
+    openLimiterScript: string;
+    nodeExecutable: string;
+    platform: NodeJS.Platform;
+    detectedAgentInstallations: Readonly<Partial<Record<AgentId, AgentInstallation | null>>>;
+    hostedContextTrust?: HostedContextTrust;
+    hostedContextPublicKeys?: HostedTrustLoadOptions["pinnedPublicKeys"];
+    hostedTrustConfigRoot?: string;
+    /**
+     * How the Windows owner and permissions of the trust file are read.
+     *
+     * The library default asks the operating system. A test injects a recorded
+     * answer instead, so a hostile ownership case can be proved without touching
+     * the security of a real file.
+     */
+    hostedTrustWindowsSecurity?: HostedTrustLoadOptions["windowsSecurity"];
     /**
      * Called once the serve command is listening.
      *

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAcL,KAAK,eAAe,EAEpB,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAuC3B,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAYpB,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,eAAe,CAAC;IACjC,eAAe,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,IAAI,CAAC;AA6C9B,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CACtC;AAqgBD,wBAAsB,MAAM,CAC1B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GACvC,OAAO,CAAC,SAAS,CAAC,CAiDpB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAcL,KAAK,eAAe,EAEpB,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAoB3B,OAAO,EAWL,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAG5B,MAAM,uBAAuB,CAAC;AA0B/B,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAYpB,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,eAAe,CAAC;IACjC,eAAe,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpE;;;;;;;;OAQG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,0BAA0B,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACzF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,uBAAuB,CAAC,EAAE,sBAAsB,CAAC,kBAAkB,CAAC,CAAC;IACrE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,0BAA0B,CAAC,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IACvE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,IAAI,CAAC;AA2E9B,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CACtC;AAoxBD,wBAAsB,MAAM,CAC1B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GACvC,OAAO,CAAC,SAAS,CAAC,CAiDpB"}

package/dist/cli.js

@@ -1,8 +1,9 @@
 import { PROVIDER_CODES, buildAdvice, canonicalJson, dedupeFailures, failureFromConnectorReason, freshness, mergeSnapshots, normalizeMeters, normalizeMetersReport, readSnapshotCache } from "@openlimiter/core";
-import { antigravityFixture, claudeFixture, codexFixture, connectors, manualFixture, opencodeFixture, openrouterFixture, parseAntigravityPayload, parseClaudePayload, parseCodexPayload, parseManualPayload, parseOpencodePayload, parseOpenrouterPayload } from "@openlimiter/connectors";
-import { agentContextFromCache, renderClaudeStatusline } from "@openlimiter/adapters";
+import { antigravityFixture, claudeFixture, codexFixture, grokFixture, kimiFixture, connectors, manualFixture, opencodeFixture, openrouterFixture, parseAntigravityPayload, parseClaudePayload, parseCodexPayload, parseGrokPayload, parseKimiPayload, parseManualPayload, parseOpencodePayload, parseOpenrouterPayload } from "@openlimiter/connectors";
+import { AGENT_COMPATIBILITY, agentContextFromCache, agentContextSpillFromCache, agentVersionCompatibility, changeAgentHook, detectAgentInstallation, readAgentHookStatus, runAgentHook, validateAgentExecutableStamp, writeAgentContextSnapshot, loadHostedContextTrust, renderClaudeStatusline } from "@openlimiter/adapters";
+import { homedir } from "node:os";
 import { STATUSLINE_KEYS, defaultConfig, initialize, isStatuslineKey, readConfig, readStatuslineConfig, setStatuslineValue, statuslineValueText, writeConfig } from "./config.js";
-import { environmentWithLocalMarkers, parseJsonText, persistSnapshots, readManualDocument } from "./ingest.js";
+import { INGEST_PROVENANCE, MANUAL_PROVENANCE, STATUSLINE_PROVENANCE, environmentWithLocalMarkers, STDIN_BYTE_LIMIT, parseJsonText, persistSnapshots, readManualDocument, withProvenance } from "./ingest.js";
 import { UnavailableCredentialStore } from "./credentials.js";
 import { DEFAULT_SERVE_PORT, serveBanner, startQuotaServer } from "./serve.js";
 import { failureLine, failureLines, renderTable, supportsColor } from "./render.js";
@@ -20,12 +21,37 @@ function defaults() {
         now: () => new Date().toISOString(),
         payloads: {},
         readStandardInput: async () => null,
-        colorOutput: supportsColor(process.env, process.stdout.isTTY === true)
+        colorOutput: supportsColor(process.env, process.stdout.isTTY === true),
+        homeDirectory: homedir(),
+        openLimiterScript: process.argv[1] ?? "",
+        nodeExecutable: process.execPath,
+        platform: process.platform,
+        detectedAgentInstallations: {}
     };
 }
 function succeed(stdout) {
     return { exitCode: EXIT_OK, stdout, stderr: "" };
 }
+async function resolvedHostedTrust(dependencies, now, signal) {
+    if (dependencies.hostedContextTrust !== undefined) {
+        return dependencies.hostedContextTrust;
+    }
+    return await loadHostedContextTrust({
+        homeDirectory: dependencies.homeDirectory,
+        platform: dependencies.platform,
+        now,
+        ...(signal === undefined ? {} : { signal }),
+        ...(dependencies.hostedContextPublicKeys === undefined
+            ? {}
+            : { pinnedPublicKeys: dependencies.hostedContextPublicKeys }),
+        ...(dependencies.hostedTrustConfigRoot === undefined
+            ? {}
+            : { trustedPlatformConfigRoot: dependencies.hostedTrustConfigRoot }),
+        ...(dependencies.hostedTrustWindowsSecurity === undefined
+            ? {}
+            : { windowsSecurity: dependencies.hostedTrustWindowsSecurity })
+    });
+}
 function fail(exitCode, message, stdout = "") {
     return { exitCode, stdout, stderr: message };
 }
@@ -62,6 +88,12 @@ async function refresh(dependencies, now) {
     const manual = supplied === undefined
         ? await readManualDocument(dependencies.stateDirectory)
         : supplied;
+    /*
+     * The manual connector is the only one this command reads from disk on its
+     * own, so it is the only one whose provenance is the document. Everything
+     * else here was handed in by a caller, which is an import by any other name.
+     */
+    const manualFromDisk = supplied === undefined;
     const environment = await environmentWithLocalMarkers(dependencies.environment, dependencies.stateDirectory);
     const raw = [];
     const failures = [];
@@ -71,7 +103,10 @@ async function refresh(dependencies, now) {
             : dependencies.payloads[connector.id];
         const result = await connector.read({ payload, now, environment });
         if (result.ok) {
-            raw.push(...result.meters);
+            const provenance = connector.id === "manual" && manualFromDisk
+                ? MANUAL_PROVENANCE
+                : INGEST_PROVENANCE;
+            raw.push(...withProvenance(result.meters, provenance));
             continue;
         }
         if (payload === undefined)
@@ -87,7 +122,7 @@ async function refresh(dependencies, now) {
     }
     if (report.snapshots.length === 0)
         return { snapshots: [], failures };
-    const persisted = await persistSnapshots(report.snapshots, dependencies.stateDirectory);
+    const persisted = await persistSnapshots(report.snapshots, dependencies.stateDirectory, now);
     return { snapshots: persisted.merged, failures };
 }
 function demoSnapshots(now) {
@@ -95,11 +130,13 @@ function demoSnapshots(now) {
         ...(parseClaudePayload(claudeFixture(now), now) ?? []),
         ...(parseOpenrouterPayload(openrouterFixture(), now) ?? []),
         ...(parseCodexPayload(codexFixture(now), now) ?? []),
+        ...(parseGrokPayload(grokFixture(now), now) ?? []),
+        ...(parseKimiPayload(kimiFixture(now), now) ?? []),
         ...(parseAntigravityPayload(antigravityFixture(now), now) ?? []),
         ...(parseOpencodePayload(opencodeFixture(now), now) ?? []),
         ...(parseManualPayload(manualFixture(now), now) ?? [])
     ];
-    return normalizeMeters(raw);
+    return normalizeMeters(withProvenance(raw, INGEST_PROVENANCE));
 }
 function doctorRows(snapshots, environment, now) {
     const lines = ["CONNECTOR DETECTED FRESHNESS DRIFT"];
@@ -127,6 +164,11 @@ const help = [
     "openlimiter snapshot [--refresh]",
     "openlimiter statusline",
     "openlimiter hook [--dry-run]",
+    "openlimiter hooks install <agent>",
+    "openlimiter hooks uninstall <agent>",
+    "openlimiter hooks status <agent>",
+    "openlimiter hooks repair <agent>",
+    "openlimiter status --agent-context",
     "openlimiter ingest [--provider <id>] [--payload <json>]",
     "openlimiter config get statusline[.<key>]",
     "openlimiter config set statusline.<key> <value>",
@@ -157,11 +199,13 @@ async function ingestStandardInput(dependencies, now) {
         const meters = parseClaudePayload(document.value, now);
         if (meters === null)
             return null;
-        const incoming = normalizeMeters(meters);
+        /* Claude Code wrote this to our standard input in this session. It is the
+           one live reading the product currently has, and it says so. */
+        const incoming = normalizeMeters(withProvenance(meters, STATUSLINE_PROVENANCE));
         if (incoming.length === 0)
             return null;
         try {
-            return (await persistSnapshots(incoming, dependencies.stateDirectory)).merged;
+            return (await persistSnapshots(incoming, dependencies.stateDirectory, now)).merged;
         }
         catch {
             const existing = await cachedSnapshots(dependencies.stateDirectory);
@@ -198,9 +242,16 @@ async function snapshotCommand(dependencies, argumentsList, now) {
     }
     const cached = await readSnapshotCache(dependencies.stateDirectory);
     if (!cached.ok && cached.reason !== "missing") {
+        await writeAgentContextSnapshot([], dependencies.stateDirectory, now, PROVIDER_CODES).catch(() => undefined);
         return fail(EXIT_FAILURE, "openlimiter snapshot: quota state could not be read.");
     }
     const snapshots = cached.ok ? cached.snapshots : [];
+    try {
+        await writeAgentContextSnapshot(snapshots, dependencies.stateDirectory, now, PROVIDER_CODES);
+    }
+    catch {
+        return fail(EXIT_FAILURE, "openlimiter snapshot: agent context could not be written.");
+    }
     const stdout = withFailures(renderTable(snapshots, now, dependencies.colorOutput), failures, dependencies.colorOutput);
     return snapshots.length === 0
         ? fail(EXIT_NO_DATA, "openlimiter snapshot: no bounded quota data is available.", stdout)
@@ -273,14 +324,24 @@ async function ingestCommand(dependencies, argumentsList, now) {
         return fail(EXIT_USAGE, "openlimiter ingest: the payload flag needs a value.");
     }
     const text = inline ?? await dependencies.readStandardInput();
-    const document = parseJsonText(text);
-    if (!document.ok) {
-        return text === null || text.trim() === ""
-            ? fail(EXIT_USAGE, "openlimiter ingest: no input was supplied on standard input.")
-            : fail(EXIT_FAILURE, "openlimiter ingest: input is not valid JSON.");
-    }
+    if (text === null || text.trim() === "") {
+        return fail(EXIT_USAGE, "openlimiter ingest: no input was supplied on standard input.");
+    }
+    /*
+     * The connector says what its payload IS, and this boundary obeys it.
+     *
+     * Assuming JSON here made the OpenCode reader unreachable from this command
+     * entirely: its payload is a logged in HTML page, so every real capture died
+     * at JSON.parse with "input is not valid JSON" and no page could ever be
+     * ingested. A text connector is handed the raw text, bounded exactly as the
+     * JSON path is bounded, and nothing is parsed on its behalf.
+     */
     let meters;
     if (provider === undefined) {
+        const document = parseJsonText(text);
+        if (!document.ok) {
+            return fail(EXIT_FAILURE, "openlimiter ingest: input is not valid JSON.");
+        }
         meters = parseManualPayload(document.value, now);
     }
     else {
@@ -288,19 +349,40 @@ async function ingestCommand(dependencies, argumentsList, now) {
         if (connector === undefined) {
             return fail(EXIT_USAGE, "openlimiter ingest: unknown provider.");
         }
+        let payload;
+        if (connector.encoding === "text") {
+            if (text.length > STDIN_BYTE_LIMIT) {
+                return fail(EXIT_FAILURE, "openlimiter ingest: input is larger than accepted.");
+            }
+            payload = text;
+        }
+        else {
+            const document = parseJsonText(text);
+            if (!document.ok) {
+                return fail(EXIT_FAILURE, "openlimiter ingest: input is not valid JSON.");
+            }
+            payload = document.value;
+        }
         const result = await connector.read({
-            payload: document.value,
+            payload,
             now,
             environment: dependencies.environment
         });
         meters = result.ok ? result.meters : null;
     }
-    const incoming = meters === null ? [] : normalizeMeters([...meters]);
+    /*
+     * However this document reached the command, a person handed it over. It is
+     * an import, not a live reading, whichever connector parsed it, and a card
+     * that showed it as live would be the exact claim this wave exists to stop.
+     */
+    const incoming = meters === null
+        ? []
+        : normalizeMeters(withProvenance(meters, INGEST_PROVENANCE));
     if (incoming.length === 0) {
         return fail(EXIT_FAILURE, "openlimiter ingest: no bounded meter survived validation.");
     }
     try {
-        const persisted = await persistSnapshots(incoming, dependencies.stateDirectory);
+        const persisted = await persistSnapshots(incoming, dependencies.stateDirectory, now);
         return succeed("Ingested " + String(incoming.length) +
             " bounded meters. Cached meters: " + String(persisted.merged.length) + ".");
     }
@@ -323,6 +405,9 @@ async function ingestCommand(dependencies, argumentsList, now) {
 async function statuslineCommand(dependencies, now) {
     const ingested = await ingestStandardInput(dependencies, now);
     const snapshots = ingested ?? await cachedSnapshots(dependencies.stateDirectory);
+    if (ingested === null) {
+        await writeAgentContextSnapshot(snapshots, dependencies.stateDirectory, now, PROVIDER_CODES).catch(() => undefined);
+    }
     const advice = buildAdvice(snapshots, now, PROVIDER_CODES);
     const config = await readStatuslineConfig(dependencies.stateDirectory);
     if (!config.bars)
@@ -335,6 +420,165 @@ async function statuslineCommand(dependencies, now) {
         color: statuslineColor(config.color, dependencies.environment, dependencies.colorOutput)
     }));
 }
+const agentAliases = {
+    agy: "antigravity",
+    antigravity: "antigravity",
+    claude: "claude",
+    codex: "codex",
+    gemini: "gemini",
+    grok: "grok",
+    "grok-build": "grok",
+    kimi: "kimi",
+    opencode: "opencode"
+};
+function agentArgument(value) {
+    return value === undefined ? null : agentAliases[value.toLowerCase()] ?? null;
+}
+async function hookProtocolCommand(dependencies, argumentsList, now) {
+    const agentFlag = flagValue(argumentsList, "--agent");
+    if (agentFlag === undefined) {
+        const hostedTrust = await resolvedHostedTrust(dependencies, now);
+        return succeed(await agentContextFromCache(dependencies.stateDirectory, now, PROVIDER_CODES, hostedTrust === undefined ? {} : { hostedTrust }));
+    }
+    const agent = agentArgument(agentFlag);
+    const hostVersion = flagValue(argumentsList, "--host-version");
+    if (agent === null || hostVersion === undefined)
+        return succeed("");
+    if (agent === "opencode" &&
+        dependencies.environment["OPENLIMITER_EXPERIMENTAL_OPENCODE"] !== "1")
+        return succeed("");
+    const fallback = () => succeed(runAgentHook({
+        agent,
+        hostVersion,
+        rawInput: null,
+        context: ""
+    }).stdout);
+    /*
+     * The deadline both chooses the answer and cancels the work behind it.
+     * Racing alone left the loser running, so a slow read could still reach the
+     * context cache and rewrite a spill file long after the host had been given
+     * its reply. Every step below sees the same signal and stops at it.
+     */
+    const deadline = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            deadline.abort();
+            resolve(fallback());
+        }, 450);
+    });
+    const work = (async () => {
+        if (flagValue(argumentsList, "--managed-hook") === "openlimiter-v1") {
+            const executable = flagValue(argumentsList, "--agent-executable");
+            const fileSize = Number(flagValue(argumentsList, "--agent-file-size"));
+            const mtime = Number(flagValue(argumentsList, "--agent-mtime-ms"));
+            if (executable === undefined ||
+                !(await validateAgentExecutableStamp(executable, fileSize, mtime)))
+                return fallback();
+        }
+        const rawInput = await dependencies.readStandardInput(deadline.signal);
+        if (deadline.signal.aborted)
+            return fallback();
+        const hostedTrust = await resolvedHostedTrust(dependencies, now, deadline.signal);
+        if (deadline.signal.aborted)
+            return fallback();
+        const context = await agentContextFromCache(dependencies.stateDirectory, now, PROVIDER_CODES, {
+            ...(hostedTrust === undefined ? {} : { hostedTrust }),
+            signal: deadline.signal
+        });
+        return succeed(runAgentHook({ agent, hostVersion, rawInput, context }).stdout);
+    })();
+    /* The race still sees a failure that arrives in time. This second handler
+       only keeps a failure that arrives too late from becoming an unhandled
+       rejection in the host process. */
+    void work.catch(() => undefined);
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        deadline.abort();
+    }
+}
+async function hooksCommand(dependencies, argumentsList) {
+    const requestedAction = argumentsList[1];
+    const action = requestedAction === "repair" ? "install" : requestedAction;
+    const agent = agentArgument(argumentsList[2]);
+    if ((action !== "install" && action !== "uninstall" && action !== "status") ||
+        agent === null) {
+        return fail(EXIT_USAGE, "openlimiter hooks: use install, uninstall, status, or repair with a known agent.");
+    }
+    if (action === "status") {
+        const status = await readAgentHookStatus(agent, {
+            homeDirectory: dependencies.homeDirectory
+        });
+        const hasKnownInstallation = Object.prototype.hasOwnProperty.call(dependencies.detectedAgentInstallations, agent);
+        const installation = hasKnownInstallation
+            ? dependencies.detectedAgentInstallations[agent] ?? null
+            : await detectAgentInstallation(agent, {
+                environment: dependencies.environment,
+                platform: dependencies.platform
+            });
+        const gate = AGENT_COMPATIBILITY[agent];
+        const compatibility = installation === null
+            ? null
+            : agentVersionCompatibility(agent, installation.version);
+        const location = status.configPath ?? "NONE";
+        return succeed([
+            "agent=" + agent,
+            "installed=" + (status.installed ? "yes" : "no"),
+            "config=" + location,
+            ...(compatibility === "newer" && gate.minimumTestedVersion !== null
+                ? [
+                    "warning=detected version " + installation.version +
+                        " is newer than minimum tested " + gate.minimumTestedVersion
+                ]
+                : [])
+        ].join("\n"));
+    }
+    const knownInstallation = Object.prototype.hasOwnProperty.call(dependencies.detectedAgentInstallations, agent) ? dependencies.detectedAgentInstallations[agent] : undefined;
+    const result = await changeAgentHook(agent, action, {
+        homeDirectory: dependencies.homeDirectory,
+        openLimiterScript: dependencies.openLimiterScript,
+        nodeExecutable: dependencies.nodeExecutable,
+        environment: dependencies.environment,
+        platform: dependencies.platform,
+        ...(knownInstallation === undefined
+            ? {}
+            : knownInstallation === null
+                ? { detectedVersion: null }
+                : {
+                    detectedVersion: knownInstallation.version,
+                    agentExecutable: knownInstallation.executable,
+                    agentFileSize: knownInstallation.fileSize,
+                    agentMtimeMilliseconds: knownInstallation.mtimeMilliseconds
+                })
+    });
+    const preview = [
+        "agent=" + result.agent,
+        "action=" + result.action,
+        "changed=" + (result.changed ? "yes" : "no"),
+        "config=" + (result.configPath ?? "NONE"),
+        "backup=" + (result.backupPath ?? "NONE"),
+        "version=" + (result.version ?? "NONE")
+    ].join("\n");
+    return result.supported
+        ? succeed(preview)
+        : fail(EXIT_FAILURE, "openlimiter hooks: " + result.message, preview);
+}
+async function explicitStatusCommand(dependencies, argumentsList, now) {
+    if (!argumentsList.includes("--agent-context")) {
+        return fail(EXIT_USAGE, "openlimiter status: use --agent-context.");
+    }
+    const hostedTrust = await resolvedHostedTrust(dependencies, now);
+    const context = await agentContextFromCache(dependencies.stateDirectory, now, PROVIDER_CODES, hostedTrust === undefined ? {} : { hostedTrust });
+    const spill = await agentContextSpillFromCache(dependencies.stateDirectory, now);
+    const stdout = [context, spill].filter((value) => value !== "").join("\n");
+    return stdout === ""
+        ? fail(EXIT_NO_DATA, "openlimiter status: no current agent context is available.")
+        : succeed(stdout);
+}
 /* --------------------------------------------------------------- config */
 /** The one section this command reads and writes. */
 const CONFIG_SECTION = "statusline";
@@ -472,7 +716,12 @@ export async function runCli(argumentsList, overrides = {}) {
             return await configCommand(dependencies, argumentsList);
         }
         if (command === "hook") {
-            return succeed(await agentContextFromCache(dependencies.stateDirectory, now, PROVIDER_CODES));
+            return await hookProtocolCommand(dependencies, argumentsList, now);
+        }
+        if (command === "hooks")
+            return await hooksCommand(dependencies, argumentsList);
+        if (command === "status") {
+            return await explicitStatusCommand(dependencies, argumentsList, now);
         }
         if (command === "doctor")
             return await doctorCommand(dependencies, now);