@ory/claude-agent-sdk 0.10.0

package/README.md

@@ -0,0 +1,33 @@
+# @ory/claude-agent-sdk
+
+Ory Agent Security for the [Anthropic Claude Agent SDK](https://docs.claude.com/en/docs/claude-code/sdk).
+
+Authorizes every tool call against Ory Permissions, traces invocations, and propagates
+user → agent → sub-agent identity — built on [`@ory/argus`](../core).
+
+```bash
+npm install @ory/claude-agent-sdk
+```
+
+Two interchangeable wiring points:
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { createOryHooks, oryCanUseTool } from "@ory/claude-agent-sdk";
+
+// (a) hooks: SessionStart (auth gates) + PreToolUse (authorize) + PostToolUse (trace)
+query({ prompt, options: { hooks: createOryHooks() } });
+
+// (b) or the permission callback
+query({ prompt, options: { canUseTool: oryCanUseTool() } });
+```
+
+`createOryHooks` runs the Ory session gates on `SessionStart`, authorizes on `PreToolUse`
+(a deny returns `permissionDecision: "deny"`, blocking the tool), records `tool.complete` on
+`PostToolUse`, and writes an agent→subagent delegation tuple when the `Task` tool spawns a
+typed sub-agent. In **observe** mode (default) denies are logged but tools run; in **enforce**
+mode (`ORY_PERMISSION_MODE=enforce`) they're blocked.
+
+This package depends only on `@ory/argus` — the hook and permission types are defined locally
+(no SDK dependency). Credentials come from the shared
+`~/.config/ory-agent-plugins/config.json`. See [docs/sdk-integrations.md](../../docs/sdk-integrations.md).

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Ory Agent Security for the Anthropic Claude Agent SDK.
+ *
+ * Two interchangeable wiring points, both built on the shared `@ory/argus` adapters:
+ *
+ *   - {@link createOryHooks} — a `hooks` config with `SessionStart` (auth gates),
+ *     `PreToolUse` (authorize; `permissionDecision: "deny"` blocks; `Task` sub-agents get a
+ *     delegation tuple), and `PostToolUse` (`tool.complete`).
+ *   - {@link oryCanUseTool} — a `canUseTool` callback returning allow/deny, for callers who
+ *     prefer the single permission-callback surface.
+ *
+ * Pass either into the SDK's `query({ options })`. The package has no SDK dependency.
+ */
+import { OryAgentClient } from "@ory/argus";
+import type { CanUseTool, HooksConfig } from "./types.js";
+export interface OryClaudeAgentOptions {
+    /** Client to use. Defaults to `OryAgentClient.fromEnv("claude-agent-sdk")`. */
+    client?: OryAgentClient;
+    /** Override the Ory project URL for the session gates. */
+    projectUrl?: string;
+    /** Whether a denied tool is hard-blocked. Default true. */
+    canBlock?: boolean;
+}
+/**
+ * Build a `hooks` config object for the Claude Agent SDK's `options.hooks`.
+ */
+export declare function createOryHooks(options?: OryClaudeAgentOptions): HooksConfig;
+/**
+ * Build a `canUseTool` callback gated through Ory. Returns `{ behavior: "deny" }` when the
+ * tool is hard-denied, otherwise `{ behavior: "allow" }`.
+ */
+export declare function oryCanUseTool(options?: OryClaudeAgentOptions): CanUseTool;
+export { OryAgentClient } from "@ory/argus";
+export type { CanUseTool, HooksConfig, HookCallback, PermissionResult, PreToolUseHookInput, PostToolUseHookInput, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Ory Agent Security for the Anthropic Claude Agent SDK.
+ *
+ * Two interchangeable wiring points, both built on the shared `@ory/argus` adapters:
+ *
+ *   - {@link createOryHooks} — a `hooks` config with `SessionStart` (auth gates),
+ *     `PreToolUse` (authorize; `permissionDecision: "deny"` blocks; `Task` sub-agents get a
+ *     delegation tuple), and `PostToolUse` (`tool.complete`).
+ *   - {@link oryCanUseTool} — a `canUseTool` callback returning allow/deny, for callers who
+ *     prefer the single permission-callback surface.
+ *
+ * Pass either into the SDK's `query({ options })`. The package has no SDK dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OryAgentClient = void 0;
+exports.createOryHooks = createOryHooks;
+exports.oryCanUseTool = oryCanUseTool;
+const argus_1 = require("@ory/argus");
+const HARNESS = "claude-agent-sdk";
+function lazySession(client, projectUrl) {
+    let started = false;
+    return async () => {
+        if (started)
+            return;
+        started = true;
+        try {
+            await (0, argus_1.sessionStart)(client, { harness: HARNESS, projectUrl });
+        }
+        catch (err) {
+            client.logger.warn("session_start.failed", {
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    };
+}
+/**
+ * Build a `hooks` config object for the Claude Agent SDK's `options.hooks`.
+ */
+function createOryHooks(options = {}) {
+    const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
+    const canBlock = options.canBlock ?? true;
+    const ensureSession = lazySession(client, options.projectUrl);
+    const sessionStartHook = async () => {
+        await ensureSession();
+        return {};
+    };
+    const preToolUse = async (raw) => {
+        await ensureSession();
+        const input = raw;
+        const toolName = input.tool_name;
+        if ((toolName === "Task" || toolName === "Agent") && typeof input.subagent_type === "string") {
+            await (0, argus_1.registerSubagent)(client, {
+                harness: HARNESS,
+                subAgentType: input.subagent_type,
+                projectUrl: options.projectUrl,
+            }).catch(() => undefined);
+        }
+        const result = await (0, argus_1.gate)(client, {
+            harness: HARNESS,
+            toolName,
+            toolArgs: input.tool_input,
+            canBlock,
+        });
+        if (result.kind === "deny" && result.blocked) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: result.denialMessage ?? "Ory: permission denied",
+                },
+            };
+        }
+        return {};
+    };
+    const postToolUse = async (raw) => {
+        const input = raw;
+        (0, argus_1.complete)(client, { toolName: input.tool_name, output: input.tool_response });
+        return {};
+    };
+    return {
+        SessionStart: [{ hooks: [sessionStartHook] }],
+        PreToolUse: [{ hooks: [preToolUse] }],
+        PostToolUse: [{ hooks: [postToolUse] }],
+    };
+}
+/**
+ * Build a `canUseTool` callback gated through Ory. Returns `{ behavior: "deny" }` when the
+ * tool is hard-denied, otherwise `{ behavior: "allow" }`.
+ */
+function oryCanUseTool(options = {}) {
+    const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
+    const canBlock = options.canBlock ?? true;
+    const ensureSession = lazySession(client, options.projectUrl);
+    return async (toolName, input) => {
+        await ensureSession();
+        const result = await (0, argus_1.gate)(client, {
+            harness: HARNESS,
+            toolName,
+            toolArgs: input,
+            canBlock,
+        });
+        if (result.kind === "deny" && result.blocked) {
+            return { behavior: "deny", message: result.denialMessage ?? "Ory: permission denied" };
+        }
+        return { behavior: "allow", updatedInput: input };
+    };
+}
+var argus_2 = require("@ory/argus");
+Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return argus_2.OryAgentClient; } });

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal Claude Agent SDK hook/permission shapes.
+ *
+ * Defined here (not imported from `@anthropic-ai/claude-agent-sdk`) so the package has no
+ * SDK dependency — same policy as the harness plugins. These mirror the documented
+ * `hooks` + `canUseTool` contracts closely enough to wire the gate.
+ */
+export interface PreToolUseHookInput {
+    hook_event_name?: "PreToolUse";
+    tool_name: string;
+    tool_input?: unknown;
+    /** Present on the `Task` sub-agent tool. */
+    subagent_type?: string;
+    session_id?: string;
+    [key: string]: unknown;
+}
+export interface PostToolUseHookInput {
+    hook_event_name?: "PostToolUse";
+    tool_name: string;
+    tool_input?: unknown;
+    tool_response?: unknown;
+    [key: string]: unknown;
+}
+export interface HookJSONOutput {
+    decision?: "block";
+    reason?: string;
+    hookSpecificOutput?: {
+        hookEventName?: string;
+        permissionDecision?: "allow" | "deny" | "ask";
+        permissionDecisionReason?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export type HookCallback = (input: Record<string, unknown>, toolUseId: string | undefined, context: {
+    signal?: AbortSignal;
+}) => Promise<HookJSONOutput> | HookJSONOutput;
+export interface HookMatcher {
+    matcher?: string;
+    hooks: HookCallback[];
+}
+export type HooksConfig = Record<string, HookMatcher[]>;
+/** `canUseTool` permission-callback result. */
+export type PermissionResult = {
+    behavior: "allow";
+    updatedInput?: unknown;
+} | {
+    behavior: "deny";
+    message: string;
+};
+export type CanUseTool = (toolName: string, input: Record<string, unknown>, context: {
+    signal?: AbortSignal;
+    suggestions?: unknown;
+}) => Promise<PermissionResult>;

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Minimal Claude Agent SDK hook/permission shapes.
+ *
+ * Defined here (not imported from `@anthropic-ai/claude-agent-sdk`) so the package has no
+ * SDK dependency — same policy as the harness plugins. These mirror the documented
+ * `hooks` + `canUseTool` contracts closely enough to wire the gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ory/claude-agent-sdk",
+  "version": "0.10.0",
+  "description": "Ory Agent Security for the Anthropic Claude Agent SDK — per-tool authorization, tracing, and identity propagation via PreToolUse hooks and canUseTool. Built on @ory/argus.",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "keywords": [
+    "ory",
+    "anthropic",
+    "claude",
+    "agent-sdk",
+    "authorization",
+    "agent",
+    "ai"
+  ],
+  "dependencies": {
+    "@ory/argus": "0.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "4.1.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}