@oked/sdk 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed errors thrown by OKedClient.approve() so callers can tell *why* a
+ * request failed and apply the right policy:
+ *
+ *  - OKedAuthError            -> bad/missing API key. Always deny. Never an
+ *                                outage, so degraded-mode does NOT apply.
+ *  - OKedBackendUnreachableError -> connect failure, timeout, or 5xx. This is
+ *                                the outage case degradedDecision() handles.
+ *
+ * An explicit user *deny* is NOT an error: approve() returns normally with
+ * { approved: false, decision: "denied" } and must always be honored.
+ */
+export declare class OKedAuthError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare class OKedBackendUnreachableError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+/**
+ * Typed errors thrown by OKedClient.approve() so callers can tell *why* a
+ * request failed and apply the right policy:
+ *
+ *  - OKedAuthError            -> bad/missing API key. Always deny. Never an
+ *                                outage, so degraded-mode does NOT apply.
+ *  - OKedBackendUnreachableError -> connect failure, timeout, or 5xx. This is
+ *                                the outage case degradedDecision() handles.
+ *
+ * An explicit user *deny* is NOT an error: approve() returns normally with
+ * { approved: false, decision: "denied" } and must always be honored.
+ */
+export class OKedAuthError extends Error {
+    status;
+    constructor(message, status = 401) {
+        super(message);
+        this.name = "OKedAuthError";
+        this.status = status;
+    }
+}
+export class OKedBackendUnreachableError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "OKedBackendUnreachableError";
+        this.cause = cause;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import type { ApprovalRequest, ApprovalResponse, OKedConfig } from "./types.js";
+import type { Rule } from "./rules.js";
+export declare class OKedClient {
+    private config;
+    constructor(config?: Partial<OKedConfig>);
+    get strictFailClosed(): boolean;
+    get apiKey(): string;
+    get backendUrl(): string;
+    approve(request: ApprovalRequest): Promise<ApprovalResponse>;
+    /**
+     * User rules for local escalation checks, cached on disk (TTL
+     * `rulesCacheTtlMs`, default 5 min). The Claude Code hook is a fresh
+     * process per call, so caching must be on disk. Never throws: a failed
+     * fetch falls back to the last cached value (even if stale), else `[]`.
+     */
+    getRules(): Promise<Rule[]>;
+    ping(): Promise<boolean>;
+    /**
+     * Presence ping so the backend knows this install is still alive — feeds
+     * retention analytics, including users who only ever run safe/warning
+     * actions (which otherwise never reach the backend). Throttled on disk to
+     * `heartbeatIntervalMs` (default once/day), keyed per backend+key. Never
+     * throws: a missing key, a throttled call, or a failed request are all
+     * silent no-ops, so it is safe to await on the hook's hot path. The stamp is
+     * only advanced on a successful send, so a transient outage just re-pings
+     * next call.
+     */
+    heartbeat(): Promise<void>;
+}
+export { OKedAuthError, OKedBackendUnreachableError } from "./errors.js";
+export { TIER_ORDER, degradedDecision } from "./degraded.js";
+export { classify } from "./classify.js";
+export { describe, describeFields } from "./describe.js";
+export { applyRules } from "./rules.js";
+export type { Rule, RuleMatch, RuleAction, RuleDecision, FieldOp, } from "./rules.js";
+export type { Rendered } from "./describe.js";
+export { CLASSIFIER_VERSION } from "./kinds.js";
+export type { OperationKind } from "./kinds.js";
+export { loadOKedConfig, OKED_CONFIG_PATH } from "./config.js";
+export type { PersistedConfig } from "./config.js";
+export type { RiskTier, ApprovalRequest, ApprovalResponse, OKedConfig, HookInput, HookOutput, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,268 @@
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { loadOKedConfig, OKED_RULES_CACHE_PATH, OKED_HEARTBEAT_PATH } from "./config.js";
+import { OKedAuthError, OKedBackendUnreachableError } from "./errors.js";
+import { hostname } from "os";
+function envStrictFailClosed() {
+    const raw = process.env.OKED_STRICT_FAIL_CLOSED;
+    if (raw === undefined)
+        return undefined;
+    return raw === "1" || raw.toLowerCase() === "true";
+}
+function envRulesCacheTtlMs() {
+    const raw = process.env.OKED_RULES_CACHE_TTL; // seconds
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n * 1000 : undefined;
+}
+function envHeartbeatIntervalMs() {
+    const raw = process.env.OKED_HEARTBEAT_INTERVAL; // seconds
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n * 1000 : undefined;
+}
+// Small stable key so different keys/backends don't collide in the shared
+// cache file, without storing the API key itself.
+function rulesCacheKey(backendUrl, apiKey) {
+    const s = `${backendUrl}|${apiKey}`;
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+    return h.toString(36);
+}
+function readRulesCache() {
+    try {
+        const parsed = JSON.parse(readFileSync(OKED_RULES_CACHE_PATH, "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeRulesCache(cache) {
+    try {
+        mkdirSync(dirname(OKED_RULES_CACHE_PATH), { recursive: true });
+        writeFileSync(OKED_RULES_CACHE_PATH, JSON.stringify(cache));
+    }
+    catch {
+        // Best-effort; a non-writable home dir just means no cross-call caching.
+    }
+}
+function readHeartbeatStamps() {
+    try {
+        const parsed = JSON.parse(readFileSync(OKED_HEARTBEAT_PATH, "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeHeartbeatStamps(stamps) {
+    try {
+        mkdirSync(dirname(OKED_HEARTBEAT_PATH), { recursive: true });
+        writeFileSync(OKED_HEARTBEAT_PATH, JSON.stringify(stamps));
+    }
+    catch {
+        // Best-effort; a non-writable home dir just means we re-ping next call.
+    }
+}
+export class OKedClient {
+    config;
+    constructor(config) {
+        const persisted = loadOKedConfig();
+        this.config = {
+            apiKey: config?.apiKey || process.env.OKED_API_KEY || persisted.apiKey || "",
+            backendUrl: config?.backendUrl ||
+                process.env.OKED_BACKEND_URL ||
+                persisted.backendUrl ||
+                "https://api.oked.ai",
+            timeout: config?.timeout || 300_000,
+            // Precedence: constructor > env > ~/.oked/config.json > default false.
+            strictFailClosed: config?.strictFailClosed ??
+                envStrictFailClosed() ??
+                persisted.strictFailClosed ??
+                false,
+            rulesCacheTtlMs: config?.rulesCacheTtlMs ??
+                envRulesCacheTtlMs() ??
+                (typeof persisted.rulesCacheTtlSeconds === "number"
+                    ? persisted.rulesCacheTtlSeconds * 1000
+                    : undefined) ??
+                300_000,
+            heartbeatIntervalMs: config?.heartbeatIntervalMs ??
+                envHeartbeatIntervalMs() ??
+                (typeof persisted.heartbeatIntervalSeconds === "number"
+                    ? persisted.heartbeatIntervalSeconds * 1000
+                    : undefined) ??
+                86_400_000,
+        };
+    }
+    get strictFailClosed() {
+        return this.config.strictFailClosed;
+    }
+    get apiKey() {
+        return this.config.apiKey;
+    }
+    get backendUrl() {
+        return this.config.backendUrl;
+    }
+    async approve(request) {
+        const signal = AbortSignal.timeout(this.config.timeout);
+        const doFetch = () => fetch(`${this.config.backendUrl}/api/v1/approve`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.config.apiKey}`,
+            },
+            body: JSON.stringify({
+                action: request.action,
+                description: request.description,
+                tier: request.tier,
+                fields: request.fields,
+                metadata: {
+                    tool_input: request.tool_input,
+                    session_id: request.session_id,
+                    cwd: request.cwd,
+                },
+            }),
+            signal,
+        });
+        let res;
+        try {
+            try {
+                res = await doFetch();
+            }
+            catch (err) {
+                if (isRetriableConnectError(err)) {
+                    await new Promise((r) => setTimeout(r, 200));
+                    res = await doFetch();
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        catch (err) {
+            // Network failure or the request-level timeout firing (AbortError).
+            // Both mean we never got a decision from the backend -> treat as an
+            // outage so degraded-mode can apply.
+            throw new OKedBackendUnreachableError(err instanceof Error ? `OKed backend unreachable: ${err.message}` : "OKed backend unreachable", err);
+        }
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            if (res.status === 401 || res.status === 403) {
+                throw new OKedAuthError(`OKed backend error ${res.status}: ${body}`, res.status);
+            }
+            if (res.status >= 500) {
+                throw new OKedBackendUnreachableError(`OKed backend error ${res.status}: ${body}`);
+            }
+            throw new Error(`OKed backend error ${res.status}: ${body}`);
+        }
+        const result = (await res.json());
+        return {
+            approved: result.decision === "approved",
+            approval_id: result.approval_id,
+            decision: result.decision,
+        };
+    }
+    /**
+     * User rules for local escalation checks, cached on disk (TTL
+     * `rulesCacheTtlMs`, default 5 min). The Claude Code hook is a fresh
+     * process per call, so caching must be on disk. Never throws: a failed
+     * fetch falls back to the last cached value (even if stale), else `[]`.
+     */
+    async getRules() {
+        if (!this.config.apiKey)
+            return [];
+        const key = rulesCacheKey(this.config.backendUrl, this.config.apiKey);
+        const cache = readRulesCache();
+        const entry = cache[key];
+        if (entry && Date.now() - entry.at < this.config.rulesCacheTtlMs) {
+            return entry.rules;
+        }
+        try {
+            const res = await fetch(`${this.config.backendUrl}/api/v1/rules`, {
+                headers: { Authorization: `Bearer ${this.config.apiKey}` },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!res.ok)
+                return entry?.rules ?? [];
+            const rules = (await res.json());
+            if (!Array.isArray(rules))
+                return entry?.rules ?? [];
+            writeRulesCache({ ...cache, [key]: { at: Date.now(), rules } });
+            return rules;
+        }
+        catch {
+            return entry?.rules ?? [];
+        }
+    }
+    async ping() {
+        try {
+            const res = await fetch(`${this.config.backendUrl}/health`, {
+                signal: AbortSignal.timeout(3000),
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Presence ping so the backend knows this install is still alive — feeds
+     * retention analytics, including users who only ever run safe/warning
+     * actions (which otherwise never reach the backend). Throttled on disk to
+     * `heartbeatIntervalMs` (default once/day), keyed per backend+key. Never
+     * throws: a missing key, a throttled call, or a failed request are all
+     * silent no-ops, so it is safe to await on the hook's hot path. The stamp is
+     * only advanced on a successful send, so a transient outage just re-pings
+     * next call.
+     */
+    async heartbeat() {
+        if (!this.config.apiKey)
+            return;
+        const key = rulesCacheKey(this.config.backendUrl, this.config.apiKey);
+        const stamps = readHeartbeatStamps();
+        const last = stamps[key];
+        if (typeof last === "number" && Date.now() - last < this.config.heartbeatIntervalMs) {
+            return;
+        }
+        try {
+            const res = await fetch(`${this.config.backendUrl}/api/v1/heartbeat`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({ hostname: hostname() }),
+                signal: AbortSignal.timeout(3000),
+            });
+            if (res.ok) {
+                writeHeartbeatStamps({ ...stamps, [key]: Date.now() });
+            }
+        }
+        catch {
+            // Best-effort presence signal; never block or break the agent.
+        }
+    }
+}
+function isRetriableConnectError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === "AbortError")
+        return false;
+    const code = err.cause?.code;
+    return (code === "ECONNREFUSED" ||
+        code === "ENOTFOUND" ||
+        code === "EAI_AGAIN" ||
+        code === "ETIMEDOUT" ||
+        code === "UND_ERR_CONNECT_TIMEOUT");
+}
+export { OKedAuthError, OKedBackendUnreachableError } from "./errors.js";
+export { TIER_ORDER, degradedDecision } from "./degraded.js";
+export { classify } from "./classify.js";
+export { describe, describeFields } from "./describe.js";
+export { applyRules } from "./rules.js";
+export { CLASSIFIER_VERSION } from "./kinds.js";
+export { loadOKedConfig, OKED_CONFIG_PATH } from "./config.js";

package/dist/kinds.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stable taxonomy of operations the SDK recognizes. Used as the
+ * `operation_kind` analytics column on approval_classifications.
+ *
+ * Bump CLASSIFIER_VERSION when you add/remove kinds or change how a
+ * pattern maps to a kind, so historical rows stay attributable to the
+ * classifier that produced them.
+ */
+export declare const CLASSIFIER_VERSION = "v2";
+export type OperationKind = "file_create" | "file_append" | "file_edit" | "file_touch" | "file_copy" | "file_move" | "file_delete" | "sql_drop" | "sql_truncate" | "sql_alter" | "sql_create" | "sql_delete_rows" | "sql_delete_all_rows" | "sql_update_rows" | "sql_update_every_row" | "sql_insert" | "sql_query" | "git_push" | "git_force_push" | "git_reset_hard" | "git_clean" | "git_checkout" | "git_restore" | "git_commit" | "git_pr_create" | "ssh_remote" | "http_get" | "http_post" | "http_put" | "http_delete" | "http_pipe_to_shell" | "docker_up" | "docker_down" | "docker_rm" | "docker_rmi" | "docker_prune" | "npm_install" | "npm_run" | "npm_test" | "npm_publish" | "npm_unpublish" | "npx_deploy" | "kill_process" | "sudo" | "chmod_777" | "email_send" | "email_delete" | "email_purge" | "payment_charge" | "payment_create" | "chat_message" | "mcp_delete" | "mcp_update" | "mcp_create" | "mcp_post" | "mcp_publish" | "mcp_send" | "mcp_submit_form" | "mcp_fill" | "mcp_submit" | "mcp_query" | "agent_launch" | "shell_pipeline" | "unknown_bash" | "unknown_tool";

package/dist/kinds.js

@@ -0,0 +1,9 @@
+/**
+ * Stable taxonomy of operations the SDK recognizes. Used as the
+ * `operation_kind` analytics column on approval_classifications.
+ *
+ * Bump CLASSIFIER_VERSION when you add/remove kinds or change how a
+ * pattern maps to a kind, so historical rows stay attributable to the
+ * classifier that produced them.
+ */
+export const CLASSIFIER_VERSION = "v2";

package/dist/rules.d.ts

@@ -0,0 +1,97 @@
+/**
+ * User-defined classification rules. Pure evaluation — no I/O.
+ *
+ * Rules are an ordered list per user; the SDK evaluates top-to-bottom and
+ * stops at the first match. This matches Gmail's "filter messages like
+ * this" model: the order IS the policy. No baked-in "most restrictive
+ * wins" — if the user wants deny to beat approve, they put deny first.
+ *
+ * Matchers reference the fields produced by `describeFields()` (Title,
+ * Target, Body, Kind), plus `cwd` from the hook input. This keeps the
+ * matcher vocabulary aligned with what the user sees in the approval
+ * card; they don't need to know that bash uses `command` while Write
+ * uses `file_path`.
+ *
+ * This module is intentionally I/O-free. Fetching/caching rules from the
+ * backend lives in `OKedClient`; wiring `applyRules()` into the hook
+ * lives in `@oked/claude-code`. Keeping evaluation pure makes the unit
+ * tests trivial and the hot path deterministic.
+ */
+import type { RiskTier } from "./types.js";
+/**
+ * Operator + value for a single matched field. `is_empty` is the only
+ * op that doesn't take a value (it matches when the field is missing or
+ * the empty string).
+ */
+export type FieldOp = {
+    op: "equals";
+    value: string;
+} | {
+    op: "contains";
+    value: string;
+} | {
+    op: "starts_with";
+    value: string;
+} | {
+    op: "matches";
+    value: string;
+} | {
+    op: "is_empty";
+};
+/**
+ * Match clause. All present field-ops must pass (AND). Absent fields
+ * are ignored — a rule with only `{ kind: { op: "equals", value: "X" } }`
+ * matches any action whose Kind is X, regardless of Title/Target/etc.
+ */
+export interface RuleMatch {
+    kind?: FieldOp;
+    title?: FieldOp;
+    target?: FieldOp;
+    body?: FieldOp;
+    cwd?: FieldOp;
+}
+/**
+ * Action the rule takes when its match clause is satisfied.
+ *
+ * - `auto_approve` / `auto_deny`: skip the network round-trip entirely.
+ *   The hook synthesizes the decision locally and logs `appliedRuleId`.
+ * - `set_tier`: still go to the backend for human approval, but with the
+ *   user-specified tier. Used both to escalate (e.g. production matches
+ *   → high_stakes) and to reduce (e.g. trusted npm scripts → warning).
+ */
+export type RuleAction = "auto_approve" | "auto_deny" | "set_tier";
+export interface Rule {
+    id: string;
+    match: RuleMatch;
+    action: RuleAction;
+    /** Required when `action === "set_tier"`; ignored otherwise. */
+    tier?: RiskTier;
+}
+/**
+ * Verdict from `applyRules()`. `outcome === "ask"` means proceed to the
+ * normal backend approval flow (with `tier` possibly overridden by a
+ * `set_tier` rule). `auto_approve` / `auto_deny` mean the hook can
+ * decide locally without a network call.
+ */
+export interface RuleDecision {
+    outcome: "ask" | "auto_approve" | "auto_deny";
+    /** Final tier after any `set_tier` override. */
+    tier: RiskTier;
+    /** Set when a rule fired. */
+    appliedRuleId?: string;
+    /** Set when `set_tier` changed the tier from the classifier default. */
+    tierOverriddenFrom?: RiskTier;
+}
+/**
+ * Evaluate user rules against a classified action. Rules are assumed to
+ * be sorted by user-defined position (top = highest priority). The first
+ * rule whose match clause is satisfied produces the verdict; evaluation
+ * stops there. If no rule matches, returns the classifier default with
+ * `outcome: "ask"`.
+ */
+export declare function applyRules(classified: {
+    tier: RiskTier;
+    fields: Record<string, string>;
+}, rules: Rule[], ctx: {
+    cwd: string;
+}): RuleDecision;

package/dist/rules.js

@@ -0,0 +1,105 @@
+/**
+ * User-defined classification rules. Pure evaluation — no I/O.
+ *
+ * Rules are an ordered list per user; the SDK evaluates top-to-bottom and
+ * stops at the first match. This matches Gmail's "filter messages like
+ * this" model: the order IS the policy. No baked-in "most restrictive
+ * wins" — if the user wants deny to beat approve, they put deny first.
+ *
+ * Matchers reference the fields produced by `describeFields()` (Title,
+ * Target, Body, Kind), plus `cwd` from the hook input. This keeps the
+ * matcher vocabulary aligned with what the user sees in the approval
+ * card; they don't need to know that bash uses `command` while Write
+ * uses `file_path`.
+ *
+ * This module is intentionally I/O-free. Fetching/caching rules from the
+ * backend lives in `OKedClient`; wiring `applyRules()` into the hook
+ * lives in `@oked/claude-code`. Keeping evaluation pure makes the unit
+ * tests trivial and the hot path deterministic.
+ */
+/** Internal: map rule-match field name → `describeFields` output key. */
+const FIELD_KEY = {
+    kind: "Kind",
+    title: "Title",
+    target: "Target",
+    body: "Body",
+};
+function evalFieldOp(op, value) {
+    switch (op.op) {
+        case "is_empty":
+            return !value;
+        case "equals":
+            return value === op.value;
+        case "contains":
+            return value !== undefined && value.includes(op.value);
+        case "starts_with":
+            return value !== undefined && value.startsWith(op.value);
+        case "matches":
+            if (value === undefined)
+                return false;
+            try {
+                return new RegExp(op.value).test(value);
+            }
+            catch {
+                // Invalid user-supplied regex never throws into the hot path —
+                // it just fails to match. The dashboard validates regexes at
+                // create time; this is a belt-and-braces defense.
+                return false;
+            }
+    }
+}
+function ruleMatches(rule, fields, cwd) {
+    const m = rule.match;
+    if (m.kind && !evalFieldOp(m.kind, fields[FIELD_KEY.kind]))
+        return false;
+    if (m.title && !evalFieldOp(m.title, fields[FIELD_KEY.title]))
+        return false;
+    if (m.target && !evalFieldOp(m.target, fields[FIELD_KEY.target]))
+        return false;
+    if (m.body && !evalFieldOp(m.body, fields[FIELD_KEY.body]))
+        return false;
+    if (m.cwd && !evalFieldOp(m.cwd, cwd))
+        return false;
+    return true;
+}
+/**
+ * Evaluate user rules against a classified action. Rules are assumed to
+ * be sorted by user-defined position (top = highest priority). The first
+ * rule whose match clause is satisfied produces the verdict; evaluation
+ * stops there. If no rule matches, returns the classifier default with
+ * `outcome: "ask"`.
+ */
+export function applyRules(classified, rules, ctx) {
+    for (const rule of rules) {
+        if (!ruleMatches(rule, classified.fields, ctx.cwd))
+            continue;
+        switch (rule.action) {
+            case "auto_approve":
+                return {
+                    outcome: "auto_approve",
+                    tier: classified.tier,
+                    appliedRuleId: rule.id,
+                };
+            case "auto_deny":
+                return {
+                    outcome: "auto_deny",
+                    tier: classified.tier,
+                    appliedRuleId: rule.id,
+                };
+            case "set_tier": {
+                // A set_tier rule with no `tier` is malformed; ignore it and
+                // keep evaluating. The dashboard prevents creating such rules;
+                // this guards against bad backend payloads.
+                if (!rule.tier)
+                    continue;
+                return {
+                    outcome: "ask",
+                    tier: rule.tier,
+                    appliedRuleId: rule.id,
+                    tierOverriddenFrom: rule.tier !== classified.tier ? classified.tier : undefined,
+                };
+            }
+        }
+    }
+    return { outcome: "ask", tier: classified.tier };
+}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+export type RiskTier = "safe" | "warning" | "review" | "high_stakes";
+export interface ApprovalRequest {
+    action: string;
+    description: string;
+    tier: RiskTier;
+    fields?: Record<string, string>;
+    tool_input?: unknown;
+    session_id?: string;
+    cwd?: string;
+}
+export interface ApprovalResponse {
+    approved: boolean;
+    approval_id: string;
+    decision: "approved" | "denied" | "timeout";
+}
+export interface OKedConfig {
+    apiKey: string;
+    backendUrl: string;
+    timeout: number;
+    /**
+     * When true, an unreachable backend hard-denies every sensitive action
+     * (the original fail-safe behavior). When false (default), an unreachable
+     * backend degrades to "allow" for non-high-stakes tiers so a single outage
+     * does not mass-abort every user's agent. `high_stakes` always denies on
+     * outage regardless of this flag. See degradedDecision().
+     */
+    strictFailClosed: boolean;
+    /**
+     * TTL (ms) for the on-disk cache of user rules used by the hook's local
+     * escalation check. The Claude Code hook is a fresh process per tool call,
+     * so the cache lives on disk; a longer TTL means fewer fetches at the cost
+     * of slower rule propagation. Default 300_000 (5 min).
+     */
+    rulesCacheTtlMs: number;
+    /**
+     * Min interval (ms) between heartbeats. The hook fires a lightweight ping so
+     * the backend knows the install is still alive (feeds retention analytics)
+     * even for users who only run safe/warning actions. Throttled on disk
+     * (~/.oked/heartbeat.json) because the hook is a fresh process per call.
+     * Default 86_400_000 (once per day).
+     */
+    heartbeatIntervalMs: number;
+}
+export interface HookInput {
+    session_id: string;
+    transcript_path?: string;
+    cwd: string;
+    permission_mode?: string;
+    hook_event_name: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+}
+export interface HookOutput {
+    hookSpecificOutput: {
+        hookEventName: "PreToolUse";
+        permissionDecision: "allow" | "deny" | "ask";
+        permissionDecisionReason?: string;
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};