@kill-switch/agent-guard 0.1.0

package/dist/config.js

@@ -0,0 +1,111 @@
+/**
+ * Configuration & paths for agent-guard.
+ *
+ * Resolution order (later wins): built-in defaults → config file
+ * (~/.kill-switch/agent-guard/config.json) → environment variables.
+ * Env override lets you set a tighter budget for a single risky run without
+ * editing files, e.g. `AGENT_GUARD_SESSION_HARD=10 claude`.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+export const DEFAULT_BUDGET = {
+    sessionSoftUSD: 5,
+    sessionHardUSD: 20,
+    dailySoftUSD: 25,
+    dailyHardUSD: 100,
+};
+/** ~/.kill-switch/agent-guard — created on demand. */
+export function guardDir() {
+    return join(homedir(), ".kill-switch", "agent-guard");
+}
+export function ensureGuardDir() {
+    const dir = guardDir();
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export const ledgerPath = () => join(guardDir(), "ledger.json");
+export const configPath = () => join(guardDir(), "config.json");
+export const pricingPath = () => join(guardDir(), "pricing.json");
+export const eventsPath = () => join(guardDir(), "events.jsonl");
+/**
+ * Escape hatch. The hook/proxy fail OPEN while this sentinel exists, so a human
+ * can always disable enforcement from outside the agent loop — even with zero
+ * tooling: `touch ~/.kill-switch/agent-guard/PAUSED`.
+ *
+ * An empty file pauses indefinitely; a file containing an epoch-ms number pauses
+ * until that time, then enforcement resumes on its own.
+ */
+export const pausePath = () => join(guardDir(), "PAUSED");
+/** True if enforcement is currently paused (sentinel present and not expired). */
+export function isPaused(now) {
+    try {
+        const raw = readFileSync(pausePath(), "utf8").trim();
+        if (!raw)
+            return true; // indefinite
+        const until = Number(raw);
+        return Number.isFinite(until) ? now < until : true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read the pause expiry (epoch ms), or null if indefinite/not paused. */
+export function pauseExpiry() {
+    try {
+        const raw = readFileSync(pausePath(), "utf8").trim();
+        const until = Number(raw);
+        return raw && Number.isFinite(until) ? until : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writePause(untilMs) {
+    ensureGuardDir();
+    writeFileSync(pausePath(), untilMs && Number.isFinite(untilMs) ? String(untilMs) : "");
+}
+export function clearPause() {
+    try {
+        rmSync(pausePath());
+    }
+    catch {
+        /* not paused */
+    }
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function num(envVal, fallback) {
+    const n = Number(envVal);
+    return envVal !== undefined && Number.isFinite(n) ? n : fallback;
+}
+export function loadConfig() {
+    const fileCfg = readJson(configPath()) ?? {};
+    const filePricing = readJson(pricingPath());
+    const fileBudget = fileCfg.budget ?? {};
+    const budget = {
+        sessionSoftUSD: num(process.env.AGENT_GUARD_SESSION_SOFT, fileBudget.sessionSoftUSD ?? DEFAULT_BUDGET.sessionSoftUSD),
+        sessionHardUSD: num(process.env.AGENT_GUARD_SESSION_HARD, fileBudget.sessionHardUSD ?? DEFAULT_BUDGET.sessionHardUSD),
+        dailySoftUSD: num(process.env.AGENT_GUARD_DAILY_SOFT, fileBudget.dailySoftUSD ?? DEFAULT_BUDGET.dailySoftUSD),
+        dailyHardUSD: num(process.env.AGENT_GUARD_DAILY_HARD, fileBudget.dailyHardUSD ?? DEFAULT_BUDGET.dailyHardUSD),
+    };
+    return {
+        budget,
+        pricingOverrides: { ...(fileCfg.pricingOverrides ?? {}), ...(filePricing ?? {}) },
+        apiKey: process.env.KILL_SWITCH_API_KEY ?? fileCfg.apiKey,
+        apiUrl: process.env.KILL_SWITCH_API_URL ?? fileCfg.apiUrl ?? "https://api.kill-switch.net",
+        slackWebhook: process.env.KILL_SWITCH_SLACK_WEBHOOK ?? fileCfg.slackWebhook,
+    };
+}
+/** Merge built-in pricing with any overrides from config. */
+export function mergedPricing(cfg, base) {
+    if (!cfg.pricingOverrides || Object.keys(cfg.pricingOverrides).length === 0)
+        return base;
+    return { ...base, ...cfg.pricingOverrides };
+}

package/dist/cost.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Turn token usage into dollars.
+ *
+ * Both the hook (parsing the Claude Code transcript) and the proxy (parsing live
+ * API responses) produce a {@link TokenUsage} and feed it through here, so cost
+ * math lives in exactly one place.
+ */
+import { type ModelPricing } from "./pricing.js";
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Anthropic cache-write tokens (a.k.a. cache_creation_input_tokens) */
+    cacheCreationTokens?: number;
+    /** Anthropic cache-read tokens (a.k.a. cache_read_input_tokens) */
+    cacheReadTokens?: number;
+}
+/** Cost in USD for a single usage record on a given model. */
+export declare function costForUsage(model: string, usage: TokenUsage, table?: Record<string, ModelPricing>): number;
+/** Total token count across all four buckets — for display / "tokens burned" metrics. */
+export declare function totalTokens(usage: TokenUsage): number;
+/** Format a USD amount for terminal output. */
+export declare function fmtUSD(n: number): string;

package/dist/cost.js

@@ -0,0 +1,41 @@
+/**
+ * Turn token usage into dollars.
+ *
+ * Both the hook (parsing the Claude Code transcript) and the proxy (parsing live
+ * API responses) produce a {@link TokenUsage} and feed it through here, so cost
+ * math lives in exactly one place.
+ */
+import { pricingFor } from "./pricing.js";
+const PER_MILLION = 1_000_000;
+/** Effective cache rates, applying Anthropic's default multipliers when a model omits them. */
+function cacheRates(p) {
+    return {
+        write: p.cacheWrite ?? p.input * 1.25,
+        read: p.cacheRead ?? p.input * 0.1,
+    };
+}
+/** Cost in USD for a single usage record on a given model. */
+export function costForUsage(model, usage, table) {
+    const p = pricingFor(model, table);
+    const { write, read } = cacheRates(p);
+    const input = usage.inputTokens || 0;
+    const output = usage.outputTokens || 0;
+    const cacheWrite = usage.cacheCreationTokens || 0;
+    const cacheRead = usage.cacheReadTokens || 0;
+    return ((input * p.input +
+        output * p.output +
+        cacheWrite * write +
+        cacheRead * read) /
+        PER_MILLION);
+}
+/** Total token count across all four buckets — for display / "tokens burned" metrics. */
+export function totalTokens(usage) {
+    return ((usage.inputTokens || 0) +
+        (usage.outputTokens || 0) +
+        (usage.cacheCreationTokens || 0) +
+        (usage.cacheReadTokens || 0));
+}
+/** Format a USD amount for terminal output. */
+export function fmtUSD(n) {
+    return `$${n.toFixed(n < 1 ? 4 : 2)}`;
+}

package/dist/hook.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Claude Code hook entrypoint — `agent-guard hook`.
+ *
+ * Wired into .claude/settings.json for PreToolUse, UserPromptSubmit, and Stop.
+ * On every call it:
+ *   1. Reads the hook JSON from stdin (session_id, transcript_path, cwd, event).
+ *   2. Recomputes the session's total spend from the transcript (authoritative).
+ *   3. Derives rolling-24h spend from the ledger and evaluates the budget.
+ *   4. Emits the event-appropriate decision:
+ *        - ok    → exit 0 silently
+ *        - warn  → allow, surface a systemMessage + additionalContext (once/scope)
+ *        - block → deny the tool / block the prompt with a reason
+ *   5. Fires alerts on the first warn and first block per scope.
+ *
+ * Design rule: this runs before every tool call, so it must be fast and must
+ * never crash the agent. Any internal error fails OPEN (exit 0, agent proceeds)
+ * — a buggy guard must not brick the user's session.
+ */
+export declare function runHook(): Promise<void>;

package/dist/hook.js

@@ -0,0 +1,190 @@
+/**
+ * Claude Code hook entrypoint — `agent-guard hook`.
+ *
+ * Wired into .claude/settings.json for PreToolUse, UserPromptSubmit, and Stop.
+ * On every call it:
+ *   1. Reads the hook JSON from stdin (session_id, transcript_path, cwd, event).
+ *   2. Recomputes the session's total spend from the transcript (authoritative).
+ *   3. Derives rolling-24h spend from the ledger and evaluates the budget.
+ *   4. Emits the event-appropriate decision:
+ *        - ok    → exit 0 silently
+ *        - warn  → allow, surface a systemMessage + additionalContext (once/scope)
+ *        - block → deny the tool / block the prompt with a reason
+ *   5. Fires alerts on the first warn and first block per scope.
+ *
+ * Design rule: this runs before every tool call, so it must be fast and must
+ * never crash the agent. Any internal error fails OPEN (exit 0, agent proceeds)
+ * — a buggy guard must not brick the user's session.
+ */
+import { loadConfig, mergedPricing, isPaused } from "./config.js";
+import { fileURLToPath } from "node:url";
+import { MODEL_PRICING } from "./pricing.js";
+import { costForUsage } from "./cost.js";
+import { parseTranscript } from "./transcript.js";
+import { loadLedger, saveLedger, setSessionCost, rollingDailyCost, prune, } from "./ledger.js";
+import { evaluate, warnKey } from "./budget.js";
+import { dispatchAlert } from "./alert.js";
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        if (process.stdin.isTTY)
+            return resolve("");
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => (data += c));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+    });
+}
+function emit(obj) {
+    process.stdout.write(JSON.stringify(obj));
+}
+/** Build the block decision shaped for the specific hook event. */
+function blockDecision(event, reason, systemMessage) {
+    if (event === "PreToolUse") {
+        return {
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: reason,
+            },
+            systemMessage,
+        };
+    }
+    // UserPromptSubmit (and others that honor decision/block)
+    return { decision: "block", reason, systemMessage };
+}
+function warnDecision(event, context, systemMessage) {
+    if (event === "PreToolUse" || event === "UserPromptSubmit") {
+        return {
+            hookSpecificOutput: { hookEventName: event, additionalContext: context },
+            systemMessage,
+        };
+    }
+    return { systemMessage };
+}
+export async function runHook() {
+    let input = {};
+    try {
+        const raw = await readStdin();
+        if (raw.trim())
+            input = JSON.parse(raw);
+    }
+    catch {
+        process.exit(0); // fail open
+    }
+    const event = input.hook_event_name || "PreToolUse";
+    const sessionId = input.session_id || "unknown-session";
+    const now = Date.now();
+    // Escape hatch: if a human has paused enforcement, fail open immediately —
+    // before any budget math — so a paused guard can never block a tool call.
+    if (isPaused(now)) {
+        process.exit(0);
+    }
+    try {
+        const cfg = loadConfig();
+        const pricing = mergedPricing(cfg, MODEL_PRICING);
+        // 1) Recompute authoritative session spend from the transcript.
+        let sessionUSD = 0;
+        let inTok = 0;
+        let outTok = 0;
+        if (input.transcript_path) {
+            const { byModel } = parseTranscript(input.transcript_path);
+            for (const [model, usage] of byModel) {
+                sessionUSD += costForUsage(model, usage, pricing);
+                inTok += usage.inputTokens;
+                outTok += usage.outputTokens;
+            }
+        }
+        // 2) Persist + derive rolling daily.
+        const ledger = loadLedger();
+        const rec = setSessionCost(ledger, sessionId, sessionUSD, inTok, outTok, now);
+        const dailyUSD = rollingDailyCost(ledger, now);
+        // 3) Evaluate.
+        const verdict = evaluate({ sessionUSD, dailyUSD }, cfg.budget);
+        // 4) Alert (deduped per scope) + decide what to output.
+        const action = verdict.level === "block"
+            ? event === "PreToolUse" ? "denied next tool call" : "blocked new prompt"
+            : verdict.level === "warn" ? "warned, agent allowed to continue" : "none";
+        const baseEvt = {
+            ts: now,
+            source: "hook",
+            sessionId,
+            sessionUSD,
+            dailyUSD,
+            reasons: verdict.reasons,
+            action,
+            cwd: input.cwd,
+        };
+        let shouldAlert = false;
+        if (verdict.level === "block") {
+            if (!rec.notified["block"]) {
+                rec.notified["block"] = true;
+                shouldAlert = true;
+            }
+        }
+        else if (verdict.level === "warn") {
+            for (const t of verdict.triggers) {
+                const k = warnKey(t.scope);
+                if (!rec.notified[k]) {
+                    rec.notified[k] = true;
+                    shouldAlert = true;
+                }
+            }
+        }
+        prune(ledger, now);
+        saveLedger(ledger);
+        if (shouldAlert) {
+            await dispatchAlert(cfg, { ...baseEvt, level: verdict.level });
+        }
+        // 5) Output decision.
+        if (verdict.level === "block") {
+            const reason = renderBlockReason(verdict, sessionId);
+            // Stop events can't usefully block spend; allow them through (alert already fired).
+            if (event === "Stop") {
+                process.exit(0);
+            }
+            emit(blockDecision(event, reason, `🛑 Kill Switch stopped this agent — ${verdict.reasons[0] ?? "budget exceeded"}.`));
+            process.exit(0);
+        }
+        // Surface the warn nudge only on the first trip per scope (shouldAlert), not
+        // on every subsequent tool call — otherwise the agent's context fills with
+        // duplicate notices. After that, warnings stay silent until the hard cap.
+        if (verdict.level === "warn" && shouldAlert) {
+            const ctx = renderWarnContext(verdict);
+            emit(warnDecision(event, ctx, `⚠️ Kill Switch: ${verdict.reasons[0] ?? "approaching budget"}.`));
+            process.exit(0);
+        }
+        process.exit(0);
+    }
+    catch {
+        process.exit(0); // fail open on any unexpected error
+    }
+}
+/** Absolute path to this CLI, so recovery commands work without PATH / npm-link. */
+function selfCmd() {
+    try {
+        return `"${process.execPath}" "${fileURLToPath(import.meta.url).replace(/hook\.js$/, "cli.js")}"`;
+    }
+    catch {
+        return "agent-guard";
+    }
+}
+function renderBlockReason(v, sessionId) {
+    const cmd = selfCmd();
+    return [
+        "Kill Switch hard cap reached — further tool use is blocked to prevent a runaway bill.",
+        ...v.reasons,
+        "Do not retry. The escape hatch belongs to the HUMAN, not you — tell the user to run ONE of these in their own shell (the `!` prefix in Claude Code bypasses this hook):",
+        `(1) PAUSE for 30 min:  ${cmd} pause --minutes 30`,
+        `(2) RAISE the caps:    ${cmd} config --session-hard 2000 --daily-hard 4000`,
+        `(3) RESET this session's spend:  ${cmd} reset --session ${sessionId}`,
+        "Or, with zero tooling: `touch ~/.kill-switch/agent-guard/PAUSED` (and `rm` it to re-arm).",
+    ].join(" ");
+}
+function renderWarnContext(v) {
+    return [
+        "Kill Switch budget notice (informational, you may continue):",
+        ...v.reasons,
+        "Consider wrapping up or narrowing scope to avoid hitting the hard cap, which will halt tool use.",
+    ].join(" ");
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @kill-switch/agent-guard — Kill Switch for coding agents.
+ *
+ * Stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM
+ * bill, via a native Claude Code hook and a token-metering proxy that share one
+ * per-session + daily-rolling budget.
+ *
+ * Programmatic surface (the CLI in cli.ts is the primary entrypoint):
+ */
+export { MODEL_PRICING, FALLBACK_PRICING, pricingFor, normalizeModel, type ModelPricing } from "./pricing.js";
+export { costForUsage, totalTokens, fmtUSD, type TokenUsage } from "./cost.js";
+export { evaluate, warnKey, type Budget, type Verdict, type Spend, type VerdictLevel } from "./budget.js";
+export { loadLedger, saveLedger, setSessionCost, addSessionCost, rollingDailyCost, prune, emptyLedger, type Ledger, type SessionRecord, } from "./ledger.js";
+export { parseTranscript, type TranscriptTotals } from "./transcript.js";
+export { loadConfig, DEFAULT_BUDGET, guardDir, ensureGuardDir, configPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, type GuardConfig, } from "./config.js";
+export { dispatchAlert, type AlertEvent } from "./alert.js";
+export { startProxy, resolveUpstream, type ProxyOptions } from "./proxy.js";
+export { runHook } from "./hook.js";
+export { buildStatusReport, type StatusReport } from "./report.js";
+export { installHook, setBudget, resetLedger, type InstallOptions, type InstallResult, type BudgetPatch, } from "./ops.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @kill-switch/agent-guard — Kill Switch for coding agents.
+ *
+ * Stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM
+ * bill, via a native Claude Code hook and a token-metering proxy that share one
+ * per-session + daily-rolling budget.
+ *
+ * Programmatic surface (the CLI in cli.ts is the primary entrypoint):
+ */
+export { MODEL_PRICING, FALLBACK_PRICING, pricingFor, normalizeModel } from "./pricing.js";
+export { costForUsage, totalTokens, fmtUSD } from "./cost.js";
+export { evaluate, warnKey } from "./budget.js";
+export { loadLedger, saveLedger, setSessionCost, addSessionCost, rollingDailyCost, prune, emptyLedger, } from "./ledger.js";
+export { parseTranscript } from "./transcript.js";
+export { loadConfig, DEFAULT_BUDGET, guardDir, ensureGuardDir, configPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, } from "./config.js";
+export { dispatchAlert } from "./alert.js";
+export { startProxy, resolveUpstream } from "./proxy.js";
+export { runHook } from "./hook.js";
+export { buildStatusReport } from "./report.js";
+export { installHook, setBudget, resetLedger, } from "./ops.js";

package/dist/ledger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Spend ledger — the single source of truth for "how much has been spent".
+ *
+ * Stored at ~/.kill-switch/agent-guard/ledger.json. Written atomically
+ * (tmp file + rename) because the hook and the proxy can both touch it.
+ *
+ * Daily-rolling cost is *derived*, not separately accumulated: it's the sum of
+ * every session whose last activity falls within the trailing 24h window. This
+ * makes double-counting impossible — the hook recomputes a session's total from
+ * the transcript (authoritative) while the proxy increments deltas, and neither
+ * can inflate the daily figure.
+ */
+export interface SessionRecord {
+    startedAt: number;
+    lastAt: number;
+    costUSD: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** Dedup flags so soft-cap warnings fire once per scope, not every tool call. */
+    notified: Record<string, boolean>;
+}
+export interface Ledger {
+    version: 1;
+    sessions: Record<string, SessionRecord>;
+}
+export declare function emptyLedger(): Ledger;
+export declare function loadLedger(): Ledger;
+export declare function saveLedger(ledger: Ledger): void;
+/** Authoritative set — used by the hook after recomputing from the transcript. */
+export declare function setSessionCost(ledger: Ledger, id: string, costUSD: number, inputTokens: number, outputTokens: number, now: number): SessionRecord;
+/** Incremental add — used by the proxy, which sees per-response deltas. */
+export declare function addSessionCost(ledger: Ledger, id: string, deltaUSD: number, inputTokens: number, outputTokens: number, now: number): SessionRecord;
+/** Sum of all sessions active within the trailing 24h window. */
+export declare function rollingDailyCost(ledger: Ledger, now: number): number;
+/** Drop sessions untouched for `days` to keep the ledger small. */
+export declare function prune(ledger: Ledger, now: number, days?: number): void;

package/dist/ledger.js

@@ -0,0 +1,79 @@
+/**
+ * Spend ledger — the single source of truth for "how much has been spent".
+ *
+ * Stored at ~/.kill-switch/agent-guard/ledger.json. Written atomically
+ * (tmp file + rename) because the hook and the proxy can both touch it.
+ *
+ * Daily-rolling cost is *derived*, not separately accumulated: it's the sum of
+ * every session whose last activity falls within the trailing 24h window. This
+ * makes double-counting impossible — the hook recomputes a session's total from
+ * the transcript (authoritative) while the proxy increments deltas, and neither
+ * can inflate the daily figure.
+ */
+import { readFileSync, writeFileSync, renameSync } from "node:fs";
+import { ledgerPath, ensureGuardDir } from "./config.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function emptyLedger() {
+    return { version: 1, sessions: {} };
+}
+export function loadLedger() {
+    try {
+        const data = JSON.parse(readFileSync(ledgerPath(), "utf8"));
+        if (data && data.version === 1 && data.sessions)
+            return data;
+    }
+    catch {
+        /* fall through to empty */
+    }
+    return emptyLedger();
+}
+export function saveLedger(ledger) {
+    ensureGuardDir();
+    const path = ledgerPath();
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(ledger, null, 2));
+    renameSync(tmp, path);
+}
+function ensureSession(ledger, id, now) {
+    let s = ledger.sessions[id];
+    if (!s) {
+        s = { startedAt: now, lastAt: now, costUSD: 0, inputTokens: 0, outputTokens: 0, notified: {} };
+        ledger.sessions[id] = s;
+    }
+    return s;
+}
+/** Authoritative set — used by the hook after recomputing from the transcript. */
+export function setSessionCost(ledger, id, costUSD, inputTokens, outputTokens, now) {
+    const s = ensureSession(ledger, id, now);
+    s.costUSD = costUSD;
+    s.inputTokens = inputTokens;
+    s.outputTokens = outputTokens;
+    s.lastAt = now;
+    return s;
+}
+/** Incremental add — used by the proxy, which sees per-response deltas. */
+export function addSessionCost(ledger, id, deltaUSD, inputTokens, outputTokens, now) {
+    const s = ensureSession(ledger, id, now);
+    s.costUSD += deltaUSD;
+    s.inputTokens += inputTokens;
+    s.outputTokens += outputTokens;
+    s.lastAt = now;
+    return s;
+}
+/** Sum of all sessions active within the trailing 24h window. */
+export function rollingDailyCost(ledger, now) {
+    let total = 0;
+    for (const s of Object.values(ledger.sessions)) {
+        if (now - s.lastAt < DAY_MS)
+            total += s.costUSD;
+    }
+    return total;
+}
+/** Drop sessions untouched for `days` to keep the ledger small. */
+export function prune(ledger, now, days = 14) {
+    const cutoff = now - days * DAY_MS;
+    for (const [id, s] of Object.entries(ledger.sessions)) {
+        if (s.lastAt < cutoff)
+            delete ledger.sessions[id];
+    }
+}

package/dist/ops.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Operations shared by the standalone `agent-guard` CLI and the `ks guard`
+ * subcommands, so both drive the same logic instead of duplicating it (or
+ * shelling out). Pure side-effecting helpers over config + Claude Code settings.
+ */
+import type { Budget } from "./budget.js";
+export interface InstallOptions {
+    /** Install into ~/.claude/settings.json instead of ./.claude/settings.json */
+    global?: boolean;
+    /** Override the hook command (default: absolute path to this binary). */
+    command?: string;
+    /** Working dir for the project-local install (default: process.cwd()). */
+    cwd?: string;
+}
+export interface InstallResult {
+    settingsPath: string;
+    command: string;
+    added: string[];
+}
+/**
+ * Wire the agent-guard hook into Claude Code settings for PreToolUse,
+ * UserPromptSubmit, and Stop. Idempotent: re-running adds nothing if the hook
+ * command is already present.
+ */
+export declare function installHook(cliPath: string, execPath: string, opts?: InstallOptions): InstallResult;
+/** Partial budget update (USD). Merges onto the existing config file. */
+export interface BudgetPatch {
+    sessionSoftUSD?: number;
+    sessionHardUSD?: number;
+    dailySoftUSD?: number;
+    dailyHardUSD?: number;
+    slackWebhook?: string;
+}
+/** Write budget/webhook overrides to the config file. Returns the saved budget. */
+export declare function setBudget(patch: BudgetPatch): Budget;
+/** Clear the spend ledger. Scope: all | a single session | today's sessions. */
+export declare function resetLedger(opts: {
+    all?: boolean;
+    session?: string;
+    today?: boolean;
+}): string;