@ory/claude-agent-sdk 0.14.0 → 1.0.0

package/README.md

@@ -2,8 +2,8 @@
 
 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).
+Authorizes every tool call against Ory Permissions, records invocation activity, and propagates
+user → agent → sub-agent identity — built on [`@ory/argus`](https://www.npmjs.com/package/@ory/argus).
 
 ```bash
 npm install @ory/claude-agent-sdk
@@ -15,7 +15,7 @@ Two interchangeable wiring points:
 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)
+// (a) hooks: SessionStart (root auth) + SubagentStart (child auth) + tool authorization/activity
 query({ prompt, options: { hooks: createOryHooks() } });
 
 // (b) or the permission callback
@@ -24,10 +24,11 @@ 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 permission 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.
+`PostToolUse`, and enrolls each typed child from the authoritative `SubagentStart` event using
+its `session_id`, `agent_type`, and `agent_id`. Later hooks executing inside that child reload
+its scoped credential before permission and event requests. In **observe** mode (default) denies
+are logged but tools run; in **enforce** mode 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).
+the operating system credential store; plaintext configuration contains no runtime secrets.

package/dist/index.d.ts

@@ -4,8 +4,8 @@
  * 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`).
+ *     `SubagentStart` (child identity enrollment), `PreToolUse` (authorize;
+ *     `permissionDecision: "deny"` blocks), and `PostToolUse` (`tool.complete`).
  *   - {@link oryCanUseTool} — a `canUseTool` callback returning allow/deny, for callers who
  *     prefer the single permission-callback surface.
  *

package/dist/index.js

@@ -5,8 +5,8 @@
  * 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`).
+ *     `SubagentStart` (child identity enrollment), `PreToolUse` (authorize;
+ *     `permissionDecision: "deny"` blocks), and `PostToolUse` (`tool.complete`).
  *   - {@link oryCanUseTool} — a `canUseTool` callback returning allow/deny, for callers who
  *     prefer the single permission-callback surface.
  *
@@ -18,91 +18,124 @@ exports.createOryHooks = createOryHooks;
 exports.oryCanUseTool = oryCanUseTool;
 const argus_1 = require("@ory/argus");
 const HARNESS = "claude-agent-sdk";
-/**
- * Extract the sub-agent type from a `Task`/`Agent` PreToolUse payload.
- *
- * In the real Claude PreToolUse contract `subagent_type` is a field of the
- * Task tool's `tool_input`, so that is the primary location. A top-level
- * `subagent_type` is kept as a harmless fallback for older payload shapes.
- */
-function resolveSubAgentType(input) {
-    const toolInput = input.tool_input;
-    if (typeof toolInput === "object" &&
-        toolInput !== null &&
-        typeof toolInput.subagent_type === "string") {
-        return toolInput.subagent_type;
-    }
-    return typeof input.subagent_type === "string" ? input.subagent_type : undefined;
-}
-function lazySession(client, projectUrl) {
-    let sessionPromise;
-    // Cache the in-flight promise (not a boolean) so concurrent first calls all
-    // await the same session start instead of racing past a still-running gate.
-    // Fail-open: a rejection is logged, never rethrown, and clears the cache so
-    // a later call can retry.
-    return () => {
-        sessionPromise ??= (0, argus_1.sessionStart)(client, { harness: HARNESS, projectUrl }).then(() => undefined, (err) => {
-            sessionPromise = undefined;
-            client.logger.warn("session_start.failed", {
-                message: err instanceof Error ? err.message : String(err),
-            });
-        });
-        return sessionPromise;
-    };
-}
 /**
  * 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 ensureSession = (0, argus_1.createSessionStarter)(client, {
+        harness: HARNESS,
+        projectUrl: options.projectUrl,
+    });
+    const sessionStartHook = async (raw) => {
+        const sessionId = typeof raw.session_id === "string" ? raw.session_id : undefined;
+        return (0, argus_1.withHookContext)(client, { sessionId }, async () => {
+            await ensureSession();
+            return {};
+        });
     };
     const preToolUse = async (raw) => {
-        await ensureSession();
         const input = raw;
-        const toolName = input.tool_name;
-        if (toolName === "Task" || toolName === "Agent") {
-            const subAgentType = resolveSubAgentType(input);
-            if (subAgentType) {
+        return (0, argus_1.withHookContext)(client, { sessionId: input.session_id }, async () => {
+            await ensureSession();
+            const toolName = input.tool_name;
+            const active = await activateSubagent(client, input);
+            const result = await (0, argus_1.withHookContext)(client, { runtimeCredential: active.runtimeCredential }, () => (0, argus_1.gate)(client, {
+                harness: HARNESS,
+                toolName,
+                toolArgs: input.tool_input,
+                canBlock,
+                principals: active.principals,
+            }));
+            if (result.kind === "deny" && result.blocked) {
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "deny",
+                        permissionDecisionReason: result.denialMessage ?? "Ory: permission denied",
+                    },
+                };
+            }
+            return {};
+        });
+    };
+    const subagentStart = async (raw, _toolUseId, context) => {
+        const input = raw;
+        return (0, argus_1.withHookContext)(client, { sessionId: input.session_id }, async () => {
+            await ensureSession();
+            const subAgentType = input.agent_type ?? input.subagent_type;
+            if (subAgentType && input.agent_id) {
                 await (0, argus_1.registerSubagent)(client, {
                     harness: HARNESS,
                     subAgentType,
                     projectUrl: options.projectUrl,
+                    sessionId: input.session_id,
+                    perSpawnId: input.agent_id,
+                    signal: context.signal,
                 }).catch(() => undefined);
             }
-        }
-        const result = await (0, argus_1.gate)(client, {
-            harness: HARNESS,
-            toolName,
-            toolArgs: input.tool_input,
-            canBlock,
+            return {};
         });
-        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 (0, argus_1.withHookContext)(client, { sessionId: input.session_id }, async () => {
+            const active = await activateSubagent(client, input);
+            return (0, argus_1.withHookContext)(client, { runtimeCredential: active.runtimeCredential }, () => {
+                (0, argus_1.complete)(client, { toolName: input.tool_name, output: input.tool_response });
+                return {};
+            });
+        });
     };
     return {
         SessionStart: [{ hooks: [sessionStartHook] }],
+        SubagentStart: [{ hooks: [subagentStart] }],
         PreToolUse: [{ hooks: [preToolUse] }],
         PostToolUse: [{ hooks: [postToolUse] }],
     };
 }
+async function activateSubagent(client, input) {
+    const type = input.agent_type ?? input.subagent_type;
+    if (!input.agent_id || !type || !(0, argus_1.isSecurityConnected)()) {
+        return { principals: actingSubagentPrincipals(input) };
+    }
+    const identity = await (0, argus_1.ensureSubAgentIdentity)(client, {
+        harness: HARNESS,
+        sessionId: input.session_id,
+        subAgentType: type,
+        perSpawnId: input.agent_id,
+        allowEnrollment: false,
+        emitActivity: false,
+    }).catch(() => undefined);
+    if (!identity?.runtimeCredential)
+        return { principals: actingSubagentPrincipals(input) };
+    return {
+        runtimeCredential: identity.runtimeCredential,
+        principals: {
+            subAgentClientId: identity.subject,
+            subAgentType: type,
+            perSpawnId: input.agent_id,
+            sessionId: input.session_id,
+        },
+    };
+}
+function actingSubagentPrincipals(input) {
+    const type = input.agent_type;
+    if (!input.agent_id || !type)
+        return undefined;
+    const credential = input.session_id
+        ? (0, argus_1.loadSubAgentDynamicCredentials)(HARNESS, input.session_id, type)
+        : (0, argus_1.loadSubAgentDynamicCredentials)(HARNESS, type);
+    if (!credential)
+        return undefined;
+    return {
+        subAgentClientId: credential.clientId,
+        subAgentType: type,
+        perSpawnId: input.agent_id,
+        sessionId: input.session_id,
+    };
+}
 /**
  * Build a `canUseTool` callback gated through Ory. Returns `{ behavior: "deny" }` when the
  * tool is hard-denied, otherwise `{ behavior: "allow" }`.
@@ -110,7 +143,10 @@ function createOryHooks(options = {}) {
 function oryCanUseTool(options = {}) {
     const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
     const canBlock = options.canBlock ?? true;
-    const ensureSession = lazySession(client, options.projectUrl);
+    const ensureSession = (0, argus_1.createSessionStarter)(client, {
+        harness: HARNESS,
+        projectUrl: options.projectUrl,
+    });
     return async (toolName, input) => {
         await ensureSession();
         const result = await (0, argus_1.gate)(client, {

package/dist/types.d.ts

@@ -20,6 +20,10 @@ export interface PreToolUseHookInput {
      */
     subagent_type?: string;
     session_id?: string;
+    /** Present on hooks executing inside a spawned sub-agent. */
+    agent_id?: string;
+    /** Type of the sub-agent currently executing this hook. */
+    agent_type?: string;
     [key: string]: unknown;
 }
 export interface PostToolUseHookInput {
@@ -27,6 +31,10 @@ export interface PostToolUseHookInput {
     tool_name: string;
     tool_input?: unknown;
     tool_response?: unknown;
+    session_id?: string;
+    agent_id?: string;
+    agent_type?: string;
+    subagent_type?: string;
     [key: string]: unknown;
 }
 export interface HookJSONOutput {

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@ory/claude-agent-sdk",
-  "version": "0.14.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.",
+  "version": "1.0.0",
+  "description": "Ory Agent Security for the Anthropic Claude Agent SDK — per-tool authorization, activity auditing, and identity propagation via PreToolUse hooks and canUseTool. Built on @ory/argus.",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
     "provenance": true
   },
+  "reova": {
+    "enabled": true,
+    "endpoint": "https://telemetry.reo.dev/data"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -30,8 +34,8 @@
     "ai"
   ],
   "dependencies": {
-    "reo-census": "^1.2.8",
-    "@ory/argus": "0.14.0"
+    "reova": "^0.7.0",
+    "@ory/argus": "1.0.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",