@oked/claude-agent-sdk 0.6.20 → 0.6.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +28 -49
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,20 +1,15 @@
1
1
  # @oked/claude-agent-sdk
2
2
 
3
- OKed for the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk).
4
- A ready-made `PreToolUse` hook callback — sensitive tool calls freeze the
5
- agent and wait for a human approval (push to your phone) before running.
3
+ [![npm version](https://img.shields.io/npm/v/@oked/claude-agent-sdk.svg)](https://www.npmjs.com/package/@oked/claude-agent-sdk)
4
+ [![License: Apache-2.0](https://img.shields.io/npm/l/@oked/claude-agent-sdk.svg)](./LICENSE)
6
5
 
7
- > Building with the **Claude Code CLI** instead? Use
8
- > [`@oked/claude-code`](../claude-code) (`oked init`, zero code).
6
+ OKed for the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk). A `PreToolUse` hook: sensitive tool calls wait for a person, in Telegram or on the [web dashboard](https://oked.ai/dashboard), before they run. The iPhone app is coming soon.
9
7
 
10
- ## Why this exists
8
+ Building with the Claude Code CLI instead? Use [`@oked/claude-code`](../claude-code) (`oked init`, no code).
11
9
 
12
- The Claude Agent SDK does **not** read `.claude/settings.json` hooks by
13
- default — hooks are passed programmatically via `options.hooks`. So unlike
14
- the Claude Code CLI there's no zero-code install: you wire OKed's hook into
15
- your agent's options yourself. (If you *do* load project settings via
16
- `settingSources: ["project"]`, the `@oked/claude-code` hook would also fire —
17
- this package is for the common programmatic case.)
10
+ ## Why this package
11
+
12
+ The Claude Agent SDK does not read `.claude/settings.json` hooks unless you opt in. Hooks are passed in `options.hooks`. There is no zero-code install: you wire OKed into the agent's options. If you do load project settings with `settingSources: ["project"]`, the `@oked/claude-code` hook would also fire. This package is the programmatic path.
18
13
 
19
14
  ## Install
20
15
 
@@ -22,75 +17,59 @@ this package is for the common programmatic case.)
22
17
  npm install @oked/claude-agent-sdk
23
18
  ```
24
19
 
25
- `@anthropic-ai/claude-agent-sdk` is an optional peer dependency — you already
26
- have it if you're building an agent.
20
+ `@anthropic-ai/claude-agent-sdk` is an optional peer dependency (`>=0.1.0`). You already have it if you are building an agent. Node.js 18 or newer.
27
21
 
28
22
  ## Use
29
23
 
24
+ `okedHooks()` sets the hook timeout to 690 seconds, above the SDK's 630 second wait, so a timeout is a deny instead of the harness aborting the hook with no decision.
25
+
30
26
  ```ts
31
27
  import { query } from "@anthropic-ai/claude-agent-sdk";
32
28
  import { okedHooks } from "@oked/claude-agent-sdk";
33
29
 
34
30
  for await (const message of query({
35
- prompt: "…",
31
+ prompt: "...",
36
32
  options: { hooks: okedHooks() },
37
33
  })) {
38
- // …
34
+ // ...
39
35
  }
40
36
  ```
41
37
 
42
- Or wire the callback yourself for full control over matchers/timeout:
38
+ Or wire the callback yourself. Set `timeout` above 630 seconds if you do.
43
39
 
44
40
  ```ts
45
41
  import { okedPreToolUseHook } from "@oked/claude-agent-sdk";
46
42
 
47
43
  const options = {
48
44
  hooks: {
49
- PreToolUse: [{ hooks: [okedPreToolUseHook] }],
45
+ PreToolUse: [{ hooks: [okedPreToolUseHook], timeout: 690 }],
50
46
  },
51
47
  };
52
48
  ```
53
49
 
54
50
  ## Auth
55
51
 
56
- Bring your own API key (this package has no pairing CLI):
52
+ This package has no pairing command. Provide a key in either place:
57
53
 
58
- - `OKED_API_KEY=ok_…` environment variable, or
59
- - `~/.oked/config.json` (`{ "apiKey": "ok_…" }`)
54
+ - `OKED_API_KEY` in the environment, or
55
+ - `~/.oked/config.json` (`{ "apiKey": "ok_..." }`)
60
56
 
61
- Create a key from the OKed dashboard. Optionally set `OKED_BACKEND_URL` to
62
- target a non-default backend.
57
+ Create a key from the [dashboard](https://oked.ai/dashboard) after you [sign up](https://oked.ai/signup), or run `oked init --key-only` from [`@oked/claude-code`](../claude-code). That command pairs the key as client type `sdk`. Optionally set `OKED_BACKEND_URL` for a non-default backend.
58
+
59
+ Each request sends `source: "claude-agent-sdk"` and `client: "@oked/claude-agent-sdk@<version>"`. Both are part of the receipt subject.
63
60
 
64
61
  ## Behavior
65
62
 
66
- Same tier model and fail-safe semantics as the other OKed integrations:
63
+ Same tiers and fail-safe rules as the other integrations:
67
64
 
68
65
  | Tier | What happens |
69
- |------|--------------|
70
- | `safe` | Allow immediately, no network call |
71
- | `warning` | Allow, log to stderr only, no network call |
72
- | `review` / `high_stakes` | Request approval; **Approve** → run, otherwise the tool call is denied with a reason |
73
-
74
- Failure handling: missing API key → defer to the agent's built-in
75
- permission flow (`ask`); invalid key → deny; backend unreachable → degrade
76
- per tier (`degradedDecision` — high-stakes / strict fail-closed deny, others
77
- may proceed); any unexpected error → deny. Set `OKED_STRICT_FAIL_CLOSED=1`
78
- to deny every sensitive action during backend outages.
79
-
80
- ## Attribution
81
-
82
- Approvals are attributed by the **API key's pairing record** — not a
83
- per-request field. Pair a device with `client_type: "claude-agent-sdk"`
84
- and that clientType plus the host/device name are bonded to the issued API
85
- key (`device_codes` ↔ `api_keys`). Every approval made with that key is
86
- then attributable to `claude-agent-sdk` in the dashboard, via the same
87
- mechanism used for the other integrations.
88
-
89
- This package ships no pairing CLI (callback-only, BYO key), so obtain a
90
- `claude-agent-sdk`-typed key through your pairing flow. A key minted from
91
- the dashboard "create key" UI has no device record and falls back to the
92
- generic `sdk` bucket.
66
+ |---|---|
67
+ | `safe` | Allow immediately, no approval request |
68
+ | `warning` | Allow, log to stderr, no approval request |
69
+ | `review` / `high_stakes` | Ask for approval. Approve and the tool runs. Otherwise it is denied, with a reason. |
70
+
71
+ Failure handling: no API key defers to the agent's own permission flow (`ask`). An invalid key denies. A receipt that does not verify denies. An unreachable backend uses the shared degraded rule: `high_stakes` denies, and lower tiers may proceed unless `OKED_STRICT_FAIL_CLOSED=1`, which denies every sensitive action during an outage. Any other unexpected error denies.
93
72
 
94
73
  ## License
95
74
 
96
- Apache-2.0
75
+ [Apache-2.0](./LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oked/claude-agent-sdk",
3
- "version": "0.6.20",
3
+ "version": "0.6.21",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -32,7 +32,7 @@
32
32
  }
33
33
  },
34
34
  "dependencies": {
35
- "@oked/sdk": "0.6.20"
35
+ "@oked/sdk": "0.6.21"
36
36
  },
37
37
  "devDependencies": {
38
38
  "@anthropic-ai/claude-agent-sdk": "^0.1.0",