@ory/claude-code 0.8.1 → 0.9.0

package/README.md

@@ -60,10 +60,11 @@ From any project where you'd like Ory authentication, inside Claude Code:
 4. **Turn on Ory login for the Claude session itself.** *(Optional but recommended.)* Out of the box the plugin only governs your *app*. To also attach an Ory identity to *Claude's* session — so every tool call is attributed to you, not a fallback `session:<id>` subject — opt in to the user-login flow:
 
    ```bash
-   export ORY_USER_LOGIN=1
+   export ORY_USER_LOGIN=true
+   export ORY_OAUTH2_CLIENT_ID=<value printed by `local up`>
    ```
 
-   User login is off by default. With it on, the next Claude session opens an Ory login in your browser; sign in with the same seeded credentials from step 1, and the token is reused on subsequent sessions until it expires. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
+   User login is off by default. Both exports above are printed in the `local up` banner — copy them straight from there. `ORY_OAUTH2_CLIENT_ID` is required whenever `ORY_USER_LOGIN` is on: it identifies the public OAuth2 client the PKCE browser flow exchanges for a token. With both set, the next Claude session opens an Ory login in your browser; sign in with the same seeded credentials from step 1, and the token is reused on subsequent sessions until it expires. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
 
 That's the full Ory DX path. Stop here if you're just evaluating the plugin. Continue to [Agent security](#agent-security) when you're ready to enforce.
 
@@ -105,24 +106,80 @@ Bundled and registered automatically. Exposes the Ory CLI and the Ory Network RE
 
 ## Pointing at a real Ory project
 
-The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project, point the plugin at it. A project URL is enough — the agent identity is created automatically via OAuth2 Dynamic Client Registration on first run:
+The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project, point the plugin at it with a single configure command. **The plugin requires `--oauth2-client-id` whenever `--project-url` is provided** — register the client first (see [Register the user OAuth2 client](#register-the-user-oauth2-client) below), then run:
 
 ```bash
 npx -y -p @ory/claude-code ory-claude configure \
-  --project-url https://<id>.projects.oryapis.com
+  --project-url https://<id>.projects.oryapis.com \
+  --oauth2-client-id <public OAuth2 client id>
 ```
 
-Pass `--api-key ory_pat_...` only if you want to override the auto-registered agent identity with a static personal access token (operator override; rarely needed).
+- **`--project-url`** points the plugin at your project. The **agent identity** (machine credentials for Claude's outgoing Ory API calls) is created automatically on first run via OAuth2 Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) against the project's `/oauth2/register` endpoint — no manual step required for that one.
+- **`--oauth2-client-id`** is required because the **user** PKCE browser flow (triggered by `ORY_USER_LOGIN=true`) cannot self-register — you must register a public OAuth2 client ahead of time and supply its id here. The configure command refuses to save a project URL without it, so you don't end up with a silently-broken setup later. See [Register the user OAuth2 client](#register-the-user-oauth2-client) below for the exact CLI / Console steps.
+- **`--api-key ory_pat_...`** is optional — pass it only if you want to override the auto-registered agent identity with a static personal access token (operator override; rarely needed).
 
-Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine. The same settings can be supplied via environment variables (`ORY_PROJECT_URL`, `ORY_AGENT_API_KEY`) — env vars take precedence over the config file when both are set, which is what most CI / scripted setups want.
+If you only want audit logging (no auth or permission checks), substitute `--audit-only` — the OAuth2 client id is not required in that mode:
+
+```bash
+npx -y -p @ory/claude-code ory-claude configure --audit-only
+```
+
+The same settings can be supplied via environment variables (`ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, `ORY_AGENT_API_KEY`) — env vars take precedence over the config file when both are set, which is what most CI / scripted setups want.
+
+Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine.
 
 Without any configuration the plugin still loads cleanly and runs in **pass-through mode**: skills, slash commands, and audit logging work, but no permission checks run, so nothing is ever blocked. You can stay in pass-through mode indefinitely if you only want the DX features.
 
+### Register the user OAuth2 client
+
+If you plan to turn on `ORY_USER_LOGIN=true` (recommended — it's what attributes every tool call to *you* rather than a fallback `session:<id>` subject), your hosted Ory project needs a **public** OAuth2 client (no client secret) registered ahead of time. The local stack provisions this for you automatically; against a hosted project you have to register it once yourself.
+
+The client must list **all four** loopback ports as redirect URIs:
+
+- `http://127.0.0.1:47823/callback`
+- `http://127.0.0.1:47824/callback`
+- `http://127.0.0.1:47825/callback`
+- `http://127.0.0.1:47826/callback`
+
+The plugin walks the four ports at runtime so the login can survive any one of them being occupied — Ory rejects the callback if the port it lands on isn't on the registered list, so register all four.
+
+Create the client with the [Ory CLI](https://www.ory.com/docs/guides/cli/installation):
+
+```bash
+ory create oauth2-client --project <project-id> \
+  --name "ory-agent-plugin" \
+  --grant-type authorization_code,refresh_token \
+  --response-type code \
+  --scope openid,offline_access \
+  --token-endpoint-auth-method none \
+  --redirect-uri http://127.0.0.1:47823/callback \
+  --redirect-uri http://127.0.0.1:47824/callback \
+  --redirect-uri http://127.0.0.1:47825/callback \
+  --redirect-uri http://127.0.0.1:47826/callback
+```
+
+…or in the [Ory Console](https://console.ory.sh) under *OAuth2* → *Clients* → *Create client* (pick "Public client", set "Authorization Code" + "Refresh Token" grants, scopes `openid offline_access`, paste the four redirect URIs above). Then persist the issued id with the configure command (preferred — survives across sessions):
+
+```bash
+npx -y -p @ory/claude-code ory-claude configure \
+  --project-url https://<id>.projects.oryapis.com \
+  --oauth2-client-id <client-id from the step above>
+```
+
+…or set it in the environment alongside `ORY_USER_LOGIN`:
+
+```bash
+export ORY_USER_LOGIN=true
+export ORY_OAUTH2_CLIENT_ID=<client-id from the step above>
+```
+
+Headless / CI runs that already hold a session token can skip this entirely by setting `ORY_USER_SESSION_TOKEN` instead — no browser flow runs, so no OAuth2 client is needed.
+
 ## Agent security
 
 Once the plugin is pointed at an Ory project (local or hosted), Claude's session and every tool call can be governed by Ory.
 
-- **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is enabled (`ORY_USER_LOGIN=1`, off by default — browser PKCE flow on first session, persisted token thereafter). The Claude process (the **agent**) gets its own OAuth2 identity, self-registered via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run. Sub-agents launched by the `Task` tool each receive their own typed identity.
+- **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is enabled (`ORY_USER_LOGIN=true`, off by default — browser PKCE flow on first session, persisted token thereafter). The Claude process (the **agent**) gets its own OAuth2 identity, self-registered via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run. Sub-agents launched by the `Task` tool each receive their own typed identity.
 - **Authorization.** Before any tool runs, the plugin checks [Ory Permissions](https://www.ory.sh/docs/keto) (Zanzibar-style relations) against the user's subject and blocks the call on `deny`. MCP tool calls additionally get a server-level check.
 - **Audit.** Every decision (allow, deny, fallback) is recorded as a structured trace span: NDJSON file output and/or OTLP/HTTP export to Jaeger, Honeycomb, Grafana, and similar collectors. The user → agent (and agent → subagent) delegation chain is written to Ory as relations so *"agent X acting on behalf of user Y"* stays queryable after tokens expire.
 
@@ -135,11 +192,14 @@ With an Ory project configured, the plugin runs in **observe mode** by default:
 1. **Turn on user login.** It's off by default. In your shell:
 
    ```bash
-   export ORY_USER_LOGIN=1
+   export ORY_USER_LOGIN=true
+   export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>
    ```
 
    The next Claude session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
 
+   `ORY_OAUTH2_CLIENT_ID` is required when `ORY_USER_LOGIN` is on: PKCE needs a public OAuth2 client registered with the four loopback redirect URIs (`http://127.0.0.1:47823..47826/callback`) to exchange the authorization code for a token. The local stack provisions one and prints the export in its `local up` banner; for a hosted Ory project see [Register the user OAuth2 client](#register-the-user-oauth2-client) for the exact CLI / Console steps. Headless / CI runs can skip the browser flow entirely by pre-supplying `ORY_USER_SESSION_TOKEN` instead.
+
 2. **Bootstrap permissions for the built-in tools.** One idempotent command grants the current user `use` on every tool Claude ships with (Read, Write, Bash, …):
 
    ```bash
@@ -168,7 +228,7 @@ With an Ory project configured, the plugin runs in **observe mode** by default:
 
 ```
 npx -y -p @ory/claude-code ory-claude install | uninstall              [--global]
-npx -y -p @ory/claude-code ory-claude configure                         [--project-url <url>] [--api-key <key>] [--audit-only]
+npx -y -p @ory/claude-code ory-claude configure                         [--project-url <url> --oauth2-client-id <id>] [--api-key <key>] [--audit-only]
 npx -y -p @ory/claude-code ory-claude agent <status|unregister>         Manage the agent's OAuth2 identity
 npx -y -p @ory/claude-code ory-claude permissions <status|bootstrap|observe|enforce>
 npx -y -p @ory/claude-code ory-claude local <up|down|status|seed|logs|env|configure|reset>

package/dist/handlers.js

@@ -226,7 +226,21 @@ async function handlePreToolUse(input, client, deps = {}) {
             };
         }
         const namespace = resolveNamespace();
-        const decision = await (0, argus_1.checkAndDecide)(client, { namespace, object: toolName, relation: "use", ...subject }, { spanAttributes: { toolName } });
+        const outcome = await (0, argus_1.gateToolCall)(client, {
+            harness: "claude-code",
+            toolName,
+            check: { namespace, object: toolName, relation: "use", ...subject },
+            spanAttributes: { toolName },
+        });
+        // Interactive tools (AskUserQuestion, ExitPlanMode, TodoWrite, …)
+        // surface UI to the user and aren't external-system tool executions.
+        // gateToolCall has already recorded the `user.interaction` audit span;
+        // we pass through with no `tool.invoke`/`tool.block` and let the
+        // harness deliver the prompt to the user.
+        if (outcome.kind === "interactive") {
+            return {};
+        }
+        const decision = outcome;
         if (decision.kind === "fail_open") {
             return handlePermissionError(decision.error, toolName, client);
         }
@@ -377,6 +391,15 @@ async function handlePermissionRequest(input, client) {
     if ((0, argus_1.resolveConfig)().auditOnly) {
         return permissionRequestFallback("Audit-only mode — deferring to user");
     }
+    // Interactive tools: the harness is about to surface UI to the user
+    // (AskUserQuestion, ExitPlanMode, TodoWrite, …). Trace and fall through
+    // — Ory shouldn't pre-answer a prompt that's meant for the human.
+    if ((0, argus_1.isInteractiveTool)("claude-code", toolName)) {
+        client.tracer.record("user.interaction", "ok", {
+            attributes: { harness: "claude-code", toolName, kind: "permission-request" },
+        });
+        return permissionRequestFallback("Interactive tool — 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);
@@ -401,7 +424,16 @@ async function handlePermissionRequest(input, client) {
                 : "Ory MCP server permission granted");
         }
         const namespace = resolveNamespace();
-        const decision = await (0, argus_1.checkAndDecide)(client, { namespace, object: toolName, relation: "use", ...subject }, { spanAttributes: { toolName } });
+        const outcome = await (0, argus_1.gateToolCall)(client, {
+            harness: "claude-code",
+            toolName,
+            check: { namespace, object: toolName, relation: "use", ...subject },
+            spanAttributes: { toolName },
+        });
+        if (outcome.kind === "interactive") {
+            return permissionRequestFallback("Interactive tool — deferring to user");
+        }
+        const decision = outcome;
         if (decision.kind === "fail_open") {
             const code = decision.error.code;
             const fallbackReason = code === "network_error" || code === "rate_limited"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/claude-code",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Ory plugin for Claude Code: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://github.com/ory/claude-plugins/tree/master/plugins/ory-agent-plugin",
@@ -75,7 +75,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@ory/argus": "0.8.1"
+    "@ory/argus": "0.9.0"
   },
   "engines": {
     "node": ">=22"