@ory/claude-code 0.1.0

package/dist/handlers.js

@@ -0,0 +1,525 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleHookEvent = handleHookEvent;
+const argus_1 = require("@ory/argus");
+/**
+ * Route a Claude Code hook event to the appropriate Ory integration.
+ */
+async function handleHookEvent(input, client, deps = {}) {
+    const event = input.hook_event_name;
+    client.logger.debug("hook.received", {
+        event,
+        sessionId: input.session_id,
+        toolName: input.tool_name,
+    });
+    // Set trace context so all spans within this hook invocation correlate
+    client.tracer.setContext({
+        traceId: (0, argus_1.deriveTraceId)(input.session_id),
+        sessionId: input.session_id,
+    });
+    try {
+        switch (event) {
+            case "SessionStart":
+                return await handleSessionStart(input, client, deps);
+            case "PreToolUse":
+                return await handlePreToolUse(input, client, deps);
+            case "PostToolUse":
+                return await handlePostToolUse(input, client);
+            case "PostToolUseFailure":
+                return await handlePostToolUseFailure(input, client);
+            case "PermissionRequest":
+                return await handlePermissionRequest(input, client);
+            case "UserPromptSubmit":
+                return await handleUserPromptSubmit(input, client);
+            case "SubagentStart":
+                return await handleSubagentStart(input, client, deps);
+            case "SubagentStop":
+                return await handleSubagentStop(input, client);
+            case "SessionEnd":
+                return await handleSessionEnd(input, client);
+            default:
+                client.logger.debug("hook.passthrough", { event });
+                client.tracer.record("hook.passthrough", "skipped", {
+                    attributes: { event },
+                });
+                return { continue: true };
+        }
+    }
+    finally {
+        client.tracer.clearContext();
+    }
+}
+// ─── SessionStart ───────────────────────────────────────────────────
+async function handleSessionStart(input, client, deps) {
+    client.logger.info("lifecycle.session_start", {
+        sessionId: input.session_id,
+        model: input.model,
+        source: input.source,
+        cwd: input.cwd,
+    });
+    client.tracer.record("session.start", "ok", {
+        attributes: { model: input.model, source: input.source },
+    });
+    // Run the user auth gate (interactive PKCE on first session, refresh
+    // when needed). When ORY_AUTH_GATE is unset this is a no-op and we
+    // fall through to the legacy verify path below.
+    const userGate = deps.authGate ?? argus_1.ensureUserAuthenticated;
+    const decision = await userGate(client, {
+        binName: "ory-claude",
+        harness: "claude-code",
+        allowBlock: true,
+    });
+    // Resolve the agent identity (machine credentials) regardless of how
+    // user auth went — it never blocks and attaches the agent's bearer
+    // token to outgoing Ory API calls so the audit trail records who
+    // acted on the user's behalf.
+    const agentGate = deps.agentGate ?? argus_1.ensureAgentIdentity;
+    await agentGate(client, { projectUrl: (0, argus_1.resolveConfig)().projectUrl, harness: "claude-code" });
+    // Record the user→agent delegation so the audit trail captures that
+    // this user authorized this agent for this session. Best-effort:
+    // requires both principals to be populated, and any failure is logged
+    // and swallowed (fail-open — delegation tracking is for audit, not
+    // enforcement).
+    await recordUserDelegatesAgent(client);
+    if (!decision.proceed) {
+        return { decision: "block", reason: decision.reason };
+    }
+    if (decision.mode !== "disabled") {
+        return {};
+    }
+    const resolved = (0, argus_1.resolveConfig)();
+    if (resolved.auditOnly) {
+        client.logger.info("config.audit_only", {
+            message: "Audit-only mode enabled. Auth and permission checks are disabled.",
+        });
+        return {};
+    }
+    if (!resolved.projectUrl) {
+        client.logger.warn("config.not_configured", {
+            message: "Ory plugin is not configured. Auth and permission checks are disabled. " +
+                "Run 'npx ory-claude configure' to connect to an Ory project.",
+        });
+        return {};
+    }
+    // Try session token first, then OAuth2 token
+    const sessionToken = process.env.ORY_SESSION_TOKEN;
+    const oauth2Token = process.env.ORY_OAUTH2_TOKEN;
+    if (sessionToken) {
+        await verifySessionToken(sessionToken, client);
+        return {};
+    }
+    if (oauth2Token) {
+        await verifyOAuth2Token(oauth2Token, client);
+        return {};
+    }
+    client.logger.warn("session.no_credentials", {
+        message: "Neither ORY_SESSION_TOKEN nor ORY_OAUTH2_TOKEN is set. " +
+            "Skipping authentication.",
+    });
+    return {};
+}
+async function verifySessionToken(token, client) {
+    try {
+        const session = await client.verifySession(token);
+        if (!session.active) {
+            client.logger.warn("session.inactive", {
+                message: "Ory session is not active. Re-authenticate to enable auth checks.",
+            });
+        }
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("session.verify_failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+async function verifyOAuth2Token(token, client) {
+    try {
+        const tokenInfo = await client.introspectToken(token);
+        if (!tokenInfo.active) {
+            client.logger.warn("oauth2.token_inactive", {
+                message: "Ory OAuth2 token is not active. Obtain a new token to enable auth checks.",
+            });
+            return;
+        }
+        client.logger.info("oauth2.session_authenticated", {
+            clientId: tokenInfo.clientId,
+            subject: tokenInfo.subject,
+            scope: tokenInfo.scope,
+        });
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("oauth2.introspect_failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+// ─── PreToolUse ─────────────────────────────────────────────────────
+async function handlePreToolUse(input, client, deps = {}) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.pre_tool_use", {
+        sessionId: input.session_id,
+        toolName,
+        toolInput: input.tool_input,
+    });
+    const inputSummary = (0, argus_1.summarizeToolInput)(toolName, input.tool_input);
+    // If the agent is invoking a sub-agent (Claude Code's "Task"/"Agent"
+    // tool with a `subagent_type`), resolve a distinct OAuth2 identity for
+    // that sub-agent via DCR and record the agent→sub-agent delegation
+    // tuple. Best-effort — failures here never block the actual tool call.
+    await maybeRegisterSubAgent(toolName, input.tool_input, client, deps);
+    // In audit-only mode, log the invocation but skip permission checks
+    if ((0, argus_1.resolveConfig)().auditOnly) {
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { toolName, ...inputSummary },
+        });
+        return {};
+    }
+    const subject = (0, argus_1.resolveUserSubject)(client, `session:${input.session_id}`);
+    const subjectId = (0, argus_1.subjectLabel)(subject);
+    const mcpTool = (0, argus_1.parseClaudeCodeMcpTool)(toolName);
+    try {
+        if (mcpTool) {
+            const mcpResult = await (0, argus_1.checkMcpPermission)(client, mcpTool, {
+                subject,
+                spanAttributes: { toolName },
+            });
+            if (!mcpResult.allowed) {
+                client.tracer.record("tool.block", "denied", {
+                    attributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary, ...(0, argus_1.alertAttributes)(true) },
+                });
+                return {
+                    decision: "block",
+                    reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }),
+                };
+            }
+            client.tracer.record("tool.invoke", "ok", {
+                attributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary },
+            });
+            return {};
+        }
+        const namespace = resolveNamespace();
+        const result = await client.checkPermission({
+            namespace,
+            object: toolName,
+            relation: "use",
+            ...subject,
+        }, { spanAttributes: { toolName } });
+        if (!result.allowed) {
+            client.tracer.record("tool.block", "denied", {
+                attributes: { toolName, ...inputSummary, allowed: result.allowed, ...(0, argus_1.alertAttributes)(true) },
+            });
+            return {
+                decision: "block",
+                reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }),
+            };
+        }
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { toolName, ...inputSummary, allowed: result.allowed },
+        });
+        return {};
+    }
+    catch (err) {
+        return handlePermissionError(err, toolName, client);
+    }
+}
+// ─── PostToolUse ────────────────────────────────────────────────────
+async function handlePostToolUse(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.post_tool_use", {
+        sessionId: input.session_id,
+        toolName,
+        toolResponse: input.tool_response,
+    });
+    client.tracer.record("tool.complete", "ok", {
+        attributes: {
+            toolName,
+            toolUseId: input.tool_use_id,
+            ...(0, argus_1.summarizeToolInput)(toolName, input.tool_input),
+            ...(0, argus_1.summarizeToolOutput)(toolName, input.tool_response),
+        },
+    });
+    return {};
+}
+// ─── PostToolUseFailure ─────────────────────────────────────────────
+async function handlePostToolUseFailure(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.post_tool_use_failure", {
+        sessionId: input.session_id,
+        toolName,
+        toolUseId: input.tool_use_id,
+    });
+    client.tracer.record("tool.fail", "error", {
+        attributes: {
+            toolName,
+            toolUseId: input.tool_use_id,
+            toolError: typeof input.tool_error === "string"
+                ? input.tool_error.slice(0, 500)
+                : input.tool_error
+                    ? "[object]"
+                    : undefined,
+            ...(0, argus_1.summarizeToolInput)(toolName, input.tool_input),
+        },
+    });
+    return {};
+}
+// ─── UserPromptSubmit ──────────────────────────────────────────────
+async function handleUserPromptSubmit(input, client) {
+    client.logger.info("lifecycle.user_prompt_submit", {
+        sessionId: input.session_id,
+        promptLen: input.prompt?.length,
+    });
+    client.tracer.record("user.prompt", "ok", {
+        attributes: { promptLen: input.prompt?.length },
+    });
+    return {};
+}
+// ─── SubagentStart ─────────────────────────────────────────────────
+//
+// Dedicated sub-agent invocation event. Replaces the legacy path of
+// sniffing the `Task`/`Agent` tool name in PreToolUse — that still runs
+// as a fallback for older Claude Code versions, but registerSubAgent
+// is idempotent so duplicate registration is harmless.
+async function handleSubagentStart(input, client, deps) {
+    const subAgentType = input.subagent_type ?? input.agent_type;
+    const agentId = input.agent_id;
+    client.logger.info("lifecycle.subagent_start", {
+        sessionId: input.session_id,
+        subAgentType,
+        agentId,
+    });
+    client.tracer.record("subagent.start", "ok", {
+        attributes: { subAgentType, agentId },
+    });
+    if (subAgentType) {
+        await registerSubAgent(subAgentType, client, deps);
+    }
+    else {
+        client.logger.debug("subagent_start.no_type", {
+            message: "SubagentStart event without subagent_type — skipping DCR.",
+        });
+    }
+    return {};
+}
+// ─── SubagentStop ──────────────────────────────────────────────────
+async function handleSubagentStop(input, client) {
+    client.logger.info("lifecycle.subagent_stop", {
+        sessionId: input.session_id,
+        subAgentType: input.subagent_type ?? input.agent_type,
+        agentId: input.agent_id,
+    });
+    client.tracer.record("subagent.stop", "ok", {
+        attributes: {
+            subAgentType: input.subagent_type ?? input.agent_type,
+            agentId: input.agent_id,
+            responseLen: input.subagent_response?.length,
+        },
+    });
+    return {};
+}
+// ─── SessionEnd ────────────────────────────────────────────────────
+async function handleSessionEnd(input, client) {
+    client.logger.info("lifecycle.session_end", {
+        sessionId: input.session_id,
+        reason: input.reason,
+    });
+    client.tracer.record("session.end", "ok", {
+        attributes: { reason: input.reason },
+    });
+    return {};
+}
+// ─── PermissionRequest ──────────────────────────────────────────────
+async function handlePermissionRequest(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.permission_request", {
+        sessionId: input.session_id,
+        toolName,
+        toolInput: input.tool_input,
+    });
+    // Audit-only mode: omit `decision` so Claude falls through to its normal
+    // user-permission prompt.
+    if ((0, argus_1.resolveConfig)().auditOnly) {
+        return permissionRequestFallback("Audit-only mode — deferring to user");
+    }
+    const subject = (0, argus_1.resolveUserSubject)(client, `session:${input.session_id}`);
+    const subjectId = (0, argus_1.subjectLabel)(subject);
+    const mcpTool = (0, argus_1.parseClaudeCodeMcpTool)(toolName);
+    try {
+        if (mcpTool) {
+            const mcpResult = await (0, argus_1.checkMcpPermission)(client, mcpTool, {
+                subject,
+                spanAttributes: { toolName },
+            });
+            return permissionRequestDecision(mcpResult.allowed ? "allow" : "deny", mcpResult.allowed
+                ? "Ory MCP server permission granted"
+                : (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }));
+        }
+        const namespace = resolveNamespace();
+        const result = await client.checkPermission({
+            namespace,
+            object: toolName,
+            relation: "use",
+            ...subject,
+        }, { spanAttributes: { toolName } });
+        return permissionRequestDecision(result.allowed ? "allow" : "deny", result.allowed
+            ? "Ory permission granted"
+            : (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }));
+    }
+    catch (err) {
+        const oryErr = err;
+        const fallbackReason = oryErr.code === "network_error" || oryErr.code === "rate_limited"
+            ? `Ory unavailable (${oryErr.code}), falling back to user prompt`
+            : `Ory permission check failed: ${oryErr.message}`;
+        return permissionRequestFallback(fallbackReason);
+    }
+}
+function permissionRequestDecision(behavior, reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: { behavior },
+            message: reason,
+        },
+    };
+}
+function permissionRequestFallback(reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            message: reason,
+        },
+    };
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+/**
+ * Write the user→agent delegation tuple. Idempotent and fail-open:
+ * requires both principal subjects to be populated; any error (including
+ * unconfigured projectUrl, which manifests as a network_error) is logged
+ * and swallowed. The actual permission enforcement is unchanged — this
+ * tuple is purely audit-trail data.
+ */
+async function recordUserDelegatesAgent(client) {
+    const user = client.userPrincipal.subject;
+    const agent = client.agentPrincipal.subject;
+    if (!user || !agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "missing principal",
+            hasUser: !!user,
+            hasAgent: !!agent,
+        });
+        return;
+    }
+    try {
+        await client.createRelationship({
+            namespace: resolveNamespace(),
+            object: `agent:${agent}`,
+            relation: "delegate",
+            subjectId: `user:${user}`,
+        }, { spanAttributes: { delegation: "user-to-agent" } });
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("delegation.user_to_agent.failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+/**
+ * Register an OAuth2 identity for a sub-agent and write the
+ * `agent → subagent` delegation tuple. Fail-open and idempotent:
+ * `createRelationship` absorbs 409s, so multiple call paths
+ * (SubagentStart event + Task-tool fallback) won't duplicate state.
+ */
+async function registerSubAgent(subAgentType, client, deps) {
+    const subAgentGate = deps.subAgentGate ?? argus_1.ensureSubAgentIdentity;
+    let identity;
+    try {
+        identity = await subAgentGate(client, {
+            subAgentType,
+            projectUrl: (0, argus_1.resolveConfig)().projectUrl,
+            harness: "claude-code",
+        });
+    }
+    catch (err) {
+        client.logger.warn("subagent.identity.failed", {
+            subAgentType,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    if (identity.kind !== "dynamic" || !identity.subject)
+        return;
+    const agent = client.agentPrincipal.subject;
+    if (!agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "agent principal not populated",
+            subAgentType,
+        });
+        return;
+    }
+    try {
+        await client.createRelationship({
+            namespace: resolveNamespace(),
+            object: `subagent:${identity.subject}`,
+            relation: "delegate",
+            subjectId: `agent:${agent}`,
+        }, { spanAttributes: { delegation: "agent-to-subagent", subAgentType } });
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("delegation.agent_to_subagent.failed", {
+            subAgentType,
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+/**
+ * Legacy fallback for older Claude Code versions that don't fire
+ * `SubagentStart`: the sub-agent invocation appears as a `Task`/`Agent`
+ * tool call in PreToolUse with a `subagent_type` field on tool_input.
+ * `SubagentStart` is the preferred path; this is a no-op when both fire.
+ */
+async function maybeRegisterSubAgent(toolName, toolInput, client, deps) {
+    if (toolName !== "Task" && toolName !== "Agent")
+        return;
+    const subAgentType = typeof toolInput === "object"
+        && toolInput !== null
+        && typeof toolInput.subagent_type === "string"
+        ? toolInput.subagent_type
+        : undefined;
+    if (!subAgentType)
+        return;
+    await registerSubAgent(subAgentType, client, deps);
+}
+function handlePermissionError(oryErr, toolName, client) {
+    if (oryErr.code === "network_error") {
+        client.logger.warn("permission.network_error", {
+            toolName,
+            message: "Ory unreachable, failing open",
+        });
+        return {};
+    }
+    if (oryErr.code === "rate_limited") {
+        client.logger.warn("permission.rate_limited", {
+            toolName,
+            message: "Ory rate limited, failing open",
+        });
+        return {};
+    }
+    // For other errors, also fail open but log prominently
+    client.logger.error("permission.check.error", {
+        toolName,
+        code: oryErr.code,
+        message: oryErr.message,
+    });
+    return {};
+}

package/dist/hook.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook entry point.
+ * This script is invoked by Claude Code for each hook event.
+ * Input: JSON on stdin
+ * Output: JSON on stdout
+ * Exit code 2 = block the action
+ */
+export {};

package/dist/hook.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Claude Code hook entry point.
+ * This script is invoked by Claude Code for each hook event.
+ * Input: JSON on stdin
+ * Output: JSON on stdout
+ * Exit code 2 = block the action
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const argus_1 = require("@ory/argus");
+const handlers_js_1 = require("./handlers.js");
+/**
+ * Read all of stdin as a string.
+ *
+ * Uses event listeners instead of `for await` so that we don't depend on the
+ * parent process closing stdin (sending EOF). If no EOF arrives, we resolve
+ * after a short idle gap once data has been received.
+ */
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let resolved = false;
+        function done() {
+            if (!resolved) {
+                resolved = true;
+                resolve(Buffer.concat(chunks).toString("utf-8"));
+            }
+        }
+        process.stdin.on("data", (chunk) => {
+            chunks.push(chunk);
+            // Reset idle timer on every chunk. Once data stops arriving for 100 ms
+            // we assume the full payload has been delivered.
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(done, 100);
+        });
+        process.stdin.on("end", done);
+        process.stdin.on("error", (err) => {
+            if (!resolved) {
+                resolved = true;
+                reject(err);
+            }
+        });
+        let idleTimer;
+    });
+}
+async function main() {
+    const client = argus_1.OryAgentClient.fromEnv("claude-code");
+    const raw = await readStdin();
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        client.logger.error("hook.stdin.parse_failed", { raw: raw.slice(0, 200) });
+        await client.tracer.shutdown();
+        process.exit(0); // Don't block on parse errors
+    }
+    const output = await (0, handlers_js_1.handleHookEvent)(input, client);
+    if (output.decision === "block") {
+        process.stdout.write(JSON.stringify(output));
+        await client.tracer.shutdown();
+        process.exit(2);
+    }
+    if (output.hookSpecificOutput ||
+        output.updatedInput ||
+        output.decision === "approve") {
+        process.stdout.write(JSON.stringify(output));
+    }
+    await client.tracer.shutdown();
+    process.exit(0);
+}
+main().catch((err) => {
+    process.stderr.write(`[ory-agent] fatal: ${err}\n`);
+    process.exit(0); // Fail open
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { handleHookEvent } from "./handlers.js";
+export { generateSettings } from "./settings.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSettings = exports.handleHookEvent = void 0;
+var handlers_js_1 = require("./handlers.js");
+Object.defineProperty(exports, "handleHookEvent", { enumerable: true, get: function () { return handlers_js_1.handleHookEvent; } });
+var settings_js_1 = require("./settings.js");
+Object.defineProperty(exports, "generateSettings", { enumerable: true, get: function () { return settings_js_1.generateSettings; } });

package/dist/settings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generate the .claude/settings.local.json that configures Ory hooks.
+ */
+export declare function generateSettings(hookScriptPath: string): object;
+/**
+ * Generate settings assuming the plugin is installed via npm/pnpm.
+ */
+export declare function generateInstalledSettings(): object;
+/**
+ * Generate settings pointing to a local dev build.
+ */
+export declare function generateDevSettings(packageDir: string): object;