@oked/sdk 0.6.20 → 0.6.22

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.
package/README.md CHANGED
@@ -1,12 +1,13 @@
1
1
  # @oked/sdk
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@oked/sdk.svg)](https://www.npmjs.com/package/@oked/sdk)
4
- [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
5
- [![Types: included](https://img.shields.io/npm/types/@oked/sdk.svg)](./dist/index.d.ts)
4
+ [![License: Apache-2.0](https://img.shields.io/npm/l/@oked/sdk.svg)](./LICENSE)
6
5
 
7
- Core library - programmatic approval API for AI agents. Sends sensitive actions to the OKed backend, waits for a human decision, and resolves only when the user approves or denies.
6
+ Programmatic approval API for AI agents. Send a sensitive action to the OKed backend, wait for a person, and continue only when they approve.
8
7
 
9
- Use this package directly from any Node.js agent (OpenAI SDK, LangChain, custom). For drop-in integrations, see [`@oked/claude-code`](../claude-code) or [`@oked/openclaw`](../openclaw).
8
+ Use this package from any Node.js agent. For drop-in integrations, see [`@oked/claude-code`](../claude-code), [`@oked/claude-agent-sdk`](../claude-agent-sdk), [`@oked/openai-agents`](../openai-agents), [`@oked/openclaw`](../openclaw), [`@oked/langgraph`](../langgraph), and [`@oked/ai-sdk`](../ai-sdk). Python agents use [`oked`](../../python/oked) and [`oked-langgraph`](../../python/oked-langgraph). Neither is on PyPI yet. Until then, `pip install "oked @ git+https://github.com/oked-ai/oked-sdk#subdirectory=python/oked"` for the client, and `pip install "oked @ git+https://github.com/oked-ai/oked-sdk#subdirectory=python/oked" "oked-langgraph @ git+https://github.com/oked-ai/oked-sdk#subdirectory=python/oked-langgraph"` for LangGraph. Once it is on PyPI, the commands are `pip install oked` and `pip install oked-langgraph`.
9
+
10
+ Decisions are made in Telegram and on the [web dashboard](https://oked.ai/dashboard). The iPhone app is coming soon. [Sign up](https://oked.ai/signup) to get an API key.
10
11
 
11
12
  ## Install
12
13
 
@@ -14,6 +15,8 @@ Use this package directly from any Node.js agent (OpenAI SDK, LangChain, custom)
14
15
  npm install @oked/sdk
15
16
  ```
16
17
 
18
+ Node.js 18 or newer.
19
+
17
20
  ## Quick start
18
21
 
19
22
  ```ts
@@ -36,78 +39,89 @@ if (!result.approved) {
36
39
  }
37
40
  ```
38
41
 
42
+ The approval window is 10 minutes. The client waits 630 seconds (`630000` ms, `DEFAULT_APPROVAL_TIMEOUT_MS`), 30 seconds past that window, so the backend's `timeout` answer arrives before the client aborts. A timeout is a denial. If you raise `timeout`, raise the harness hook limit above it. Otherwise the process can be killed before the deny is written.
43
+
39
44
  ## Configuration
40
45
 
41
- Pass to `new OKedClient(config)`:
46
+ Pass any of these to `new OKedClient(config)`. Constructor values win over environment variables, which win over `~/.oked/config.json`.
42
47
 
43
48
  | Key | Type | Default | Description |
44
49
  |---|---|---|---|
45
- | `apiKey` | `string` | `OKED_API_KEY` env | Your OKed API key. Required. |
46
- | `backendUrl` | `string` | `https://api.oked.ai` | Override the OKed backend URL. |
47
- | `timeout` | `number` | `630000` | Per-approval timeout in ms (10.5 minutes, just above the backend's 10 minute expiry, so the backend's `timeout` answer arrives first). If you raise it, raise the harness hook timeout to match: it must stay above this value so the fail-safe deny is written before the hook process is killed. |
48
- | `strictFailClosed` | `boolean` | `false` | When true, backend outages deny every tier. When false, outages deny only `high_stakes` and allow lower tiers. |
50
+ | `apiKey` | `string` | `OKED_API_KEY`, then the config file | OKed API key. Required for `approve`. |
51
+ | `timeout` | `number` | `630000` | How long to wait for a decision, in milliseconds. See above. |
52
+ | `strictFailClosed` | `boolean` | `false` | When true, an unreachable backend denies every tier. When false, it denies only `high_stakes`. |
49
53
  | `requireReceipt` | `boolean` | `true` | Deny an approval that arrives without a signed receipt. A receipt that is present but invalid always denies. Set `false` (env `OKED_REQUIRE_RECEIPT=0`) only for a backend that does not sign receipts. |
50
- | `receiptKeysUrl` | `string` | `https://api.oked.ai/.well-known/oked-receipt-keys.json` | Where to fetch a receipt key the SDK has not seen. Independent of `backendUrl`; https only, except loopback. |
51
- | `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch (self-hosted backends, tests). |
52
- | `client` | `string` | | Your integration's name and version, e.g. `my-agent@1.2.0`. Recorded in receipts. |
53
- | `source` | `string` | `"sdk"` | Where requests come from. Part of each receipt's subject. |
54
+ | `receiptKeysUrl` | `string` | `https://api.oked.ai/.well-known/oked-receipt-keys.json` | Where to fetch a receipt key the SDK has not seen. https only, except loopback. |
55
+ | `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch. For self-hosted backends and tests. |
56
+ | `rulesCacheTtlMs` | `number` | `300000` | How long the on-disk rules cache stays fresh. Env `OKED_RULES_CACHE_TTL` is in seconds. |
57
+ | `heartbeatIntervalMs` | `number` | `86400000` | Minimum gap between presence pings. Env `OKED_HEARTBEAT_INTERVAL` is in seconds. |
58
+ | `client` | `string` | | Your integration's name and version, for example `my-agent@1.2.0`. Recorded on the receipt. |
59
+ | `source` | `string` | `"sdk"` | Where the request came from. Part of the receipt subject. |
54
60
 
55
61
  ## API
56
62
 
57
63
  ### `approve(request)`
58
64
 
59
- Request an approval for a sensitive action. Resolves when the user responds, the request times out, or the backend denies.
60
-
61
- Request fields:
65
+ Ask for a decision. Resolves when the person responds, the request times out, or the backend returns an error as a thrown exception (see below).
62
66
 
63
67
  | Field | Type | Required | Description |
64
68
  |---|---|---|---|
65
- | `action` | `string` | yes | Short action identifier (e.g. `"deploy"`, `"send_email"`). |
66
- | `description` | `string` | yes | Human-readable summary shown in the approval UI. |
67
- | `tier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | yes | Risk tier. Use `classify()` if unsure. |
68
- | `tool_input` | `unknown` | no | Raw tool arguments, included in the audit log. |
69
- | `session_id` | `string` | no | Groups related approvals under one session. |
70
- | `cwd` | `string` | no | Working directory, shown in the UI for context. |
71
-
72
- Response fields:
69
+ | `action` | `string` | yes | Short action id, for example `"deploy"`. |
70
+ | `description` | `string` | yes | Text shown on the approval card. |
71
+ | `tier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | yes | Risk tier. Use `classify()` if you are not sure. |
72
+ | `fields` | `Record<string, string>` | no | Card fields (title, target, body, and so on). |
73
+ | `tool_input` | `unknown` | no | Raw tool arguments. Included in the receipt subject. |
74
+ | `session_id` | `string` | no | Groups related approvals. |
75
+ | `cwd` | `string` | no | Working directory, shown for context. |
73
76
 
74
77
  | Field | Type | Description |
75
78
  |---|---|---|
76
- | `approved` | `boolean` | `true` only when the user approved. |
77
- | `approval_id` | `string \| null` | Opaque id for logs / audit. |
78
- | `decision` | `"approved" \| "denied" \| "timeout"` | Exact outcome. |
79
- | `receipt` | `SignedReceipt` | The signed receipt for this decision, already verified: OKed's signature, this request, this decision, and the exact action you sent. See [docs/receipts.md](../../docs/receipts.md). |
79
+ | `approved` | `boolean` | `true` only when the person approved. |
80
+ | `approval_id` | `string \| null` | Id for logs. `null` when the backend created no request row. |
81
+ | `decision` | `"approved" \| "denied" \| "timeout"` | Outcome. |
82
+ | `receipt` | `SignedReceipt \| undefined` | Signed receipt, already verified against this request, this decision, and the exact action you sent. Absent for some denials and timeouts that carry no receipt. See [docs/receipts.md](../../docs/receipts.md). |
80
83
 
81
84
  ### `ping()`
82
85
 
83
- Returns `true` when the backend is reachable. Use for startup health checks.
86
+ Returns `true` when `GET https://api.oked.ai/health` succeeds within 3 seconds.
87
+
88
+ ### `getRules()` and `heartbeat()`
89
+
90
+ `getRules()` returns the operator's rules, cached on disk. `heartbeat()` sends a throttled presence ping and never throws. Integrations call both. You do not need them to use `approve`.
84
91
 
85
92
  ### Helpers
86
93
 
87
- - `classify(input)` - classifies a shell command or tool call into a risk tier.
88
- - `describe(input)` - generates a human-readable description for the approval UI.
94
+ - `classify(toolName, toolInput)` returns a risk tier for a tool call. Pass `{ sandboxEnforced: false }` to ask (`review`) before an opaque runner (`cargo test`, `npm test`, `npm run`, `pytest`, `go test`, `make`, `./script.sh`, `node scripts/x.mjs`, `npx`). Omit the option, or pass `true`, and those commands stay `safe`. Claude Code sets this from sandbox settings. Other hosts omit it.
95
+ - `describe(toolName, toolInput, ctx?)` returns a one-line description.
96
+ - `describeFields(toolName, toolInput, ctx?)` returns the card fields.
89
97
 
90
- Full type definitions ship with the package (`dist/index.d.ts`).
98
+ Full type definitions ship in the package (`dist/index.d.ts`).
91
99
 
92
100
  ## Environment
93
101
 
94
102
  | Var | Required | Description |
95
103
  |---|---|---|
96
- | `OKED_API_KEY` | yes, unless passed in code | Your OKed API key. |
97
- | `OKED_BACKEND_URL` | no | Override the hosted backend URL. |
98
- | `OKED_STRICT_FAIL_CLOSED` | no | Set to `1` or `true` to deny every sensitive action when the backend is unreachable. |
99
- | `OKED_REQUIRE_RECEIPT` | no | Set to `0` to allow an approval that has no receipt (a backend that does not sign receipts). On by default. |
100
- | `OKED_RECEIPT_KEYS_URL` | no | Where to fetch receipt keys (default OKed's published set). |
104
+ | `OKED_API_KEY` | yes, unless passed in code or saved by `oked init` | OKed API key. |
105
+ | `OKED_STRICT_FAIL_CLOSED` | no | `1` or `true` denies every sensitive action when the backend is unreachable. |
106
+ | `OKED_REQUIRE_RECEIPT` | no | `0` allows an approval that has no receipt. On by default. |
107
+ | `OKED_RECEIPT_KEYS_URL` | no | Where to fetch receipt keys. Default is OKed's published set. |
108
+ | `OKED_RULES_CACHE_TTL` | no | Rules cache TTL, in seconds. Default 300. |
109
+ | `OKED_HEARTBEAT_INTERVAL` | no | Minimum seconds between heartbeats. Default 86400. |
101
110
 
102
111
  ## Degraded-mode behavior
103
112
 
104
- Explicit user denials return `{ approved: false }` and should always be treated as final. Invalid API keys throw `OKedAuthError` and should deny. A receipt that does not verify, or an approval with no receipt, throws `OKedReceiptError` and should deny. A request the backend accepted but nobody answered in time returns `decision: "timeout"`, never an outage. If the backend is unreachable, `OKedBackendUnreachableError` lets integrations apply degraded mode: `high_stakes` denies, while lower tiers may proceed unless `strictFailClosed` is enabled. Unexpected errors should be treated as deny.
113
+ Explicit denials return `{ approved: false }` and are final. Invalid API keys throw `OKedAuthError`. A receipt that does not verify, or an approval with no receipt while `requireReceipt` is on, throws `OKedReceiptError`. A request the backend accepted and nobody answered returns `decision: "timeout"`, not an outage error. HTTP 429 throws `OKedTooManyPendingError` (too many approvals are already waiting). Other HTTP errors throw `OKedHttpError`.
114
+
115
+ If the backend is unreachable, `OKedBackendUnreachableError` is the outage signal. `high_stakes` denies. Lower tiers may proceed unless `strictFailClosed` is set. Treat anything else as a deny.
105
116
 
106
117
  ## Development
107
118
 
119
+ From the repo root:
120
+
108
121
  ```bash
109
122
  npm install
110
123
  npm run build
124
+ npm test
111
125
  ```
112
126
 
113
127
  ## License
@@ -1,11 +1,20 @@
1
1
  import type { RiskTier } from "./types.js";
2
- export declare function classify(toolName: string, toolInput: Record<string, unknown>): RiskTier;
2
+ /**
3
+ * `sandboxEnforced: false` asks for `review` before an opaque code runner
4
+ * (a test runner, package script, script file, or npx tool). `true` or omitted
5
+ * leaves those commands `safe`. Claude Code sets this from sandbox settings.
6
+ * Other hosts omit it and keep the previous behaviour.
7
+ */
8
+ export interface ClassifyOptions {
9
+ sandboxEnforced?: boolean;
10
+ }
11
+ export declare function classify(toolName: string, toolInput: Record<string, unknown>, options?: ClassifyOptions): RiskTier;
3
12
  /**
4
13
  * Tier of each step of a compound command, read the way the whole command is
5
14
  * read: a step sees the temp files and temp folders that earlier steps made
6
15
  * (`cat > _s.mjs <<EOF … && rm _s.mjs`). `classify` of one step alone does not.
7
16
  */
8
- export declare function classifyBashSteps(steps: string[]): RiskTier[];
17
+ export declare function classifyBashSteps(steps: string[], sandboxEnforced?: boolean): RiskTier[];
9
18
  /** Split a shell command into top-level segments on the operators that
10
19
  * sequence separate commands: `|`, `||`, `&&`, `;`, and a bare newline (a
11
20
  * newline separates commands in a multi-line script exactly like `;`).
package/dist/classify.js CHANGED
@@ -17,12 +17,14 @@ import { TIER_ORDER } from "./degraded.js";
17
17
  // Tier 3 - review: push notification, tap to approve. Prompt-worthy but not
18
18
  // catastrophic: sensitive-path writes (~/.ssh, shell rc, system
19
19
  // dirs, OKed's own config), sudo, outward message/email sends,
20
- // curl POST/PUT/PATCH with an inline body.
20
+ // curl POST/PUT/PATCH with an inline body, other cloud CLI writes
21
+ // (create, update, upload, preview deploy, kubectl apply/exec).
21
22
  // Tier 4 - high_stakes: push + number matching. Destructive / irreversible /
22
23
  // external: rm of non-temp data, DROP/TRUNCATE/DELETE FROM,
23
24
  // git push --force / reset --hard / branch -D, mkfs / dd-to-device /
24
25
  // shutdown, curl DELETE / file upload / pay-or-send API, ssh/scp,
25
- // npm publish, kill.
26
+ // npm publish, kill, cloud and cluster deletes, terraform apply /
27
+ // pulumi up, production deploys, Stripe CLI writes.
26
28
  // Tools that are always safe (read-only, no side effects)
27
29
  const SAFE_TOOLS = new Set([
28
30
  "Read",
@@ -90,7 +92,7 @@ const WARNING_SESSION_TOOLS = new Set([
90
92
  "WebFetch",
91
93
  ]);
92
94
  /** Built-ins whose tier depends on their input. Returns null for other tools. */
93
- function classifySessionTool(toolName, toolInput) {
95
+ function classifySessionTool(toolName, toolInput, sandboxEnforced) {
94
96
  switch (toolName) {
95
97
  // "keep" leaves everything on disk. "remove" refuses when there is
96
98
  // unsaved work, unless discard_changes deletes it for good.
@@ -101,7 +103,7 @@ function classifySessionTool(toolName, toolInput) {
101
103
  // Monitor runs a shell command (classified like Bash) or reads a WebSocket.
102
104
  case "Monitor":
103
105
  if (typeof toolInput.command === "string")
104
- return classifyBashCommand(toolInput.command);
106
+ return classifyBashCommand(toolInput.command, new Set(), sandboxEnforced);
105
107
  return "warning";
106
108
  // Artifact: publishing puts content on claude.ai; delete is permanent;
107
109
  // read / list / open / quickstart / pin only look or arrange.
@@ -325,6 +327,277 @@ const REVIEW_COMMANDS = [
325
327
  /^gh\s+run\s+(?:cancel|rerun)\b/,
326
328
  /^gh\s+(?:gist|label)\s+(?:create|edit)\b/,
327
329
  ];
330
+ // Cloud, cluster, infrastructure, deploy and payment CLIs change live systems
331
+ // that other people use, so the `safe` default for an unknown command is wrong
332
+ // for their writes. The CLI's own subcommand words pick the tier: a delete, an
333
+ // infrastructure apply, a production deploy or a payment → high_stakes; any
334
+ // other write (create, update, upload, a preview deploy, exec into a pod) →
335
+ // review; reads (`aws s3 ls`, `kubectl get`, `terraform plan`) stay safe, and so
336
+ // do `--help` and dry runs. Matched on the stage's command word, so the CLI name
337
+ // in an argument or a commit message is not the command.
338
+ // A package runner in front of the CLI (`npx vercel@latest --prod`).
339
+ const CLI_RUNNER_RE = /^(?:npx|bunx|pnpx|(?:pnpm|yarn|bun)\s+(?:dlx|exec|x))\s+(?:-\S+\s+)*/;
340
+ // `--dry-run=none` (kubectl) and `--dry-run=false` are real runs.
341
+ const CLI_PREVIEW_ARG_RE = /^(?:--help|-help|--dry-?run(?:=(?:true|client|server))?)$/;
342
+ // Subcommand words that delete, tear down or redeploy a live resource, and
343
+ // words that create or change one. A hyphenated word (`delete-stack`,
344
+ // `add-iam-policy-binding`) is read by its first part.
345
+ const CLOUD_DELETE_WORDS = new Set(["delete", "destroy", "terminate", "purge", "remove", "rm", "rb", "uninstall", "drain"]);
346
+ const CLOUD_DEPLOY_WORDS = new Set(["deploy", "rollback", "promote"]);
347
+ const CLOUD_WRITE_WORDS = new Set([
348
+ "create", "update", "patch", "apply", "set", "unset", "add", "put", "push", "upload", "import",
349
+ "start", "stop", "restart", "reboot", "reset", "resize", "scale", "enable", "disable", "attach",
350
+ "detach", "move", "rename", "restore", "cancel", "upgrade", "install", "invoke", "call", "execute",
351
+ "exec", "ssh", "scp", "submit", "connect", "failover", "issue", "transfer", "clone", "extend",
352
+ "launch", "console",
353
+ ]);
354
+ function cloudWordTier(word) {
355
+ const [head, ...rest] = word.split("-");
356
+ if (rest.length === 0) {
357
+ if (CLOUD_DELETE_WORDS.has(word) || CLOUD_DEPLOY_WORDS.has(word))
358
+ return "high_stakes";
359
+ return CLOUD_WRITE_WORDS.has(word) ? "review" : "safe";
360
+ }
361
+ if (/^(?:delete|destroy|terminate|purge|deregister)$/.test(head))
362
+ return "high_stakes";
363
+ return CLOUD_WRITE_WORDS.has(head) || head === "remove" ? "review" : "safe";
364
+ }
365
+ function maxCloudWordTier(words) {
366
+ return words.reduce((t, w) => maxTier(t, cloudWordTier(w)), "safe");
367
+ }
368
+ /** The non-flag arguments, without the values of `valueFlags` and redirects. */
369
+ function cliPositionals(args, valueFlags = new Set()) {
370
+ const out = [];
371
+ for (let i = 0; i < args.length; i++) {
372
+ const a = args[i];
373
+ if (/^(?:\d|&)?>{1,2}$|^<$/.test(a)) {
374
+ i++;
375
+ continue;
376
+ } // `> log`
377
+ if (/^(?:\d|&)?>|^</.test(a))
378
+ continue; // `2>&1`, `>log`
379
+ if (a.startsWith("-")) {
380
+ if (valueFlags.has(a))
381
+ i++;
382
+ continue;
383
+ }
384
+ out.push(a);
385
+ }
386
+ return out;
387
+ }
388
+ /** `aws s3`, `gsutil`, `gcloud storage`: delete, upload, or download. */
389
+ function objectStoreTier(op, pos, args, scheme) {
390
+ if (op === "rm" || op === "rb")
391
+ return "high_stakes";
392
+ if (op === "mv" || op === "mb")
393
+ return "review";
394
+ if (op === "cp" || op === "sync" || op === "rsync") {
395
+ if (op !== "cp" && args.some((a) => /^(?:--delete|-d|--delete-unmatched-destination-objects)$/.test(a)))
396
+ return "high_stakes";
397
+ return (pos[pos.length - 1] ?? "").startsWith(scheme) ? "review" : "safe"; // to a bucket, or a download
398
+ }
399
+ return null;
400
+ }
401
+ const AWS_VALUE_FLAGS = new Set(["--profile", "--region", "--output", "--endpoint-url", "--query", "--color",
402
+ "--ca-bundle", "--cli-read-timeout", "--cli-connect-timeout", "--cli-binary-format"]);
403
+ // Operations that only read. An aws operation that is not a read is a write.
404
+ const AWS_READ_OP_RE = /^(?:describe|list|get|head|batch-get|search|scan|query|lookup|filter|select|estimate|validate|simulate|test|preview|wait|tail|ls|help|check|presign)(?:-|$)/;
405
+ const AWS_LOCAL_SERVICES = new Set(["configure", "sso", "sso-oidc", "sts", "help", "history"]);
406
+ function awsTier(args) {
407
+ const pos = cliPositionals(args, AWS_VALUE_FLAGS);
408
+ const [service, op] = pos;
409
+ if (!service || !op || AWS_LOCAL_SERVICES.has(service))
410
+ return "safe";
411
+ if (service === "s3")
412
+ return objectStoreTier(op, pos, args, "s3://") ?? (op === "ls" ? "safe" : "review");
413
+ if (/^(?:delete|terminate|purge|deregister|destroy)-/.test(op) || op === "deploy")
414
+ return "high_stakes";
415
+ return AWS_READ_OP_RE.test(op) ? "safe" : "review";
416
+ }
417
+ const KUBECTL_VALUE_FLAGS = new Set(["-n", "--namespace", "--context", "--kubeconfig", "--cluster", "--user",
418
+ "-s", "--server", "--as", "--as-group", "--token", "--request-timeout", "-l", "--selector", "-f",
419
+ "--filename", "-c", "--container", "-o", "--output"]);
420
+ const KUBECTL_WRITE_VERBS = new Set(["apply", "create", "patch", "replace", "edit", "scale", "autoscale", "set",
421
+ "label", "annotate", "taint", "cordon", "uncordon", "expose", "run", "exec", "cp", "attach", "debug", "certificate"]);
422
+ function kubectlTier(args) {
423
+ const [verb, sub] = cliPositionals(args, KUBECTL_VALUE_FLAGS);
424
+ if (verb === "delete" || verb === "drain")
425
+ return "high_stakes";
426
+ if (verb === "rollout")
427
+ return ["restart", "undo", "pause", "resume"].includes(sub) ? "review" : "safe";
428
+ return KUBECTL_WRITE_VERBS.has(verb) ? "review" : "safe";
429
+ }
430
+ function terraformTier(args) {
431
+ let [verb, sub] = cliPositionals(args);
432
+ // terragrunt `run-all apply`
433
+ if (verb === "run-all" || verb === "run")
434
+ [verb, sub] = cliPositionals(args).slice(1);
435
+ if (verb === "apply" || verb === "destroy")
436
+ return "high_stakes";
437
+ if (["import", "taint", "untaint", "force-unlock", "refresh"].includes(verb))
438
+ return "review";
439
+ if (verb === "state" && ["rm", "mv", "push", "replace-provider"].includes(sub))
440
+ return "review";
441
+ if (verb === "workspace" && sub === "delete")
442
+ return "review";
443
+ return "safe";
444
+ }
445
+ const VERCEL_VALUE_FLAGS = new Set(["--scope", "-S", "--token", "-t", "--cwd", "-A", "--local-config", "-Q",
446
+ "--global-config", "--target", "-e", "--env", "-b", "--build-env", "-m", "--meta", "--regions", "--archive"]);
447
+ // Subcommands other than a deploy. A first word that is none of these is a
448
+ // path to deploy, as vercel reads it.
449
+ const VERCEL_SUBCOMMANDS = new Set(["alias", "bisect", "blob", "build", "cache", "certs", "curl", "dev", "dns",
450
+ "domains", "env", "git", "help", "init", "inspect", "install", "integration", "link", "list", "login",
451
+ "logout", "logs", "ls", "mcp", "microfrontends", "open", "project", "projects", "promote", "pull",
452
+ "redeploy", "remove", "rm", "rollback", "switch", "target", "teams", "telemetry", "whoami"]);
453
+ function vercelTier(args) {
454
+ const [sub, op] = cliPositionals(args, VERCEL_VALUE_FLAGS);
455
+ const prod = args.some((a, i) => a === "--prod" || a === "--target=production" ||
456
+ (a === "--target" && args[i + 1] === "production"));
457
+ if (sub === undefined || sub === "deploy" || !VERCEL_SUBCOMMANDS.has(sub))
458
+ return prod ? "high_stakes" : "review";
459
+ if (sub === "redeploy")
460
+ return prod ? "high_stakes" : "review";
461
+ if (["rm", "remove", "promote", "rollback"].includes(sub))
462
+ return "high_stakes";
463
+ if (sub === "alias")
464
+ return op === "set" || op === "rm" || op === "remove" ? "high_stakes" : "safe";
465
+ if (["env", "domains", "dns", "certs", "project", "projects", "teams", "blob", "integration"].includes(sub)) {
466
+ return op === undefined ? "safe" : cloudWordTier(op);
467
+ }
468
+ return "safe";
469
+ }
470
+ /** Tier of a single stage that runs a cloud CLI, or null for any other stage. */
471
+ function classifyCloudCliStage(stage) {
472
+ // The same wrappers the delete scan strips (`xargs kubectl delete`, `do aws
473
+ // s3 rb …`, `time terraform apply`), then a package runner.
474
+ const args = splitArgs(stage.replace(DELETE_LEAD, "").replace(CLI_RUNNER_RE, ""));
475
+ const tool = (args.shift() ?? "").replace(/^.*\//, "").replace(/(?<=.)@.*$/, "");
476
+ const known = ["aws", "kubectl", "helm", "terraform", "tofu", "terragrunt", "pulumi", "cdk", "serverless",
477
+ "sls", "gcloud", "gsutil", "az", "doctl", "eksctl", "vercel", "netlify", "fly", "flyctl", "heroku",
478
+ "wrangler", "firebase", "stripe"];
479
+ if (!known.includes(tool))
480
+ return null;
481
+ // Arguments after `--` belong to another command (`kubectl exec pod -- x
482
+ // --help`), so a `--help` there does not make this one a preview.
483
+ const sep = args.indexOf("--");
484
+ if ((sep === -1 ? args : args.slice(0, sep)).some((a) => CLI_PREVIEW_ARG_RE.test(a)))
485
+ return "safe";
486
+ const pos = cliPositionals(args);
487
+ if (pos[0] === "help")
488
+ return "safe";
489
+ const has = (re) => args.some((a) => re.test(a));
490
+ switch (tool) {
491
+ case "aws": return awsTier(args);
492
+ case "kubectl": return kubectlTier(args);
493
+ case "helm": {
494
+ const [verb] = cliPositionals(args, new Set(["-n", "--namespace", "--kube-context", "--kubeconfig"]));
495
+ if (["uninstall", "delete", "del", "un", "rollback"].includes(verb))
496
+ return "high_stakes";
497
+ return ["install", "upgrade", "push"].includes(verb) ? "review" : "safe";
498
+ }
499
+ case "terraform":
500
+ case "tofu":
501
+ case "terragrunt": return terraformTier(args);
502
+ case "pulumi": {
503
+ const [verb, sub] = cliPositionals(args, new Set(["-s", "--stack", "-C", "--cwd"]));
504
+ if (["up", "update", "destroy"].includes(verb) || (verb === "stack" && sub === "rm"))
505
+ return "high_stakes";
506
+ if (["refresh", "import", "cancel"].includes(verb))
507
+ return "review";
508
+ return verb === "state" && ["delete", "move", "unprotect"].includes(sub) ? "review" : "safe";
509
+ }
510
+ case "cdk": return ["deploy", "destroy"].includes(pos[0]) ? "high_stakes" : pos[0] === "bootstrap" ? "review" : "safe";
511
+ case "serverless":
512
+ case "sls":
513
+ if (["deploy", "remove"].includes(pos[0]))
514
+ return "high_stakes";
515
+ return pos[0] === "invoke" && pos[1] !== "local" ? "review" : "safe";
516
+ case "gcloud":
517
+ case "az":
518
+ case "doctl":
519
+ case "eksctl": {
520
+ const flags = {
521
+ gcloud: ["--project", "--account", "--configuration", "--format", "--verbosity", "--impersonate-service-account"],
522
+ az: ["--subscription", "-o", "--output", "--query"],
523
+ doctl: ["--context", "-t", "--access-token", "-o", "--output", "--config"],
524
+ eksctl: [],
525
+ }[tool];
526
+ const words = cliPositionals(args, new Set(flags));
527
+ // Local CLI config and sign-in (`gcloud config set project x`).
528
+ const local = { gcloud: ["config", "auth", "components", "info", "init", "version", "topic"],
529
+ az: ["account", "config", "configure", "login", "logout", "extension", "version", "upgrade", "cloud", "find"],
530
+ doctl: ["auth", "version", "completion"], eksctl: ["version", "info"] }[tool];
531
+ if (local.includes(words[0]))
532
+ return "safe";
533
+ if (tool === "gcloud" && words[0] === "storage") {
534
+ const t = objectStoreTier(words[1], words, args, "gs://");
535
+ if (t !== null)
536
+ return t;
537
+ }
538
+ // The first word of gcloud, az and doctl is a product group (`gcloud
539
+ // deploy`, `gcloud run`), not a verb. eksctl is verb first.
540
+ return maxCloudWordTier(tool === "eksctl" ? words : words.slice(1));
541
+ }
542
+ case "gsutil": {
543
+ const words = cliPositionals(args, new Set(["-o", "-h", "-u"]));
544
+ const t = objectStoreTier(words[0], words, args, "gs://");
545
+ if (t !== null)
546
+ return t;
547
+ return words[1] === "set" || words[1] === "ch" || words[0] === "setmeta" ? "review" : "safe";
548
+ }
549
+ case "vercel": return vercelTier(args);
550
+ case "netlify": {
551
+ const words = cliPositionals(args, new Set(["--site", "--dir", "-d", "--auth", "--filter", "-a", "-s", "-m", "--message", "--alias"]));
552
+ if (words[0] === "deploy")
553
+ return has(/^(?:--prod|-p|--prodIfUnlocked|--prod-if-unlocked)$/) ? "high_stakes" : "review";
554
+ return cloudWordTier((words[0] ?? "").split(":").pop() ?? "");
555
+ }
556
+ case "fly":
557
+ case "flyctl": {
558
+ const words = cliPositionals(args, new Set(["-a", "--app", "-c", "--config", "-r", "--region", "--image", "-t", "--access-token"]));
559
+ return words.includes("run") ? maxTier("review", maxCloudWordTier(words)) : maxCloudWordTier(words);
560
+ }
561
+ case "heroku": {
562
+ const parts = (cliPositionals(args, new Set(["-a", "--app", "-r", "--remote"]))[0] ?? "").split(":");
563
+ const last = parts[parts.length - 1];
564
+ if (parts[0] === "pg" && ["reset", "copy", "push"].includes(last))
565
+ return "high_stakes";
566
+ return last === "run" ? "review" : cloudWordTier(last);
567
+ }
568
+ case "wrangler": {
569
+ const words = cliPositionals(args, new Set(["-c", "--config", "-e", "--env", "--name"]))
570
+ // `d1 execute` runs on a local database unless `--remote`.
571
+ .filter((w) => w !== "execute" || args.includes("--remote"));
572
+ return words.includes("publish") ? "high_stakes" : maxCloudWordTier(words);
573
+ }
574
+ case "firebase": {
575
+ const words = cliPositionals(args, new Set(["-P", "--project", "--only", "--except", "--token"]));
576
+ const parts = (words[0] ?? "").split(":");
577
+ const last = parts[parts.length - 1];
578
+ if (parts[0] === "emulators")
579
+ return "safe";
580
+ if (words[0] === "deploy" || words[0] === "hosting:disable")
581
+ return "high_stakes";
582
+ // A preview channel deploy (`hosting:channel:deploy`) does not reach the live site.
583
+ return last === "deploy" ? "review" : cloudWordTier(last);
584
+ }
585
+ case "stripe": {
586
+ const [resource, op] = cliPositionals(args, new Set(["--api-key", "--project-name", "-p", "--device-name",
587
+ "--color", "--log-level", "--config"]));
588
+ // A raw API write, or any resource operation that is not a read. Matches
589
+ // the curl rule for the Stripe API: it can move money.
590
+ if (resource === "post" || resource === "delete")
591
+ return "high_stakes";
592
+ const local = ["get", "listen", "logs", "login", "logout", "config", "samples", "trigger", "open",
593
+ "status", "version", "completion", "serve", "resources", "feedback", "community", "daemon", "plugin", "fixtures"];
594
+ if (!resource || !op || local.includes(resource))
595
+ return "safe";
596
+ return ["list", "retrieve", "search"].includes(op) ? "safe" : "high_stakes";
597
+ }
598
+ }
599
+ return null;
600
+ }
328
601
  /**
329
602
  * `gh api` is curl for GitHub: a mutating method, or fields without a method
330
603
  * (gh then sends a POST), is an outward write like a curl POST. A GraphQL call
@@ -348,12 +621,13 @@ function classifyGhApiStage(stage) {
348
621
  // (silent) label, and cover the local mutations we can recognize by shape but
349
622
  // that aren't a plain file write (those are handled by extractShellWriteOps).
350
623
  //
351
- // Opaque code execution (node/npx/python/claude/test runners) is intentionally
352
- // NOT here: we can't tell whether it mutated anything, and a destructive effect
353
- // buried inside `node -e …` would slip through regardless of the label — so
354
- // logging it adds terminal noise without buying safety. It stays `safe`, just
355
- // like any other unrecognized command. A real file write it performs is a
356
- // separate Bash/Write call that gets classified on its own.
624
+ // Opaque code execution (node -e, npx, python -c, test runners, script files)
625
+ // is intentionally NOT a warning marker. A warning only adds a log line, and
626
+ // the hook still cannot see what the child process runs. When the host sandbox
627
+ // is not enforcing containment, classify() with `sandboxEnforced: false` raises
628
+ // test runners and script files to `review` (see isOpaqueCodeRunner). Other
629
+ // hosts omit that option, so those commands stay `safe`. Inline interpreter
630
+ // bodies stay unscanned as shell, because shell tokens in the body are data.
357
631
  const WARNING_COMMANDS = [
358
632
  // Local, reversible git writes — stage/commit/switch/stash. They mutate the
359
633
  // local repo but can be undone (amend, reset, checkout). Destructive git
@@ -544,7 +818,8 @@ function isSensitiveWritePath(filePath) {
544
818
  return true;
545
819
  return false;
546
820
  }
547
- export function classify(toolName, toolInput) {
821
+ export function classify(toolName, toolInput, options) {
822
+ const sandboxEnforced = options?.sandboxEnforced;
548
823
  // Check tool-level classification first
549
824
  if (SAFE_TOOLS.has(toolName))
550
825
  return "safe";
@@ -558,7 +833,7 @@ export function classify(toolName, toolInput) {
558
833
  return "safe";
559
834
  if (WARNING_SESSION_TOOLS.has(toolName))
560
835
  return "warning";
561
- const sessionTier = classifySessionTool(toolName, toolInput);
836
+ const sessionTier = classifySessionTool(toolName, toolInput, sandboxEnforced);
562
837
  if (sessionTier !== null)
563
838
  return sessionTier;
564
839
  // File-editing tools: a write/edit can't act on its own — whatever later
@@ -578,7 +853,7 @@ export function classify(toolName, toolInput) {
578
853
  return "safe";
579
854
  // Bash commands need deeper analysis
580
855
  if (toolName === "Bash") {
581
- return classifyBashCommand(toolInput.command);
856
+ return classifyBashCommand(toolInput.command, new Set(), sandboxEnforced);
582
857
  }
583
858
  // MCP tools: mcp__<server>__<tool>
584
859
  if (toolName.startsWith("mcp__")) {
@@ -589,7 +864,7 @@ export function classify(toolName, toolInput) {
589
864
  // command/cmd field. Route through bash classification.
590
865
  const shellCommand = (toolInput.command ?? toolInput.cmd);
591
866
  if (typeof shellCommand === "string") {
592
- return classifyBashCommand(shellCommand);
867
+ return classifyBashCommand(shellCommand, new Set(), sandboxEnforced);
593
868
  }
594
869
  // File-write-style tools from other agents (OpenClaw `write`, generic
595
870
  // `create_file`, `file_write`). Detect by signature: string path field
@@ -607,13 +882,13 @@ export function classify(toolName, toolInput) {
607
882
  * read: a step sees the temp files and temp folders that earlier steps made
608
883
  * (`cat > _s.mjs <<EOF … && rm _s.mjs`). `classify` of one step alone does not.
609
884
  */
610
- export function classifyBashSteps(steps) {
885
+ export function classifyBashSteps(steps, sandboxEnforced) {
611
886
  const vars = new Set();
612
887
  for (const step of steps)
613
888
  for (const stage of splitTopLevel(step))
614
889
  collectMktempVars(stage, vars);
615
890
  return steps.map((step) => {
616
- const tier = classifyBashCommand(step, vars);
891
+ const tier = classifyBashCommand(step, vars, sandboxEnforced);
617
892
  for (const stage of splitTopLevel(step))
618
893
  noteEphemeralEffects(stripHeredocBodies(stage), vars);
619
894
  return tier;
@@ -784,7 +1059,7 @@ function isBuildOutputOnlyDeletion(command) {
784
1059
  * values, plus any trailing command. A purely literal assignment is `safe`.
785
1060
  * Returns null if the stage is not assignment-prefixed.
786
1061
  */
787
- function classifyAssignmentStage(stage) {
1062
+ function classifyAssignmentStage(stage, sandboxEnforced) {
788
1063
  if (!/^\w+=/.test(stage))
789
1064
  return null;
790
1065
  const inners = [];
@@ -839,9 +1114,9 @@ function classifyAssignmentStage(stage) {
839
1114
  const rest = stage.slice(i).trim();
840
1115
  let tier = "safe";
841
1116
  for (const inner of inners)
842
- tier = maxTier(tier, classifyBashCommand(inner));
1117
+ tier = maxTier(tier, classifyBashCommand(inner, new Set(), sandboxEnforced));
843
1118
  if (rest)
844
- tier = maxTier(tier, classifyBashCommand(rest));
1119
+ tier = maxTier(tier, classifyBashCommand(rest, new Set(), sandboxEnforced));
845
1120
  return tier;
846
1121
  }
847
1122
  /**
@@ -852,7 +1127,7 @@ function classifyAssignmentStage(stage) {
852
1127
  * (quote-preserving) offset. `env` with no command just prints the environment
853
1128
  * → safe. Returns null if the stage doesn't start with `env`.
854
1129
  */
855
- function classifyEnvStage(stage) {
1130
+ function classifyEnvStage(stage, sandboxEnforced) {
856
1131
  const lead = /^env\b[ \t]*/.exec(stage);
857
1132
  if (!lead)
858
1133
  return null;
@@ -903,7 +1178,7 @@ function classifyEnvStage(stage) {
903
1178
  }
904
1179
  if (/^\w+=/.test(tok))
905
1180
  continue; // NAME=VALUE
906
- return classifyBashCommand(stage.slice(start).trim()); // first real word → the command
1181
+ return classifyBashCommand(stage.slice(start).trim(), new Set(), sandboxEnforced); // first real word → the command
907
1182
  }
908
1183
  return "safe"; // `env` / `env -u X` with no command just prints the environment
909
1184
  }
@@ -921,7 +1196,7 @@ const GIT_GLOBAL_ARG_OPTS = new Set([
921
1196
  * can define a shell command, so it gets a `review` floor. Returns null if the
922
1197
  * stage is not a git call with global options.
923
1198
  */
924
- function classifyGitGlobalOptsStage(stage, ephemeralVars) {
1199
+ function classifyGitGlobalOptsStage(stage, ephemeralVars, sandboxEnforced) {
925
1200
  const lead = /^git[ \t]+(?=-)/.exec(stage);
926
1201
  if (!lead)
927
1202
  return null;
@@ -958,7 +1233,7 @@ function classifyGitGlobalOptsStage(stage, ephemeralVars) {
958
1233
  i = readToken(i);
959
1234
  const tok = stage.slice(start, i);
960
1235
  if (!tok.startsWith("-")) {
961
- const inner = classifyBashCommand(`git ${stage.slice(start).trim()}`, ephemeralVars);
1236
+ const inner = classifyBashCommand(`git ${stage.slice(start).trim()}`, ephemeralVars, sandboxEnforced);
962
1237
  return maxTier(floor, inner);
963
1238
  }
964
1239
  let value = "";
@@ -992,7 +1267,7 @@ const SSH_ARG_OPTS = new Set([
992
1267
  * isn't an ssh invocation. Excludes `ssh-keygen`/`ssh-add`/`ssh-keyscan` (the
993
1268
  * `^ssh\s` anchor requires whitespace, not a hyphen).
994
1269
  */
995
- function classifySshStage(stage) {
1270
+ function classifySshStage(stage, sandboxEnforced) {
996
1271
  const lead = /^ssh\s+/.exec(stage);
997
1272
  if (!lead)
998
1273
  return null;
@@ -1050,7 +1325,7 @@ function classifySshStage(stage) {
1050
1325
  if (rest.length >= 2 && (rest[0] === '"' || rest[0] === "'") && rest[rest.length - 1] === rest[0]) {
1051
1326
  rest = rest.slice(1, -1);
1052
1327
  }
1053
- return classifyBashCommand(rest);
1328
+ return classifyBashCommand(rest, new Set(), sandboxEnforced);
1054
1329
  }
1055
1330
  return "review"; // only options / a bare host token → treat as remote access
1056
1331
  }
@@ -1062,11 +1337,11 @@ function classifySshStage(stage) {
1062
1337
  * `grep -c`) is unaffected because the stage doesn't start with a shell name.
1063
1338
  * Returns null if the stage isn't a `sh -c`-style invocation.
1064
1339
  */
1065
- function classifyShellCStage(stage) {
1340
+ function classifyShellCStage(stage, sandboxEnforced) {
1066
1341
  const m = stage.match(/^(?:bash|sh|zsh|ksh|dash)\b[^'"]*?\s-[A-Za-z]*c\s+(['"])([\s\S]*?)\1/);
1067
1342
  if (!m)
1068
1343
  return null;
1069
- return classifyBashCommand(m[2]);
1344
+ return classifyBashCommand(m[2], new Set(), sandboxEnforced);
1070
1345
  }
1071
1346
  // A curl/wget whose target host is loopback (localhost, 127.0.0.0/8, 0.0.0.0,
1072
1347
  // ::1). A request to a server on this machine is a LOCAL action, not an outward
@@ -1095,7 +1370,7 @@ function isLoopbackHttpStage(stage) {
1095
1370
  return false;
1096
1371
  return /(?:^|[\s@])(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1\])(?::\d+)?(?:[/\s'"]|$)/i.test(stage);
1097
1372
  }
1098
- function classifyBashCommand(command, ephemeralVars = new Set()) {
1373
+ function classifyBashCommand(command, ephemeralVars = new Set(), sandboxEnforced) {
1099
1374
  if (!command)
1100
1375
  return "safe";
1101
1376
  // Two views of the command:
@@ -1157,7 +1432,7 @@ function classifyBashCommand(command, ephemeralVars = new Set()) {
1157
1432
  // before the create still counts as a real delete.
1158
1433
  let worst = pipesToShell ? "review" : "safe";
1159
1434
  for (const stage of stages) {
1160
- worst = maxTier(worst, classifyBashCommand(stage, vars));
1435
+ worst = maxTier(worst, classifyBashCommand(stage, vars, sandboxEnforced));
1161
1436
  noteEphemeralEffects(stripHeredocBodies(stage), vars);
1162
1437
  }
1163
1438
  return worst;
@@ -1169,14 +1444,278 @@ function classifyBashCommand(command, ephemeralVars = new Set()) {
1169
1444
  // shell pass short-circuits to `safe` (e.g. an assignment-prefixed node -e).
1170
1445
  const sql = findSqlInCommand(intact);
1171
1446
  const sqlTier = sql ? classifySqlSeverity(sql) : "safe";
1172
- return maxTier(maxTier(sqlTier, pipesToShell ? "review" : "safe"), classifyStageShellEffects(stripped, ephemeralVars));
1447
+ return maxTier(maxTier(sqlTier, pipesToShell ? "review" : "safe"), classifyStageShellEffects(stripped, ephemeralVars, sandboxEnforced));
1173
1448
  }
1174
1449
  /**
1175
1450
  * Shell-effect classification of a SINGLE, already-body-stripped stage. No SQL
1176
1451
  * detection here — that runs on the body-intact view in classifyBashCommand and
1177
1452
  * is folded in by the caller. Returns the stage's tier (default `safe`).
1453
+ * A cloud CLI tier is a floor: it never lowers what the other detectors find
1454
+ * (`kubectl exec pod -- curl -X DELETE …` stays high_stakes).
1178
1455
  */
1179
- function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
1456
+ // Package-manager subcommands that do not run a package script. `yarn build`
1457
+ // and `pnpm build` do: those tools treat an unknown word as a script name.
1458
+ const PM_NON_SCRIPT = new Set([
1459
+ "access", "add", "adduser", "approve-builds", "audit", "bin", "bugs", "cache", "ci", "cit",
1460
+ "completion", "config", "create", "dedupe", "deploy", "deprecate", "diff", "dist-tag", "docs",
1461
+ "doctor", "env", "explain", "explore", "fetch", "find", "fund", "get", "help", "hook", "i",
1462
+ "import", "info", "init", "install", "install-ci-test", "install-test", "it", "licenses",
1463
+ "link", "list", "ll", "login", "logout", "ls", "node", "org", "outdated", "owner", "pack",
1464
+ "patch", "ping", "pkg", "prefix", "profile", "prune", "publish", "query", "rebuild", "repo",
1465
+ "root", "search", "set", "setup", "shrinkwrap", "star", "stars", "store", "team", "token",
1466
+ "uninstall", "unlink", "unplug", "unstar", "update", "upgrade", "up", "version", "view",
1467
+ "whoami", "why",
1468
+ ]);
1469
+ /**
1470
+ * A test runner, package script, script file, or package executor. The hook
1471
+ * sees the runner command, not the processes it starts (a `cargo test` can
1472
+ * run `rm` without a second tool call). Command position only: `echo cargo
1473
+ * test` and `git commit -m "npm test"` are not runners.
1474
+ */
1475
+ function isOpaqueCodeRunner(stage) {
1476
+ const words = stripRunnerPrefixes(withoutShellRedirects(splitArgs(stage)));
1477
+ if (words.length === 0)
1478
+ return false;
1479
+ const [cmd, ...args] = words;
1480
+ if (isDirectScript(cmd))
1481
+ return true;
1482
+ const base = commandBase(cmd);
1483
+ if (base === "source" || cmd === ".")
1484
+ return args.some((w) => w !== "--" && !w.startsWith("-"));
1485
+ if (base === "bash" || base === "sh" || base === "zsh" || base === "dash" || base === "ksh")
1486
+ return shellInvokesFile(args);
1487
+ if (base === "node" || base === "nodejs" || base === "tsx" || base === "deno")
1488
+ return nodeInvokesFile(args);
1489
+ if (base === "npx" || base === "bunx")
1490
+ return npxInvokes(args);
1491
+ if (base === "bun")
1492
+ return pmInvokes(base, args) || bunInvokesFile(args);
1493
+ if (base === "npm" || base === "pnpm" || base === "yarn")
1494
+ return pmInvokes(base, args);
1495
+ if (base === "pytest" || base === "py.test")
1496
+ return true;
1497
+ if (base === "python" || base === "python3" || /^python3\.\d+$/.test(base))
1498
+ return pythonInvokes(args);
1499
+ if (base === "cargo")
1500
+ return cargoInvokesTest(args);
1501
+ if (base === "go")
1502
+ return goInvokesTest(args);
1503
+ if (base === "make" || base === "gmake")
1504
+ return makeInvokes(args);
1505
+ return false;
1506
+ }
1507
+ function commandBase(cmd) {
1508
+ const slash = Math.max(cmd.lastIndexOf("/"), cmd.lastIndexOf("\\"));
1509
+ return slash >= 0 ? cmd.slice(slash + 1) : cmd;
1510
+ }
1511
+ function isDirectScript(cmd) {
1512
+ if (cmd.startsWith("./") || cmd.startsWith("../"))
1513
+ return true;
1514
+ return cmd.includes("/") && /\.(?:sh|bash|zsh|py|rb|pl|[cm]?js|[cm]?ts|mjs|cjs|mts|cts)$/i.test(cmd);
1515
+ }
1516
+ function withoutShellRedirects(words) {
1517
+ const out = [];
1518
+ for (let i = 0; i < words.length; i++) {
1519
+ const w = words[i];
1520
+ if (w === ">" || w === ">>" || w === "<" || w === "<<" || w === ">&" || w === "&>") {
1521
+ i++;
1522
+ continue;
1523
+ }
1524
+ if (/^(?:&>>?|\d*>&?\d*|\d*>>?|[<>])\S*$/.test(w))
1525
+ continue;
1526
+ out.push(w);
1527
+ }
1528
+ return out;
1529
+ }
1530
+ function stripRunnerPrefixes(words) {
1531
+ let i = 0;
1532
+ while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
1533
+ i++;
1534
+ while (i < words.length && (words[i] === "command" || words[i] === "builtin"))
1535
+ i++;
1536
+ return words.slice(i);
1537
+ }
1538
+ function shellInvokesFile(args) {
1539
+ for (let i = 0; i < args.length; i++) {
1540
+ const w = args[i];
1541
+ if (w === "--")
1542
+ return Boolean(args[i + 1]);
1543
+ // `-c` / `-lc` is inline shell. classifyShellCStage already classified a
1544
+ // quoted body. `-n` checks syntax and does not run the file.
1545
+ if (w === "-c" || w === "--command" || /^-[^-]*c/.test(w))
1546
+ return false;
1547
+ if (w === "-n" || w === "--noexec" || /^-[^-]*n/.test(w))
1548
+ return false;
1549
+ if (w.startsWith("-"))
1550
+ continue;
1551
+ return true;
1552
+ }
1553
+ return false;
1554
+ }
1555
+ function nodeInvokesFile(args) {
1556
+ const argTaking = new Set(["-r", "--require", "--import", "--loader", "--experimental-loader", "-C", "--conditions"]);
1557
+ for (let i = 0; i < args.length; i++) {
1558
+ const w = args[i];
1559
+ if (w === "--")
1560
+ return Boolean(args[i + 1]);
1561
+ if (w === "-e" || w === "--eval" || w === "-p" || w === "--print" || w === "-c" || w === "--check")
1562
+ return false;
1563
+ if (w.startsWith("--eval=") || w.startsWith("--print="))
1564
+ return false;
1565
+ if (w === "--test" || w.startsWith("--test"))
1566
+ return true;
1567
+ if (w.startsWith("-")) {
1568
+ if (argTaking.has(w) && !w.includes("="))
1569
+ i++;
1570
+ continue;
1571
+ }
1572
+ return true;
1573
+ }
1574
+ return false;
1575
+ }
1576
+ function npxInvokes(args) {
1577
+ const argTaking = new Set(["-p", "--package", "-c", "--call", "--npm", "--node-options"]);
1578
+ for (let i = 0; i < args.length; i++) {
1579
+ const w = args[i];
1580
+ if (w === "--")
1581
+ return Boolean(args[i + 1]);
1582
+ if (w === "-v" || w === "--version" || w === "-h" || w === "--help")
1583
+ return false;
1584
+ if (w.startsWith("-")) {
1585
+ if ((argTaking.has(w) || w.startsWith("--package=") || w.startsWith("--call=")) && !w.includes("="))
1586
+ i++;
1587
+ continue;
1588
+ }
1589
+ return true;
1590
+ }
1591
+ return false;
1592
+ }
1593
+ function pmPositionals(args) {
1594
+ const skip = new Set(["--prefix", "-C", "--dir", "--workspace", "-w", "--filter", "--cwd"]);
1595
+ const out = [];
1596
+ for (let i = 0; i < args.length; i++) {
1597
+ const w = args[i];
1598
+ if (w === "--")
1599
+ break;
1600
+ if (w.startsWith("-")) {
1601
+ if (skip.has(w))
1602
+ i++;
1603
+ continue;
1604
+ }
1605
+ out.push(w);
1606
+ }
1607
+ return out;
1608
+ }
1609
+ function bunInvokesFile(args) {
1610
+ const file = pmPositionals(args)[0];
1611
+ if (!file)
1612
+ return false;
1613
+ return file.startsWith("./") || file.startsWith("../") || file.includes("/") || /\.(?:[cm]?[jt]sx?|mjs|cjs)$/i.test(file);
1614
+ }
1615
+ function pmInvokes(pm, args) {
1616
+ const pos = pmPositionals(args);
1617
+ const sub = pos[0];
1618
+ if (!sub)
1619
+ return false;
1620
+ if (sub === "test" || sub === "t" || sub === "tst" || sub === "start" || sub === "stop" || sub === "restart")
1621
+ return true;
1622
+ if ((sub === "run" || sub === "run-script") && pos[1])
1623
+ return true;
1624
+ if ((sub === "exec" || sub === "dlx") && pos[1])
1625
+ return true;
1626
+ // yarn and pnpm run a package script named by the first word (`yarn build`).
1627
+ if ((pm === "yarn" || pm === "pnpm") && !PM_NON_SCRIPT.has(sub))
1628
+ return true;
1629
+ return false;
1630
+ }
1631
+ function pythonInvokes(args) {
1632
+ const takes = new Set(["-W", "-X"]);
1633
+ for (let i = 0; i < args.length; i++) {
1634
+ const w = args[i];
1635
+ if (w === "-c" || w === "--command")
1636
+ return false;
1637
+ if (w === "-m" || w === "--module") {
1638
+ const mod = args[i + 1];
1639
+ return mod === "pytest" || mod === "unittest";
1640
+ }
1641
+ if (w.startsWith("-")) {
1642
+ if (takes.has(w))
1643
+ i++;
1644
+ continue;
1645
+ }
1646
+ return true;
1647
+ }
1648
+ return false;
1649
+ }
1650
+ function cargoInvokesTest(args) {
1651
+ let i = 0;
1652
+ if (args[0]?.startsWith("+"))
1653
+ i++;
1654
+ const takes = new Set([
1655
+ "--manifest-path", "--target", "--target-dir", "--config", "-Z", "--color",
1656
+ "--features", "-F", "--package", "-p", "--exclude", "--bin", "--example", "--test", "--bench",
1657
+ ]);
1658
+ for (; i < args.length; i++) {
1659
+ const w = args[i];
1660
+ if (w.startsWith("-")) {
1661
+ if (takes.has(w) && !w.includes("="))
1662
+ i++;
1663
+ continue;
1664
+ }
1665
+ return w === "test";
1666
+ }
1667
+ return false;
1668
+ }
1669
+ function goInvokesTest(args) {
1670
+ const takes = new Set(["-C", "-o", "-p"]);
1671
+ for (let i = 0; i < args.length; i++) {
1672
+ const w = args[i];
1673
+ if (w.startsWith("-")) {
1674
+ if ((takes.has(w) || w === "-ldflags" || w === "-gcflags") && !w.includes("="))
1675
+ i++;
1676
+ continue;
1677
+ }
1678
+ return w === "test";
1679
+ }
1680
+ return false;
1681
+ }
1682
+ function makeInvokes(args) {
1683
+ let dry = false;
1684
+ let help = false;
1685
+ const positionals = [];
1686
+ const takes = new Set([
1687
+ "-C", "--directory", "-f", "--file", "--makefile", "-I", "--include-dir",
1688
+ "-o", "--old-file", "-W", "--what-if", "--assume-new", "--eval",
1689
+ ]);
1690
+ for (let i = 0; i < args.length; i++) {
1691
+ const w = args[i];
1692
+ if (w === "-n" || w === "--dry-run" || w === "--just-print" || w === "--recon") {
1693
+ dry = true;
1694
+ continue;
1695
+ }
1696
+ if (w === "--version" || w === "-v" || w === "--help" || w === "-h") {
1697
+ help = true;
1698
+ continue;
1699
+ }
1700
+ if (w.startsWith("-")) {
1701
+ if (/^-[^-]*n/.test(w))
1702
+ dry = true;
1703
+ if (takes.has(w))
1704
+ i++;
1705
+ continue;
1706
+ }
1707
+ positionals.push(w);
1708
+ }
1709
+ if (dry)
1710
+ return false;
1711
+ if (help && positionals.length === 0)
1712
+ return false;
1713
+ return true;
1714
+ }
1715
+ function classifyStageShellEffects(stage, ephemeralVars = new Set(), sandboxEnforced) {
1716
+ return maxTier(classifyCloudCliStage(stage) ?? "safe", classifyStageEffects(stage, ephemeralVars, sandboxEnforced));
1717
+ }
1718
+ function classifyStageEffects(stage, ephemeralVars, sandboxEnforced) {
1180
1719
  // File deletion in COMMAND POSITION, per-stage so the ephemeral-temp carve-out
1181
1720
  // can win: deleting only throwaway temp files (/tmp, $TMPDIR, /var/folders, …)
1182
1721
  // → warning; any non-temp target (or the temp root itself) → high_stakes.
@@ -1186,7 +1725,7 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
1186
1725
  return "warning";
1187
1726
  // `git -C repo …` / `git -c k=v …`: classify the subcommand without the
1188
1727
  // global options, so the git patterns below and in the full scan apply.
1189
- const gitTier = classifyGitGlobalOptsStage(stage, ephemeralVars);
1728
+ const gitTier = classifyGitGlobalOptsStage(stage, ephemeralVars, sandboxEnforced);
1190
1729
  if (gitTier !== null)
1191
1730
  return gitTier;
1192
1731
  if (isBuildOutputOnlyDeletion(stage.replace(DELETE_LEAD, "")))
@@ -1246,19 +1785,19 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
1246
1785
  // / capture). Classify the command-substitution inners and any trailing
1247
1786
  // command; a purely literal assignment is safe. Dangerous substitutions were
1248
1787
  // already caught by the high-stakes/delete scans above.
1249
- const assignTier = classifyAssignmentStage(stage);
1788
+ const assignTier = classifyAssignmentStage(stage, sandboxEnforced);
1250
1789
  if (assignTier !== null)
1251
1790
  return assignTier;
1252
1791
  // `env [opts] [NAME=VAL]... cmd` runs cmd with a modified environment. Strip
1253
1792
  // the env prefix and classify the inner command (a dangerous inner was already
1254
1793
  // caught by the high-stakes full scan). Bare `env` just prints the env → safe.
1255
- const envTier = classifyEnvStage(stage);
1794
+ const envTier = classifyEnvStage(stage, sandboxEnforced);
1256
1795
  if (envTier !== null)
1257
1796
  return envTier;
1258
1797
  // ssh is a transport — classify the remote command it runs (interactive /
1259
1798
  // port-forwarding ssh has no inspectable command → review floor). scp/rsync
1260
1799
  // to a remote are file transfers and stay high_stakes (HIGH_STAKES_STAGE).
1261
- const sshTier = classifySshStage(stage);
1800
+ const sshTier = classifySshStage(stage, sandboxEnforced);
1262
1801
  if (sshTier !== null)
1263
1802
  return sshTier;
1264
1803
  // `sh -c '<shell>'` / `bash -c "<shell>"` runs the quoted argument AS shell —
@@ -1266,7 +1805,7 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
1266
1805
  // is why the command-position delete scan above can ignore quoted text: a real
1267
1806
  // shell-out like `bash -c 'rm -rf /important'` is caught HERE, by re-running
1268
1807
  // the body as a command, while `echo 'rm …'` (data) is not.
1269
- const shellCTier = classifyShellCStage(stage);
1808
+ const shellCTier = classifyShellCStage(stage, sandboxEnforced);
1270
1809
  if (shellCTier !== null)
1271
1810
  return shellCTier;
1272
1811
  // sudo: privilege escalation. A high-stakes inner command was already caught
@@ -1298,6 +1837,12 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
1298
1837
  }
1299
1838
  // Default: safe. No destructive/outward/sensitive effect was detected, so we
1300
1839
  // do NOT put a human in the loop just for "running a command".
1840
+ // Exception: an opaque runner (test runner, package script, script file, npx)
1841
+ // hides child processes from this hook. When the host sandbox is not
1842
+ // enforcing containment, that asks for review. A higher tier above already
1843
+ // returned. Other hosts leave sandboxEnforced unset and stay safe.
1844
+ if (sandboxEnforced === false && isOpaqueCodeRunner(stage))
1845
+ return "review";
1301
1846
  return "safe";
1302
1847
  }
1303
1848
  function classifySqlSeverity(sql) {
@@ -1450,13 +1995,13 @@ export function blankTextCommandArgs(command) {
1450
1995
  .join("\n");
1451
1996
  }
1452
1997
  // Interpreters whose inline `-e`/`-c`/`--eval` (and perl/deno one-liner) body is
1453
- // opaque CODE — not shell. We blank that body before the SHELL-pattern scans so
1998
+ // opaque CODE, not shell. We blank that body before the SHELL-pattern scans so
1454
1999
  // tokens embedded as code or data (`rm`, `curl -d`, a `>` redirect) don't trip a
1455
- // destructive/outward rule. This matches the documented policy that opaque code
1456
- // execution is `safe` (see the WARNING_COMMANDS note): we can't tell what a
1457
- // `node -e`/`python -c` body does, and a real destructive shell effect buried
1458
- // inside it would slip through the label regardless — so scanning the body for
1459
- // shell tokens only manufactures false positives.
2000
+ // destructive/outward rule. Inline interpreter bodies stay unscanned as shell
2001
+ // (see the WARNING_COMMANDS note): we can't tell what a `node -e`/`python -c`
2002
+ // body does, and scanning it for shell tokens only manufactures false positives.
2003
+ // A test runner or a script file is different: its body is not in the command
2004
+ // at all. Those ask for review when sandboxEnforced is false.
1460
2005
  //
1461
2006
  // NOTE: SQL is the deliberate exception. classifyBashCommand still runs SQL
1462
2007
  // detection on the body-INTACT view, so inline SQL in a `node -e`/`python -c`
@@ -1887,6 +2432,12 @@ function classifyMcpTool(toolName, toolInput = {}) {
1887
2432
  // but each push is gated on its own. Log it, no prompt.
1888
2433
  if (parts.includes("ccd_pr") && tool === "set_monitor")
1889
2434
  return "warning";
2435
+ // The PR bar's auto-merge switch. On, GitHub merges the PR when checks pass
2436
+ // and no other card comes, the same as `gh pr merge --auto`. Off only stops
2437
+ // a merge that has not happened yet: log it, no prompt.
2438
+ if (parts.includes("ccd_pr") && tool === "set_auto_merge") {
2439
+ return toolInput.enabled === false ? "warning" : "high_stakes";
2440
+ }
1890
2441
  // Start a new local Claude session, or move this task into one. Its own tool
1891
2442
  // calls are gated by OKed like this one's, so log it, no prompt. A cloud or
1892
2443
  // SSH session runs outside this machine's hook, so it stays `review`.
@@ -18,6 +18,8 @@ export interface Rendered {
18
18
  link?: string;
19
19
  kind: OperationKind;
20
20
  }
21
+ /** Shown when an opaque runner asks for review because the sandbox is off. */
22
+ export declare const OPAQUE_RUNNER_FOOTNOTE = "OKed cannot see the commands inside this run. Enable Claude Code's Bash sandbox and set allowUnsandboxedCommands to false to allow these without a prompt.";
21
23
  /** Optional caller context. `cwd` lets describers read local files (e.g. the
22
24
  * package.json behind `npm publish`) to show what an action will touch. */
23
25
  export interface DescribeContext {
@@ -25,6 +27,11 @@ export interface DescribeContext {
25
27
  /** Title of the PR the card links to, when the command does not say it.
26
28
  * `lookupPrTitle()` gets it from GitHub. */
27
29
  prTitle?: string;
30
+ /**
31
+ * `false` when the host sandbox is not enforcing containment. An opaque
32
+ * runner then gets a footnote explaining how to skip the prompt.
33
+ */
34
+ sandboxEnforced?: boolean;
28
35
  }
29
36
  export declare function describe(toolName: string, toolInput: Record<string, unknown>, ctx?: DescribeContext): string;
30
37
  export declare function describeFields(toolName: string, toolInput: Record<string, unknown>, ctx?: DescribeContext): Record<string, string> | null;
package/dist/describe.js CHANGED
@@ -15,6 +15,8 @@ import { TIER_ORDER } from "./degraded.js";
15
15
  const BODY_PREVIEW_MAX = 200;
16
16
  const COMMAND_INLINE_MAX = 50;
17
17
  const DIFF_HUNK_MAX_LINES = 10;
18
+ /** Shown when an opaque runner asks for review because the sandbox is off. */
19
+ export const OPAQUE_RUNNER_FOOTNOTE = "OKed cannot see the commands inside this run. Enable Claude Code's Bash sandbox and set allowUnsandboxedCommands to false to allow these without a prompt.";
18
20
  export function describe(toolName, toolInput, ctx = {}) {
19
21
  // Single-line consumers (audit logs, SMS) get title + target inlined.
20
22
  const r = summarize(toolName, toolInput, ctx);
@@ -54,7 +56,17 @@ export function describeFields(toolName, toolInput, ctx = {}) {
54
56
  // ───────────────────────────────────────────────────────────────────────
55
57
  function summarize(toolName, toolInput, ctx) {
56
58
  const r = summarizeTool(toolName, toolInput, ctx);
57
- return ctx.prTitle ? namePr(r, ctx.prTitle) : r;
59
+ const named = ctx.prTitle ? namePr(r, ctx.prTitle) : r;
60
+ if (ctx.sandboxEnforced !== false || named.footnote)
61
+ return named;
62
+ // The runner is the reason for the card: the same call is safe when the
63
+ // sandbox flag is omitted. A higher effect (rm, a force push) keeps its
64
+ // own text.
65
+ const plain = classify(toolName, toolInput);
66
+ const gated = classify(toolName, toolInput, { sandboxEnforced: false });
67
+ if (plain === "safe" && gated === "review")
68
+ return { ...named, footnote: OPAQUE_RUNNER_FOOTNOTE };
69
+ return named;
58
70
  }
59
71
  /**
60
72
  * "Merge PR #49 in o/r" says which PR, not what it does. Put the PR title after
@@ -73,7 +85,7 @@ function summarizeTool(toolName, toolInput, ctx) {
73
85
  const fileSizeBytes = typeof toolInput._file_size_bytes === "number" ? toolInput._file_size_bytes : undefined;
74
86
  switch (toolName) {
75
87
  case "Bash":
76
- return summarizeBash(toolInput.command || "", fileSizeBytes, ctx.cwd);
88
+ return summarizeBash(toolInput.command || "", fileSizeBytes, ctx.cwd, ctx.sandboxEnforced);
77
89
  case "Write":
78
90
  return summarizeWrite(toolInput);
79
91
  case "Edit":
@@ -96,7 +108,7 @@ function summarizeTool(toolName, toolInput, ctx) {
96
108
  // Shell-exec wrappers: signature is a string command/cmd field
97
109
  const shellCommand = (toolInput.command ?? toolInput.cmd);
98
110
  if (typeof shellCommand === "string") {
99
- return summarizeBash(shellCommand, fileSizeBytes);
111
+ return summarizeBash(shellCommand, fileSizeBytes, undefined, ctx.sandboxEnforced);
100
112
  }
101
113
  // File-write wrappers: signature is a path + content/data string
102
114
  const writePath = (toolInput.file_path ?? toolInput.path);
@@ -192,11 +204,11 @@ function extractCurlPayload(cmd) {
192
204
  const parts = [data.join("&"), json.join(""), form.join("\n")].filter(Boolean);
193
205
  return parts.length ? parts.join("\n") : undefined;
194
206
  }
195
- function summarizeBash(command, sizeBytes, cwd) {
207
+ function summarizeBash(command, sizeBytes, cwd, sandboxEnforced) {
196
208
  let cmd = (command || "").trim();
197
209
  if (!cmd)
198
210
  return { title: "Run empty command", kind: "unknown_bash" };
199
- const compound = summarizeCompoundBash(cmd, sizeBytes, cwd);
211
+ const compound = summarizeCompoundBash(cmd, sizeBytes, cwd, sandboxEnforced);
200
212
  if (compound)
201
213
  return compound;
202
214
  // SQL detection runs before shell-write detection so that inline-interpreter
@@ -458,17 +470,18 @@ function summarizeBash(command, sizeBytes, cwd) {
458
470
  * from a pattern that spans steps (`curl … | sh`): the whole-command rules
459
471
  * below describe those.
460
472
  */
461
- function summarizeCompoundBash(cmd, sizeBytes, cwd) {
473
+ function summarizeCompoundBash(cmd, sizeBytes, cwd, sandboxEnforced) {
462
474
  const steps = splitTopLevel(cmd, { pipes: false });
463
475
  if (steps.length < 2)
464
476
  return null;
465
477
  // Each step sees what earlier steps made (a temp file a later `rm` deletes),
466
478
  // as the whole command does. Alone, that `rm` would outrank the real step.
467
- const rank = classifyBashSteps(steps).map((t) => TIER_ORDER[t]);
479
+ const rank = classifyBashSteps(steps, sandboxEnforced).map((t) => TIER_ORDER[t]);
468
480
  const top = Math.max(...rank);
469
481
  if (top < TIER_ORDER.review)
470
482
  return null;
471
- if (TIER_ORDER[classify("Bash", { command: cmd })] !== top)
483
+ const whole = classify("Bash", { command: cmd }, sandboxEnforced === undefined ? undefined : { sandboxEnforced });
484
+ if (TIER_ORDER[whole] !== top)
472
485
  return null;
473
486
  const lead = rank.indexOf(top);
474
487
  // Variables set by earlier steps (`D=/dir; rm $D/x`) show as their values.
@@ -1015,7 +1028,7 @@ function summarizeSql(sql, originalCommand) {
1015
1028
  * to X", "Delete email N", "Purge folder Y") instead of a raw shell line.
1016
1029
  *
1017
1030
  * Used for both the approval-card display (so the user sees "Send email to
1018
- * orendor@gmail.com" with the subject + sender, not a printf|himalaya
1031
+ * contact@oked.ai" with the subject + sender, not a printf|himalaya
1019
1032
  * pipeline) and the analytics `operation_kind`.
1020
1033
  *
1021
1034
  * Returns null if the command mentions himalaya but doesn't match a known
@@ -1362,6 +1375,25 @@ function summarizeDesktopApp(server, tool, input) {
1362
1375
  };
1363
1376
  }
1364
1377
  }
1378
+ if (server === "ccd_pr" && tool === "set_auto_merge") {
1379
+ // Same card as `gh pr merge --auto`: the PR, the method, and when it merges.
1380
+ const pr = str(input.url)?.match(/^https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)/);
1381
+ const where = pr ? `PR #${pr[2]} in ${pr[1]}` : "PR";
1382
+ const link = pr ? `https://github.com/${pr[1]}/pull/${pr[2]}` : undefined;
1383
+ if (input.enabled === false) {
1384
+ return { title: `Turn off auto-merge for ${where}`, link, kind: "git_pr_write" };
1385
+ }
1386
+ return {
1387
+ title: `Merge ${where}`,
1388
+ annotation: [str(input.merge_method), "when checks pass"].filter(Boolean).join(", "),
1389
+ link,
1390
+ kind: "git_pr_merge",
1391
+ };
1392
+ }
1393
+ if (server === "ccd_session_mgmt" && tool === "send_message") {
1394
+ const message = str(input.message);
1395
+ return { title: "Send a message to another Claude session", body: message ? truncateBody(message) : undefined, kind: "agent_message" };
1396
+ }
1365
1397
  if (server === "ccd_turn" && tool === "update_plan") {
1366
1398
  return { title: "Update the task list in the Claude app", kind: "session_housekeeping" };
1367
1399
  }
package/dist/index.d.ts CHANGED
@@ -46,8 +46,9 @@ export { checkReceipt, keysFor, keysUrlAllowed, OKED_RECEIPT_KEYS_URL } from "./
46
46
  export { PINNED_RECEIPT_KEYS } from "./receipt-keys.js";
47
47
  export { verifyReceipt, verifyChain, shortReceiptId, type SignedReceipt, type ReceiptBody, type ReceiptKey, } from "@oked/receipt-core";
48
48
  export { TIER_ORDER, degradedDecision } from "./degraded.js";
49
- export { classify } from "./classify.js";
50
- export { describe, describeFields } from "./describe.js";
49
+ export { classify, splitTopLevel, type ClassifyOptions } from "./classify.js";
50
+ export { describe, describeFields, OPAQUE_RUNNER_FOOTNOTE } from "./describe.js";
51
+ export type { DescribeContext } from "./describe.js";
51
52
  export { lookupPrTitle } from "./pr-title.js";
52
53
  export { applyRules } from "./rules.js";
53
54
  export type { Rule, RuleMatch, RuleAction, RuleDecision, FieldOp, } from "./rules.js";
package/dist/index.js CHANGED
@@ -397,8 +397,8 @@ export { checkReceipt, keysFor, keysUrlAllowed, OKED_RECEIPT_KEYS_URL } from "./
397
397
  export { PINNED_RECEIPT_KEYS } from "./receipt-keys.js";
398
398
  export { verifyReceipt, verifyChain, shortReceiptId, } from "@oked/receipt-core";
399
399
  export { TIER_ORDER, degradedDecision } from "./degraded.js";
400
- export { classify } from "./classify.js";
401
- export { describe, describeFields } from "./describe.js";
400
+ export { classify, splitTopLevel } from "./classify.js";
401
+ export { describe, describeFields, OPAQUE_RUNNER_FOOTNOTE } from "./describe.js";
402
402
  export { lookupPrTitle } from "./pr-title.js";
403
403
  export { applyRules } from "./rules.js";
404
404
  export { CLASSIFIER_VERSION } from "./kinds.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oked/sdk",
3
- "version": "0.6.20",
3
+ "version": "0.6.22",
4
4
  "description": "OKed SDK - human approval layer for AI agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -45,11 +45,11 @@
45
45
  "access": "public"
46
46
  },
47
47
  "dependencies": {
48
- "@oked/receipt-core": "0.6.20"
48
+ "@oked/receipt-core": "0.6.22"
49
49
  },
50
50
  "devDependencies": {
51
- "@types/node": "^22.13.10",
52
- "tsx": "^4.22.0",
53
- "typescript": "^5.6.0"
51
+ "@types/node": "^26.6.5",
52
+ "tsx": "^4.23.15",
53
+ "typescript": "^7.0.2"
54
54
  }
55
55
  }