@oked/claude-agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OKed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# @oked/claude-agent-sdk
+
+OKed for the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk).
+A ready-made `PreToolUse` hook callback — sensitive tool calls freeze the
+agent and wait for a human approval (push to your phone) before running.
+
+> Building with the **Claude Code CLI** instead? Use
+> [`@oked/claude-code`](../claude-code) (`oked init`, zero code).
+
+## Why this exists
+
+The Claude Agent SDK does **not** read `.claude/settings.json` hooks by
+default — hooks are passed programmatically via `options.hooks`. So unlike
+the Claude Code CLI there's no zero-code install: you wire OKed's hook into
+your agent's options yourself. (If you *do* load project settings via
+`settingSources: ["project"]`, the `@oked/claude-code` hook would also fire —
+this package is for the common programmatic case.)
+
+## Install
+
+```sh
+npm install @oked/claude-agent-sdk
+```
+
+`@anthropic-ai/claude-agent-sdk` is an optional peer dependency — you already
+have it if you're building an agent.
+
+## Use
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { okedHooks } from "@oked/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "…",
+  options: { hooks: okedHooks() },
+})) {
+  // …
+}
+```
+
+Or wire the callback yourself for full control over matchers/timeout:
+
+```ts
+import { okedPreToolUseHook } from "@oked/claude-agent-sdk";
+
+const options = {
+  hooks: {
+    PreToolUse: [{ hooks: [okedPreToolUseHook] }],
+  },
+};
+```
+
+## Auth
+
+Bring your own API key (this package has no pairing CLI):
+
+- `OKED_API_KEY=ok_…` environment variable, or
+- `~/.oked/config.json` (`{ "apiKey": "ok_…" }`)
+
+Create a key from the OKed dashboard. Optionally set `OKED_BACKEND_URL` to
+target a non-default backend.
+
+## Behavior
+
+Same tier model and fail-safe semantics as the other OKed integrations:
+
+| Tier | What happens |
+|------|--------------|
+| `safe` | Allow immediately, no network call |
+| `warning` | Allow, log to stderr only, no network call |
+| `review` / `high_stakes` | Request approval; **Approve** → run, otherwise the tool call is denied with a reason |
+
+Failure handling: missing API key → defer to the agent's built-in
+permission flow (`ask`); invalid key → deny; backend unreachable → degrade
+per tier (`degradedDecision` — high-stakes / strict fail-closed deny, others
+may proceed); any unexpected error → deny. Set `OKED_STRICT_FAIL_CLOSED=1`
+to deny every sensitive action during backend outages.
+
+## Attribution
+
+Approvals are attributed by the **API key's pairing record** — not a
+per-request field. Pair a device with `client_type: "claude-agent-sdk"`
+and that clientType plus the host/device name are bonded to the issued API
+key (`device_codes` ↔ `api_keys`). Every approval made with that key is
+then attributable to `claude-agent-sdk` in the dashboard, via the same
+mechanism used for the other integrations.
+
+This package ships no pairing CLI (callback-only, BYO key), so obtain a
+`claude-agent-sdk`-typed key through your pairing flow. A key minted from
+the dashboard "create key" UI has no device record and falls back to the
+generic `sdk` bucket.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * A `PreToolUse` hook callback for the Claude Agent SDK. Pass it via
+ * `options.hooks` (or use {@link okedHooks}).
+ */
+export declare const okedPreToolUseHook: HookCallback;
+/**
+ * Convenience: spread into the Claude Agent SDK `options.hooks`.
+ *
+ * ```ts
+ * import { query } from "@anthropic-ai/claude-agent-sdk";
+ * import { okedHooks } from "@oked/claude-agent-sdk";
+ *
+ * for await (const m of query({ prompt, options: { hooks: okedHooks() } })) { }
+ * ```
+ */
+export declare function okedHooks(): {
+    PreToolUse: {
+        hooks: HookCallback[];
+    }[];
+};

package/dist/index.js

@@ -0,0 +1,125 @@
+/**
+ * @oked/claude-agent-sdk — OKed for the Claude Agent SDK.
+ *
+ * Exports a ready-made `PreToolUse` hook callback. Wire it into your agent's
+ * `options.hooks` and every tool call the model makes is classified; calls
+ * classified as sensitive (review / high_stakes) freeze the agent and wait
+ * for a human approval via the OKed backend (push to your phone). The tool
+ * only runs on Approve.
+ *
+ * Unlike `@oked/claude-code` there is no `.claude/settings.json` install —
+ * the Claude Agent SDK takes hooks programmatically. Bring your own API key
+ * via `OKED_API_KEY` (or `~/.oked/config.json`); see README.
+ *
+ * Failure semantics mirror the other OKed integrations: fail safe. Auth
+ * errors deny; backend-unreachable degrades per tier (`degradedDecision`);
+ * any unexpected error denies. Never let an agent proceed when in doubt.
+ */
+import { OKedClient, classify, describe, describeFields, degradedDecision, OKedAuthError, OKedBackendUnreachableError, } from "@oked/sdk";
+function log(msg) {
+    process.stderr.write(`[OKed] ${msg}\n`);
+}
+const ALLOW = {};
+function deny(reason) {
+    return {
+        systemMessage: reason,
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+        },
+    };
+}
+function ask() {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "ask",
+        },
+    };
+}
+/**
+ * A `PreToolUse` hook callback for the Claude Agent SDK. Pass it via
+ * `options.hooks` (or use {@link okedHooks}).
+ */
+export const okedPreToolUseHook = async (rawInput) => {
+    const input = rawInput;
+    const toolName = input.tool_name;
+    const toolInput = (input.tool_input ?? {});
+    const tier = classify(toolName, toolInput);
+    const client = new OKedClient();
+    // Presence ping (throttled to once/day on disk, never throws). Fired before
+    // the safe/warning return so installs that only run safe actions still
+    // register for retention. Fire-and-forget: this is a long-lived process, so
+    // we never add latency to the tool call.
+    if (client.apiKey)
+        void client.heartbeat().catch(() => { });
+    // Safe — allow immediately, no network call.
+    if (tier === "safe")
+        return ALLOW;
+    // Warning — allow, log only, no network call (mirrors the Claude Code hook).
+    if (tier === "warning") {
+        const summary = (toolInput.file_path ?? toolInput.command ?? toolName);
+        log(`WARNING ${toolName} ${summary} - allowed (inside project)`);
+        return ALLOW;
+    }
+    if (!client.apiKey) {
+        log("OKED_API_KEY not set - deferring to the agent's built-in permission flow.");
+        return ask();
+    }
+    const description = describe(toolName, toolInput);
+    const fields = describeFields(toolName, toolInput) ?? undefined;
+    log(`${toolName}: "${description}" - ${tier}`);
+    log("Requesting approval... (check your phone)");
+    try {
+        const result = await client.approve({
+            action: toolName,
+            description,
+            tier,
+            fields,
+            tool_input: toolInput,
+            session_id: input.session_id,
+            cwd: input.cwd,
+        });
+        if (result.approved) {
+            log(`Approved (${result.approval_id})`);
+            return ALLOW;
+        }
+        log(`Denied (${result.approval_id})`);
+        return deny(`Denied via OKed: ${description}`);
+    }
+    catch (err) {
+        if (err instanceof OKedAuthError) {
+            // Auth misconfig is not an outage — always deny.
+            log("Invalid API key - action denied");
+            return deny("OKed: invalid API key");
+        }
+        if (err instanceof OKedBackendUnreachableError) {
+            const decision = degradedDecision(tier, {
+                strictFailClosed: client.strictFailClosed,
+            });
+            if (decision === "allow") {
+                log(`Backend unreachable - allowed (degraded; ${tier}, non-high-stakes)`);
+                return ALLOW;
+            }
+            const why = client.strictFailClosed ? "strict fail-closed" : "high-stakes";
+            log(`Backend unreachable - ${why} denied (fail-safe)`);
+            return deny(`OKed backend unreachable - ${why} denied (fail-safe)`);
+        }
+        log("Unexpected error - action denied (fail-safe)");
+        return deny("OKed: unexpected error (fail-safe)");
+    }
+};
+/**
+ * Convenience: spread into the Claude Agent SDK `options.hooks`.
+ *
+ * ```ts
+ * import { query } from "@anthropic-ai/claude-agent-sdk";
+ * import { okedHooks } from "@oked/claude-agent-sdk";
+ *
+ * for await (const m of query({ prompt, options: { hooks: okedHooks() } })) { }
+ * ```
+ */
+export function okedHooks() {
+    return { PreToolUse: [{ hooks: [okedPreToolUseHook] }] };
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@oked/claude-agent-sdk",
+  "version": "0.1.0",
+  "description": "OKed for the Claude Agent SDK. A ready-made PreToolUse hook that gates sensitive tool calls behind a human approval push to your phone.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "npm run build --workspace=@oked/sdk",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && node src/smoke.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@oked/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+    "@types/node": "^22.13.10",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "claude-agent-sdk",
+    "claude",
+    "anthropic",
+    "approval",
+    "hook",
+    "agents",
+    "ai",
+    "human-in-the-loop",
+    "oked"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oked-ai/oked-sdk.git",
+    "directory": "packages/claude-agent-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/oked-ai/oked-sdk/issues"
+  },
+  "homepage": "https://github.com/oked-ai/oked-sdk/tree/main/packages/claude-agent-sdk#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}