@ory/argus 0.8.1 → 0.9.0

package/assets/skills/ory-build-agent/SKILL.md

@@ -86,7 +86,7 @@ import {
 const client = OryAgentClient.fromEnv("my-agent");
 const { projectUrl } = resolveConfig();
 
-// 1. User gate — interactive PKCE when ORY_USER_LOGIN=1, no-op otherwise.
+// 1. User gate — interactive PKCE when ORY_USER_LOGIN=true, no-op otherwise.
 const userDecision = await ensureUserAuthenticated(client, {
   binName: "my-agent",
   harness: "my-agent",
@@ -409,7 +409,7 @@ PKCE flow, permission tuples, and trace spans are all visible:
 1. {{REF_LOCAL_UP}} — brings up Kratos / Keto / Hydra on `localhost:4000`
    and seeds a demo user. The banner prints the email + password.
 2. Export the env vars the launcher writes (`ORY_PROJECT_URL`,
-   `ORY_USER_LOGIN=1`, `ORY_OAUTH2_CLIENT_ID`, optional
+   `ORY_USER_LOGIN=true`, `ORY_OAUTH2_CLIENT_ID`, optional
    `ORY_AGENT_TRACE_FILE` for an NDJSON span log).
 3. Start your agent. Confirm the browser opens for PKCE login.
 4. Invoke a gated tool and `tail -f $ORY_AGENT_TRACE_FILE | jq .` — you

package/assets/skills/ory-e2b-sandbox/SKILL.md

@@ -66,7 +66,7 @@ export const template = Template()
   // Sandbox runtime defaults. Per-tenant secrets (project URL, tokens, client
   // IDs) MUST be passed at Sandbox.create() time, never baked into the image.
   .setEnvs({
-    ORY_USER_LOGIN: "1",
+    ORY_USER_LOGIN: "true",
     ORY_PERMISSION_MODE: "observe",
     ORY_PERMISSION_NAMESPACE: "AgentTools",
     ORY_AGENT_DEBUG: "true",

package/assets/skills/permissions-onboarding/SKILL.md

@@ -41,9 +41,11 @@ What you want to see:
 If any of those are wrong, fix them before continuing:
 
 ```sh
-{{NPX}} configure --project-url <URL> --api-key <KEY>
+{{NPX}} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]
 ```
 
+`--oauth2-client-id` is the public OAuth2 client registered in your Ory project (required when `ORY_USER_LOGIN=true`; see the *Register the user OAuth2 client* section of the plugin README).
+
 ## Step 2: Look at the current permission posture
 
 ```sh
@@ -94,7 +96,7 @@ Two common failure modes:
 1. **No user identity cached.** Bootstrap needs to know which subject
    to grant tuples to. If user login has never run (no PKCE login,
    no `ORY_USER_SUBJECT_ID`), the command refuses. Run the harness once
-   with `ORY_USER_LOGIN=1` to cache a user token, or set
+   with `ORY_USER_LOGIN=true` to cache a user token, or set
    `ORY_USER_SUBJECT_ID=<id>` to target a known subject.
 2. **Credentials lack write scope on the permission namespace.** The
    command prints the full tuple list so you can apply them manually

package/dist/agent-auth.js

@@ -290,7 +290,7 @@ async function resolveAgentCredentials(options = {}) {
     }
     return {
         kind: "none",
-        reason: "No agent credentials configured. Run with a user session (ORY_USER_LOGIN=1) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
+        reason: "No agent credentials configured. Run with a user session (ORY_USER_LOGIN=true) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
         warnings,
     };
 }

package/dist/cli.d.ts

@@ -1,8 +1,16 @@
 /**
  * Shared `configure` command implementation for all plugin CLIs.
  *
- * Parses --project-url and --api-key from args. If neither is provided,
- * shows the current configuration. Otherwise saves the provided values.
+ * Parses --project-url, --api-key, and --oauth2-client-id from args.
+ * If none is provided, shows the current configuration. Otherwise saves
+ * the provided values.
+ *
+ * When `--project-url` is provided, requires the OAuth2 client id to be
+ * resolvable from one of: the `--oauth2-client-id` flag, the
+ * `ORY_OAUTH2_CLIENT_ID` env var, or an already-persisted value in the
+ * shared config. The PKCE browser flow that runs when
+ * `ORY_USER_LOGIN=true` can't self-register that client — surfacing the
+ * requirement here keeps users from a silently-broken setup later.
  */
 export declare function runConfigureCommand(binName: string, args: string[]): void;
 /**

package/dist/cli.js

@@ -54,12 +54,21 @@ const tracer_js_1 = require("./tracer.js");
 /**
  * Shared `configure` command implementation for all plugin CLIs.
  *
- * Parses --project-url and --api-key from args. If neither is provided,
- * shows the current configuration. Otherwise saves the provided values.
+ * Parses --project-url, --api-key, and --oauth2-client-id from args.
+ * If none is provided, shows the current configuration. Otherwise saves
+ * the provided values.
+ *
+ * When `--project-url` is provided, requires the OAuth2 client id to be
+ * resolvable from one of: the `--oauth2-client-id` flag, the
+ * `ORY_OAUTH2_CLIENT_ID` env var, or an already-persisted value in the
+ * shared config. The PKCE browser flow that runs when
+ * `ORY_USER_LOGIN=true` can't self-register that client — surfacing the
+ * requirement here keeps users from a silently-broken setup later.
  */
 function runConfigureCommand(binName, args) {
     let projectUrl;
     let apiKey;
+    let oauth2ClientId;
     let auditOnly = false;
     for (let i = 0; i < args.length; i++) {
         switch (args[i]) {
@@ -69,30 +78,35 @@ function runConfigureCommand(binName, args) {
             case "--api-key":
                 apiKey = args[++i];
                 break;
+            case "--oauth2-client-id":
+                oauth2ClientId = args[++i];
+                break;
             case "--audit-only":
                 auditOnly = true;
                 break;
         }
     }
-    if (!projectUrl && !apiKey && !auditOnly) {
+    if (!projectUrl && !apiKey && !oauth2ClientId && !auditOnly) {
         const resolved = (0, config_js_1.resolveConfig)();
         const configPath = (0, config_js_1.getConfigPath)();
         console.log("Ory Plugin Configuration");
         console.log("========================");
         console.log("");
-        console.log(`Config file: ${configPath}`);
-        console.log(`Project URL: ${resolved.projectUrl ?? "(not set)"} [${resolved.projectUrlSource}]`);
-        console.log(`API Key:     ${resolved.apiKey ? "(set)" : "(not set)"} [${resolved.apiKeySource}]`);
-        console.log(`Audit Only:  ${resolved.auditOnly ? "yes" : "no"}`);
+        console.log(`Config file:      ${configPath}`);
+        console.log(`Project URL:      ${resolved.projectUrl ?? "(not set)"} [${resolved.projectUrlSource}]`);
+        console.log(`API Key:          ${resolved.apiKey ? "(set)" : "(not set)"} [${resolved.apiKeySource}]`);
+        console.log(`OAuth2 Client ID: ${resolved.oauth2ClientId ?? "(not set)"} [${resolved.oauth2ClientIdSource}]`);
+        console.log(`Audit Only:       ${resolved.auditOnly ? "yes" : "no"}`);
         console.log("");
         console.log("To configure:");
-        console.log(`  npx ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.log(`  npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         console.log("");
         console.log("To enable audit logging only (no auth or permission checks):");
         console.log(`  npx ${binName} configure --audit-only`);
         console.log("");
         console.log("Or set environment variables:");
         console.log("  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
+        console.log("  export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
         console.log("  export ORY_AGENT_API_KEY=ory_pat_...");
         return;
     }
@@ -106,11 +120,49 @@ function runConfigureCommand(binName, args) {
         console.log("This configuration is shared across all Ory agent plugins.");
         return;
     }
+    // When --project-url is provided we need a usable OAuth2 client id for
+    // the user PKCE flow — block the configure with a clear error if none
+    // is reachable from the flag, env, or already-persisted config.
+    if (projectUrl) {
+        const persisted = (0, config_js_1.loadConfig)().oauth2ClientId;
+        const envClientId = process.env.ORY_OAUTH2_CLIENT_ID;
+        const resolved = oauth2ClientId ?? envClientId ?? persisted;
+        if (!resolved) {
+            console.error("Error: --project-url requires an OAuth2 client id for the user PKCE flow.\n" +
+                "\n" +
+                "Provide one with --oauth2-client-id <id>, or set ORY_OAUTH2_CLIENT_ID in your\n" +
+                "environment. The client must be a public OAuth2 client (no client secret,\n" +
+                "token_endpoint_auth_method=none) registered in your Ory project with all four\n" +
+                "loopback redirect URIs:\n" +
+                "  http://127.0.0.1:47823/callback\n" +
+                "  http://127.0.0.1:47824/callback\n" +
+                "  http://127.0.0.1:47825/callback\n" +
+                "  http://127.0.0.1:47826/callback\n" +
+                "\n" +
+                "Create it with:\n" +
+                "  ory create oauth2-client --project <project-id> \\\n" +
+                "    --name \"ory-agent-plugin\" \\\n" +
+                "    --grant-type authorization_code,refresh_token \\\n" +
+                "    --response-type code \\\n" +
+                "    --scope openid,offline_access \\\n" +
+                "    --token-endpoint-auth-method none \\\n" +
+                "    --redirect-uri http://127.0.0.1:47823/callback \\\n" +
+                "    --redirect-uri http://127.0.0.1:47824/callback \\\n" +
+                "    --redirect-uri http://127.0.0.1:47825/callback \\\n" +
+                "    --redirect-uri http://127.0.0.1:47826/callback\n" +
+                "\n" +
+                "If you only want audit logging (no auth or permission checks), use:\n" +
+                `  npx ${binName} configure --audit-only`);
+            process.exit(1);
+        }
+    }
     const update = {};
     if (projectUrl)
         update.projectUrl = projectUrl;
     if (apiKey)
         update.apiKey = apiKey;
+    if (oauth2ClientId)
+        update.oauth2ClientId = oauth2ClientId;
     // Clear auditOnly when configuring with a project URL
     update.auditOnly = false;
     (0, config_js_1.saveConfig)(update);
@@ -120,9 +172,11 @@ function runConfigureCommand(binName, args) {
         console.log(`  Project URL: ${projectUrl}`);
     if (apiKey)
         console.log(`  API Key: (set)`);
+    if (oauth2ClientId)
+        console.log(`  OAuth2 Client ID: ${oauth2ClientId}`);
     console.log("");
     console.log("This configuration is shared across all Ory agent plugins.");
-    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY) take precedence when set.");
+    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY, ORY_OAUTH2_CLIENT_ID) take precedence when set.");
 }
 /**
  * Print the "Configuration:" block showing Ory project URL and API key status.
@@ -136,6 +190,7 @@ function printOryConfig() {
     console.log(`  Mode:            ${resolved.auditOnly ? "audit-only" : "full"}`);
     console.log(`  Project URL:     ${resolved.projectUrl ?? "NOT SET"} [source: ${resolved.projectUrlSource}]`);
     console.log(`  API Key:         ${resolved.apiKey ? "(set)" : "NOT SET"} [source: ${resolved.apiKeySource}]`);
+    console.log(`  OAuth2 Client:   ${resolved.oauth2ClientId ?? "NOT SET"} [source: ${resolved.oauth2ClientIdSource}]`);
     console.log(`  Permission mode: ${resolved.permissionMode} [source: ${resolved.permissionModeSource}]`);
     console.log(`  Namespace:       ${namespace}`);
 }
@@ -153,6 +208,7 @@ function printEnvironment() {
             false,
         ],
         ["ORY_AGENT_CLIENT_ID", process.env.ORY_AGENT_CLIENT_ID, false],
+        ["ORY_OAUTH2_CLIENT_ID", process.env.ORY_OAUTH2_CLIENT_ID, false],
         [
             "ORY_USER_SESSION_TOKEN",
             process.env.ORY_USER_SESSION_TOKEN ? "(set)" : undefined,
@@ -210,10 +266,13 @@ function printEnvHelp(binName) {
     console.log("Configure your Ory credentials (one of these methods):");
     console.log("");
     console.log("  Option 1 — Save to config file (persists across sessions):");
-    console.log(`    npx ${binName} configure --project-url https://your-project.projects.oryapis.com --api-key ory_pat_...`);
+    console.log(`    npx ${binName} configure --project-url https://your-project.projects.oryapis.com \\`);
+    console.log("                              --oauth2-client-id <public OAuth2 client id> \\");
+    console.log("                              --api-key ory_pat_...");
     console.log("");
     console.log("  Option 2 — Set environment variables:");
     console.log("    export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
+    console.log("    export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
     console.log("    export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
     console.log("If neither is set when a session starts, the agent will prompt for configuration.");
@@ -371,7 +430,7 @@ async function interactiveConfigPrompt(binName) {
         "Run one of the following commands in another terminal:",
         "",
         "  Connect to Ory (enables auth & permission checks):",
-        `    npx ${binName} configure --project-url <URL> --api-key <KEY>`,
+        `    npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`,
         "",
         "  Or, enable audit logging only (no auth or permission checks):",
         `    npx ${binName} configure --audit-only`,

package/dist/config.d.ts

@@ -75,6 +75,16 @@ export type PermissionMode = "observe" | "enforce";
 export interface OryPluginConfig {
     projectUrl?: string;
     apiKey?: string;
+    /**
+     * Public OAuth2 client id used by the user PKCE browser flow when
+     * `ORY_USER_LOGIN` is on. The client must be registered ahead of time
+     * in the Ory project with all four loopback redirect URIs
+     * (`http://127.0.0.1:47823..47826/callback`) and
+     * `token_endpoint_auth_method=none`. The local stack provisions one
+     * automatically; against a hosted project the operator registers it
+     * once and supplies the id here (or via `ORY_OAUTH2_CLIENT_ID`).
+     */
+    oauth2ClientId?: string;
     /** When true, only audit logging is enabled — no auth or permission checks. */
     auditOnly?: boolean;
     /**
@@ -144,11 +154,13 @@ export declare function mutateConfig(mutator: (current: OryPluginConfig) => OryP
 export declare function resolveConfig(): {
     projectUrl?: string;
     apiKey?: string;
+    oauth2ClientId?: string;
     auditOnly: boolean;
     permissionMode: PermissionMode;
     permissionModeSource: "env" | "config" | "default";
     projectUrlSource: "env" | "config" | "none";
     apiKeySource: "env" | "config" | "none";
+    oauth2ClientIdSource: "env" | "config" | "none";
 };
 /**
  * Build the "not configured" prompt message for a given harness CLI bin name.

package/dist/config.js

@@ -115,6 +115,7 @@ function loadConfig() {
         return {
             projectUrl: typeof parsed.projectUrl === "string" ? parsed.projectUrl : undefined,
             apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : undefined,
+            oauth2ClientId: typeof parsed.oauth2ClientId === "string" ? parsed.oauth2ClientId : undefined,
             auditOnly: parsed.auditOnly === true ? true : undefined,
             permissionMode: parsePermissionMode(parsed.permissionMode),
             user: parseUserCredentials(parsed),
@@ -328,6 +329,7 @@ function resolveConfig() {
     // alias kept for back-compat (agent-auth emits a warning when only the
     // legacy form is set).
     const envApiKey = process.env.ORY_AGENT_API_KEY ?? process.env.ORY_API_KEY;
+    const envClientId = process.env.ORY_OAUTH2_CLIENT_ID;
     const envMode = parsePermissionMode(process.env.ORY_PERMISSION_MODE);
     const permissionMode = envMode ?? file.permissionMode ?? "observe";
     const permissionModeSource = envMode
@@ -338,11 +340,13 @@ function resolveConfig() {
     return {
         projectUrl: envProjectUrl ?? file.projectUrl,
         apiKey: envApiKey ?? file.apiKey,
+        oauth2ClientId: envClientId ?? file.oauth2ClientId,
         auditOnly: file.auditOnly === true,
         permissionMode,
         permissionModeSource,
         projectUrlSource: envProjectUrl ? "env" : file.projectUrl ? "config" : "none",
         apiKeySource: envApiKey ? "env" : file.apiKey ? "config" : "none",
+        oauth2ClientIdSource: envClientId ? "env" : file.oauth2ClientId ? "config" : "none",
     };
 }
 /**
@@ -352,7 +356,7 @@ function configPromptMessage(binName) {
     return ("The Ory agent plugin is installed but not yet configured.\n" +
         "\n" +
         "  Option 1 — Connect to Ory (enables authentication and permission checks):\n" +
-        `    npx ${binName} configure --project-url <URL> --api-key <KEY>\n` +
+        `    npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]\n` +
         "\n" +
         "  Option 2 — Continue without authentication (audit logging only):\n" +
         `    npx ${binName} configure --audit-only\n` +

package/dist/dev.js

@@ -396,7 +396,7 @@ function buildLocalOryEnv(gatewayUrl, seed) {
         ORY_PERMISSION_NAMESPACE: seed.permissions.namespace,
         // User login — always on in local dev so the launcher demonstrates
         // the interactive PKCE login UX end-to-end every session.
-        ORY_USER_LOGIN: "1",
+        ORY_USER_LOGIN: "true",
         // Agent identity — the harness self-registers via DCR on first run
         // using the user's bearer as the initial access token. No static
         // client_credentials are seeded; explicitly clear them so a leaking

package/dist/index.d.ts

@@ -15,8 +15,9 @@ export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./
 export { renderOrySkills, renderOryCommands, commandToSkill, commandToToml, commandToFrontmatterMarkdown, commandToPlainMarkdown, toSkillMarkdown, writeSkillTree, removeSkillDirs, ORY_SKILL_NAMES, ORY_COMMAND_SKILL_NAMES, ORY_COMMAND_SLUGS, type RenderedSkill, type RenderedCommand, type RenderProfileOptions, } from "./skills.js";
 export { runLocalCommand, ensureDevJaeger, stopDevJaeger, DEV_JAEGER_CONTAINER, type EnsureDevJaegerResult, type StopDevJaegerResult, } from "./local/index.js";
 export { runRegistryCommand } from "./registry/index.js";
-export { checkAndDecide, applyPermissionMode, type PermissionDecision, type ModeDecision, type DecisionSpanAttributes, type CheckAndDecideOptions, type ApplyPermissionModeContext, } from "./permissions.js";
-export { HARNESS_TOOL_CATALOG, KNOWN_HARNESSES, ALL_TOOLS, getToolCatalog, type KnownHarness, } from "./tool-catalog.js";
+export { checkAndDecide, applyPermissionMode, gateToolCall, type PermissionDecision, type ModeDecision, type DecisionSpanAttributes, type CheckAndDecideOptions, type ApplyPermissionModeContext, type GateToolCallArgs, type ToolGateOutcome, } from "./permissions.js";
+export { HARNESS_TOOL_CATALOG, KNOWN_HARNESSES, ALL_TOOLS, getToolCatalog, INTERACTIVE_TOOL_CATALOG, getInteractiveToolCatalog, isInteractiveTool, type KnownHarness, } from "./tool-catalog.js";
+export { classifyLifecycle, isUserFacingPhase, isToolExecutionPhase, HARNESS_LIFECYCLE_MAP, USER_FACING_PHASES, TOOL_EXECUTION_PHASES, type LifecyclePhase, } from "./lifecycle.js";
 export { parseClaudeCodeMcpTool, parseGeminiMcpTool, parseMcpToolGeneric, checkMcpPermission, type McpToolIdentifier, type McpPermissionCheckOptions, type McpPermissionResult, } from "./mcp.js";
 export { resolveUserSubject, subjectLabel, type UserSubjectRef, } from "./subject.js";
 export { formatDenialMessage, formatDenialSummary, formatAlertMessage, formatAlertSummary, alertAttributes, OryDenialError, type DenialContext, type AlertAttributes, } from "./denial.js";

package/dist/index.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printOryConfig = exports.runAgentCommand = exports.runConfigureCommand = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = exports.clearSubAgentDynamicCredentials = exports.saveSubAgentDynamicCredentials = exports.loadSubAgentDynamicCredentials = exports.clearAgentDynamicCredentials = exports.saveAgentDynamicCredentials = exports.loadAgentDynamicCredentials = exports.registerAgentClient = exports.fetchClientCredentialsToken = exports.ensureSubAgentIdentity = exports.ensureAgentIdentity = exports.resolveAgentCredentials = exports.ensureAuthenticated = exports.ensureUserAuthenticated = exports.TOKEN_EXPIRY_SKEW_SEC = exports.waitForPeerTokensSync = exports.waitForPeerTokens = exports.clearPkceFlightLock = exports.tryAcquirePkceFlightLock = exports.refreshAndSave = exports.isExpired = exports.clearTokens = exports.saveTokens = exports.loadTokens = exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = exports.buildAuthorizeUrl = exports.sha256Base64Url = exports.generateCodeVerifier = exports.detectHeadless = exports.refreshAccessToken = exports.pkceLogin = exports.getHarnessDataDir = exports.getDataDir = exports.getConfigPath = exports.mutateConfig = exports.resolveConfig = exports.saveConfig = exports.loadConfig = exports.watchTraceFile = exports.formatSpan = exports.deriveTraceId = exports.ActiveSpan = exports.Tracer = exports.redactLogData = exports.DebugLogger = exports.OryAgentClient = void 0;
 exports.runLocalCommand = exports.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = exports.removeSkillDirs = exports.writeSkillTree = exports.toSkillMarkdown = exports.commandToPlainMarkdown = exports.commandToFrontmatterMarkdown = exports.commandToToml = exports.commandToSkill = exports.renderOryCommands = exports.renderOrySkills = exports.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.printNextSteps = exports.printSetupHelp = exports.removeFlatHooks = exports.mergeFlatHooks = exports.flatHookEntry = exports.removeMatcherHooks = exports.mergeMatcherHooks = exports.matcherHookEntry = exports.resolveHookCommand = exports.isOryHookCommand = exports.writeJsonFile = exports.readJsonFile = exports.parseSetupArgs = exports.printPermissionsSection = exports.printAgentIdentitySection = exports.printUserIdentitySection = exports.runStatusCommand = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = void 0;
-exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.applyPermissionMode = exports.checkAndDecide = exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = void 0;
+exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.TOOL_EXECUTION_PHASES = exports.USER_FACING_PHASES = exports.HARNESS_LIFECYCLE_MAP = exports.isToolExecutionPhase = exports.isUserFacingPhase = exports.classifyLifecycle = exports.isInteractiveTool = exports.getInteractiveToolCatalog = exports.INTERACTIVE_TOOL_CATALOG = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.gateToolCall = exports.applyPermissionMode = exports.checkAndDecide = exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return client_js_1.OryAgentClient; } });
 var logger_js_1 = require("./logger.js");
@@ -126,11 +126,22 @@ Object.defineProperty(exports, "runRegistryCommand", { enumerable: true, get: fu
 var permissions_js_1 = require("./permissions.js");
 Object.defineProperty(exports, "checkAndDecide", { enumerable: true, get: function () { return permissions_js_1.checkAndDecide; } });
 Object.defineProperty(exports, "applyPermissionMode", { enumerable: true, get: function () { return permissions_js_1.applyPermissionMode; } });
+Object.defineProperty(exports, "gateToolCall", { enumerable: true, get: function () { return permissions_js_1.gateToolCall; } });
 var tool_catalog_js_1 = require("./tool-catalog.js");
 Object.defineProperty(exports, "HARNESS_TOOL_CATALOG", { enumerable: true, get: function () { return tool_catalog_js_1.HARNESS_TOOL_CATALOG; } });
 Object.defineProperty(exports, "KNOWN_HARNESSES", { enumerable: true, get: function () { return tool_catalog_js_1.KNOWN_HARNESSES; } });
 Object.defineProperty(exports, "ALL_TOOLS", { enumerable: true, get: function () { return tool_catalog_js_1.ALL_TOOLS; } });
 Object.defineProperty(exports, "getToolCatalog", { enumerable: true, get: function () { return tool_catalog_js_1.getToolCatalog; } });
+Object.defineProperty(exports, "INTERACTIVE_TOOL_CATALOG", { enumerable: true, get: function () { return tool_catalog_js_1.INTERACTIVE_TOOL_CATALOG; } });
+Object.defineProperty(exports, "getInteractiveToolCatalog", { enumerable: true, get: function () { return tool_catalog_js_1.getInteractiveToolCatalog; } });
+Object.defineProperty(exports, "isInteractiveTool", { enumerable: true, get: function () { return tool_catalog_js_1.isInteractiveTool; } });
+var lifecycle_js_1 = require("./lifecycle.js");
+Object.defineProperty(exports, "classifyLifecycle", { enumerable: true, get: function () { return lifecycle_js_1.classifyLifecycle; } });
+Object.defineProperty(exports, "isUserFacingPhase", { enumerable: true, get: function () { return lifecycle_js_1.isUserFacingPhase; } });
+Object.defineProperty(exports, "isToolExecutionPhase", { enumerable: true, get: function () { return lifecycle_js_1.isToolExecutionPhase; } });
+Object.defineProperty(exports, "HARNESS_LIFECYCLE_MAP", { enumerable: true, get: function () { return lifecycle_js_1.HARNESS_LIFECYCLE_MAP; } });
+Object.defineProperty(exports, "USER_FACING_PHASES", { enumerable: true, get: function () { return lifecycle_js_1.USER_FACING_PHASES; } });
+Object.defineProperty(exports, "TOOL_EXECUTION_PHASES", { enumerable: true, get: function () { return lifecycle_js_1.TOOL_EXECUTION_PHASES; } });
 var mcp_js_1 = require("./mcp.js");
 Object.defineProperty(exports, "parseClaudeCodeMcpTool", { enumerable: true, get: function () { return mcp_js_1.parseClaudeCodeMcpTool; } });
 Object.defineProperty(exports, "parseGeminiMcpTool", { enumerable: true, get: function () { return mcp_js_1.parseGeminiMcpTool; } });

package/dist/lifecycle.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Canonical lifecycle vocabulary for harness plugins.
+ *
+ * Each harness exposes a different set of hook event names (Claude Code's
+ * `PreToolUse`, Gemini's `BeforeTool`, OpenCode's `tool.execute.before`,
+ * …). Mapping them onto a shared phase set lets the plugin code reason
+ * about *what is happening* without first remembering *which harness
+ * we're in*. Spans, logs, docs, and tests all reference the same set of
+ * phases.
+ *
+ * Phases split into three buckets:
+ *
+ * - **Session / agent lifecycle.** `session.start`, `session.stop`,
+ *   `compaction`. The session begins or ends, or the harness compacts
+ *   context. Plugins authenticate here (start) and may flush state
+ *   (stop).
+ *
+ * - **User-facing interactions.** `user.prompt`, `user.interaction`,
+ *   `permission.ask`. The harness is communicating with the human:
+ *   they typed a prompt, the harness is surfacing a confirmation,
+ *   the harness is asking whether to allow a tool. These are *traced*
+ *   but never gated by a tool permission check — the user is the
+ *   final decision-maker. (`permission.ask` does consult Ory to
+ *   inform the harness's UI, but the call is advisory.)
+ *
+ * - **Tool execution.** `tool.before`, `tool.after`, `tool.failure`,
+ *   `subagent.start`, `subagent.stop`. The agent is reaching into an
+ *   external system (or spawning a child agent that will). These are
+ *   the only phases that run a true `use` permission gate.
+ *
+ * `passthrough` is the explicit "nothing to do here" bucket — the
+ * harness fired an event we don't model, and we record an audit span
+ * and return.
+ */
+export type LifecyclePhase = "session.start" | "session.stop" | "user.prompt" | "user.interaction" | "permission.ask" | "tool.before" | "tool.after" | "tool.failure" | "subagent.start" | "subagent.stop" | "compaction" | "passthrough";
+/**
+ * Per-harness map from the harness's native event name to a canonical
+ * {@link LifecyclePhase}. Event names that don't appear here resolve to
+ * `passthrough` via {@link classifyLifecycle}.
+ */
+export declare const HARNESS_LIFECYCLE_MAP: Record<string, Record<string, LifecyclePhase>>;
+/**
+ * Resolve a harness event name to its canonical {@link LifecyclePhase}.
+ * Unknown harnesses or unknown event names both yield `passthrough`.
+ */
+export declare function classifyLifecycle(harness: string, event: string): LifecyclePhase;
+/**
+ * Phases that surface to the human (prompts, confirmations, notifications,
+ * advisory permission asks). Tool-call permission gates must never fire
+ * on these — the user is the decision-maker.
+ */
+export declare const USER_FACING_PHASES: ReadonlySet<LifecyclePhase>;
+/**
+ * Phases that represent actual tool execution against external systems.
+ * Only these run a real `use` permission check.
+ */
+export declare const TOOL_EXECUTION_PHASES: ReadonlySet<LifecyclePhase>;
+export declare function isUserFacingPhase(phase: LifecyclePhase): boolean;
+export declare function isToolExecutionPhase(phase: LifecyclePhase): boolean;

package/dist/lifecycle.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Canonical lifecycle vocabulary for harness plugins.
+ *
+ * Each harness exposes a different set of hook event names (Claude Code's
+ * `PreToolUse`, Gemini's `BeforeTool`, OpenCode's `tool.execute.before`,
+ * …). Mapping them onto a shared phase set lets the plugin code reason
+ * about *what is happening* without first remembering *which harness
+ * we're in*. Spans, logs, docs, and tests all reference the same set of
+ * phases.
+ *
+ * Phases split into three buckets:
+ *
+ * - **Session / agent lifecycle.** `session.start`, `session.stop`,
+ *   `compaction`. The session begins or ends, or the harness compacts
+ *   context. Plugins authenticate here (start) and may flush state
+ *   (stop).
+ *
+ * - **User-facing interactions.** `user.prompt`, `user.interaction`,
+ *   `permission.ask`. The harness is communicating with the human:
+ *   they typed a prompt, the harness is surfacing a confirmation,
+ *   the harness is asking whether to allow a tool. These are *traced*
+ *   but never gated by a tool permission check — the user is the
+ *   final decision-maker. (`permission.ask` does consult Ory to
+ *   inform the harness's UI, but the call is advisory.)
+ *
+ * - **Tool execution.** `tool.before`, `tool.after`, `tool.failure`,
+ *   `subagent.start`, `subagent.stop`. The agent is reaching into an
+ *   external system (or spawning a child agent that will). These are
+ *   the only phases that run a true `use` permission gate.
+ *
+ * `passthrough` is the explicit "nothing to do here" bucket — the
+ * harness fired an event we don't model, and we record an audit span
+ * and return.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_EXECUTION_PHASES = exports.USER_FACING_PHASES = exports.HARNESS_LIFECYCLE_MAP = void 0;
+exports.classifyLifecycle = classifyLifecycle;
+exports.isUserFacingPhase = isUserFacingPhase;
+exports.isToolExecutionPhase = isToolExecutionPhase;
+/**
+ * Per-harness map from the harness's native event name to a canonical
+ * {@link LifecyclePhase}. Event names that don't appear here resolve to
+ * `passthrough` via {@link classifyLifecycle}.
+ */
+exports.HARNESS_LIFECYCLE_MAP = {
+    "claude-code": {
+        SessionStart: "session.start",
+        SessionEnd: "session.stop",
+        PreToolUse: "tool.before",
+        PostToolUse: "tool.after",
+        PostToolUseFailure: "tool.failure",
+        PermissionRequest: "permission.ask",
+        UserPromptSubmit: "user.prompt",
+        SubagentStart: "subagent.start",
+        SubagentStop: "subagent.stop",
+    },
+    codex: {
+        SessionStart: "session.start",
+        Stop: "session.stop",
+        PreToolUse: "tool.before",
+        PostToolUse: "tool.after",
+        PermissionRequest: "permission.ask",
+        UserPromptSubmit: "user.prompt",
+    },
+    "gemini-cli": {
+        SessionStart: "session.start",
+        SessionEnd: "session.stop",
+        BeforeTool: "tool.before",
+        AfterTool: "tool.after",
+        BeforeToolSelection: "tool.before",
+        Notification: "user.interaction",
+        PreCompress: "compaction",
+    },
+    openclaw: {
+        session_start: "session.start",
+        before_agent_run: "user.prompt",
+        before_tool_call: "tool.before",
+        after_tool_call: "tool.after",
+        subagent_spawning: "subagent.start",
+        subagent_spawned: "subagent.start",
+        subagent_ended: "subagent.stop",
+    },
+    opencode: {
+        config: "session.start",
+        "chat.message": "user.prompt",
+        "permission.ask": "permission.ask",
+        "tool.execute.before": "tool.before",
+        "tool.execute.after": "tool.after",
+    },
+};
+/**
+ * Resolve a harness event name to its canonical {@link LifecyclePhase}.
+ * Unknown harnesses or unknown event names both yield `passthrough`.
+ */
+function classifyLifecycle(harness, event) {
+    return exports.HARNESS_LIFECYCLE_MAP[harness]?.[event] ?? "passthrough";
+}
+/**
+ * Phases that surface to the human (prompts, confirmations, notifications,
+ * advisory permission asks). Tool-call permission gates must never fire
+ * on these — the user is the decision-maker.
+ */
+exports.USER_FACING_PHASES = new Set([
+    "user.prompt",
+    "user.interaction",
+    "permission.ask",
+]);
+/**
+ * Phases that represent actual tool execution against external systems.
+ * Only these run a real `use` permission check.
+ */
+exports.TOOL_EXECUTION_PHASES = new Set([
+    "tool.before",
+    "tool.after",
+    "tool.failure",
+]);
+function isUserFacingPhase(phase) {
+    return exports.USER_FACING_PHASES.has(phase);
+}
+function isToolExecutionPhase(phase) {
+    return exports.TOOL_EXECUTION_PHASES.has(phase);
+}

package/dist/local/manager.js

@@ -622,8 +622,17 @@ function localEnv() {
 }
 function localConfigure() {
     console.log(`Saving local Ory gateway URL to shared config...`);
-    (0, config_js_1.saveConfig)({ projectUrl: configs_js_1.GATEWAY_URL, auditOnly: false });
-    console.log(`  Project URL: ${configs_js_1.GATEWAY_URL}`);
+    // Persist the seeded user PKCE client id alongside the project URL so
+    // a subsequent `configure --project-url <hosted>` doesn't trip the
+    // require-OAuth2-client check, and the user gate resolves the right
+    // client out of the box.
+    (0, config_js_1.saveConfig)({
+        projectUrl: configs_js_1.GATEWAY_URL,
+        oauth2ClientId: seed_js_1.USER_CLIENT_ID,
+        auditOnly: false,
+    });
+    console.log(`  Project URL:      ${configs_js_1.GATEWAY_URL}`);
+    console.log(`  OAuth2 Client ID: ${seed_js_1.USER_CLIENT_ID}`);
     console.log("");
     console.log("All Ory agent plugins will now connect to the local environment.");
     console.log("This persists across sessions. Run 'configure --project-url <URL>'");
@@ -647,7 +656,7 @@ function printSeedResult(result) {
     console.log("To use with any Ory agent plugin, set these environment variables:");
     console.log("");
     console.log(`  export ORY_PROJECT_URL=${configs_js_1.GATEWAY_URL}`);
-    console.log(`  export ORY_USER_LOGIN=1`);
+    console.log(`  export ORY_USER_LOGIN=true`);
     console.log(`  export ORY_OAUTH2_CLIENT_ID=${result.user.client.clientId}`);
     console.log(`  export ORY_USER_SUBJECT_NAMESPACE=User`);
     console.log(`  export ORY_USER_SUBJECT_ID=${result.user.identity.id}`);

package/dist/local/seed.d.ts

@@ -23,6 +23,13 @@
  * Idempotent — re-running the seed reuses existing identities and
  * recreates OAuth2 clients (so the secret is always known).
  */
+/**
+ * Stable client id Hydra issues to the seeded user PKCE client. Stable
+ * so `local configure` can persist it to the shared config and downstream
+ * runs can rely on `ORY_OAUTH2_CLIENT_ID` resolution without first
+ * dragging the value out of the `local up` banner.
+ */
+export declare const USER_CLIENT_ID = "ory-user-local";
 export interface SeededIdentity {
     id: string;
     email: string;

package/dist/local/seed.js

@@ -25,7 +25,7 @@
  * recreates OAuth2 clients (so the secret is always known).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.USER_SUBJECT_NAMESPACE = void 0;
+exports.USER_SUBJECT_NAMESPACE = exports.USER_CLIENT_ID = void 0;
 exports.seedLocalEnvironment = seedLocalEnvironment;
 const auth_js_1 = require("../auth.js");
 const tool_catalog_js_1 = require("../tool-catalog.js");
@@ -38,7 +38,13 @@ const AGENT_PASSWORD = "ory-agent-local-dev-password!";
 const USER_EMAIL = "user@ory-local.dev";
 const USER_PASSWORD = "ory-user-local-dev-password!";
 const USER_CLIENT_NAME = "ory-agent-plugins-local-user";
-const USER_CLIENT_ID = "ory-user-local";
+/**
+ * Stable client id Hydra issues to the seeded user PKCE client. Stable
+ * so `local configure` can persist it to the shared config and downstream
+ * runs can rely on `ORY_OAUTH2_CLIENT_ID` resolution without first
+ * dragging the value out of the `local up` banner.
+ */
+exports.USER_CLIENT_ID = "ory-user-local";
 /**
  * Tools the dev launcher seeds tuples for. Sourced from the shared
  * per-harness catalog so a single seed grants the local user identity
@@ -193,11 +199,11 @@ async function seedLocalEnvironment(namespace = "AgentTools") {
     //    OAuth2 client is intentionally NOT pre-registered; the harness
     //    will self-register via DCR on first session start.
     process.stderr.write("  Registering user OAuth2 client (PKCE)...\n");
-    let userClient = { clientId: USER_CLIENT_ID };
+    let userClient = { clientId: exports.USER_CLIENT_ID };
     try {
         userClient = await ensureOAuth2Client({
             clientName: USER_CLIENT_NAME,
-            clientId: USER_CLIENT_ID,
+            clientId: exports.USER_CLIENT_ID,
             // Public PKCE client — no secret. Hydra accepts an empty string
             // for `token_endpoint_auth_method=none`.
             grantTypes: ["authorization_code", "refresh_token"],

package/dist/permissions-cli.js

@@ -129,12 +129,12 @@ async function runPermissionsStatus(binName, harness) {
     console.log("");
     if (resolved.auditOnly) {
         console.log("Ory is disabled (audit-only). No permission checks run.");
-        console.log(`Re-enable with: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.log(`Re-enable with: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 0;
     }
     if (!resolved.projectUrl) {
         console.log("No project URL configured — cannot probe permission coverage.");
-        console.log(`Configure first: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.log(`Configure first: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 0;
     }
     if (catalog.length === 0) {
@@ -211,12 +211,12 @@ async function runPermissionsBootstrap(binName, harness, args) {
     const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
     if (resolved.auditOnly) {
         console.error("Ory is in audit-only mode (kill-switch). Nothing to bootstrap.");
-        console.error(`Re-enable Ory: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.error(`Re-enable Ory: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 1;
     }
     if (!resolved.projectUrl) {
         console.error("No ORY_PROJECT_URL configured — cannot write permissions.");
-        console.error(`Configure first: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.error(`Configure first: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 1;
     }
     if (catalog.length === 0) {
@@ -235,7 +235,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
         console.error("No user identity resolved — refusing to write permissions for an unknown subject.");
         console.error("");
         console.error("Either:");
-        console.error("  - run the harness once with ORY_USER_LOGIN=1 so a user token is cached, or");
+        console.error("  - run the harness once with ORY_USER_LOGIN=true so a user token is cached, or");
         console.error("  - set ORY_USER_SUBJECT_ID=<id> to target a known subject.");
         return 1;
     }

package/dist/permissions.d.ts

@@ -117,6 +117,57 @@ export interface ApplyPermissionModeContext {
  * proceed despite the deny.
  */
 export declare function applyPermissionMode(client: OryAgentClient, allowed: boolean, context?: ApplyPermissionModeContext): ModeDecision;
+/**
+ * Outcome of {@link gateToolCall}. Either the tool is a user-interaction
+ * primitive (`AskUserQuestion`, `ExitPlanMode`, `TodoWrite`, …) and we
+ * pass through with a single audit span, or it's a real tool execution
+ * and the caller gets the standard {@link PermissionDecision}.
+ */
+export type ToolGateOutcome = {
+    kind: "interactive";
+    /** Attributes to attach to the caller's pass-through trace, if any. */
+    spanAttributes: {
+        interactive: true;
+        toolName: string;
+    };
+} | PermissionDecision;
+export interface GateToolCallArgs {
+    /** Harness name (`claude-code`, `codex`, …). Used to look up the interactive-tool catalog. */
+    harness: string;
+    /** The tool the agent is invoking. */
+    toolName: string;
+    /** Permission check to run when the tool is a real execution. */
+    check: PermissionCheck;
+    /**
+     * Attributes merged into the permission span (real path) and the
+     * `user.interaction` span (interactive path).
+     */
+    spanAttributes?: Record<string, unknown>;
+    /** Override the resolved {@link PermissionMode}. Tests use this. */
+    modeOverride?: PermissionMode;
+}
+/**
+ * Single entry point for the pre-tool-use gate. Splits the harness's
+ * incoming "tool" into two semantic categories:
+ *
+ *   - **Interactive** — the tool surfaces UI to the user
+ *     (`AskUserQuestion`, `ExitPlanMode`, `TodoWrite`, plus anything
+ *     listed in `ORY_INTERACTIVE_TOOLS`). The plugin must not gate these
+ *     through Ory: the user is the decision-maker, and blocking them in
+ *     enforce mode (or logging a misleading observe-deny) hides the very
+ *     prompt the user needs to see. We record one `user.interaction`
+ *     audit span and return — no permission check, no `tool.invoke`,
+ *     no `tool.block`.
+ *
+ *   - **Execution** — every other tool. Delegates to
+ *     {@link checkAndDecide} so observe/enforce/fail-open behavior is
+ *     identical to the legacy code path.
+ *
+ * The caller branches on `outcome.kind`. The four execution kinds
+ * (`allow`, `deny`, `observe`, `fail_open`) keep their existing
+ * semantics; the new `interactive` kind means "do nothing else."
+ */
+export declare function gateToolCall(client: OryAgentClient, args: GateToolCallArgs): Promise<ToolGateOutcome>;
 /**
  * Run a permission check and resolve the configured mode against the
  * result. Never throws — fail-open scenarios are surfaced as a typed

package/dist/permissions.js

@@ -23,8 +23,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyPermissionMode = applyPermissionMode;
+exports.gateToolCall = gateToolCall;
 exports.checkAndDecide = checkAndDecide;
 const config_js_1 = require("./config.js");
+const tool_catalog_js_1 = require("./tool-catalog.js");
 function formatSubjectSet(set) {
     if (!set)
         return undefined;
@@ -75,6 +77,52 @@ function applyPermissionMode(client, allowed, context = {}) {
     }
     return { kind: "deny", mode: "enforce", spanAttributes };
 }
+/**
+ * Single entry point for the pre-tool-use gate. Splits the harness's
+ * incoming "tool" into two semantic categories:
+ *
+ *   - **Interactive** — the tool surfaces UI to the user
+ *     (`AskUserQuestion`, `ExitPlanMode`, `TodoWrite`, plus anything
+ *     listed in `ORY_INTERACTIVE_TOOLS`). The plugin must not gate these
+ *     through Ory: the user is the decision-maker, and blocking them in
+ *     enforce mode (or logging a misleading observe-deny) hides the very
+ *     prompt the user needs to see. We record one `user.interaction`
+ *     audit span and return — no permission check, no `tool.invoke`,
+ *     no `tool.block`.
+ *
+ *   - **Execution** — every other tool. Delegates to
+ *     {@link checkAndDecide} so observe/enforce/fail-open behavior is
+ *     identical to the legacy code path.
+ *
+ * The caller branches on `outcome.kind`. The four execution kinds
+ * (`allow`, `deny`, `observe`, `fail_open`) keep their existing
+ * semantics; the new `interactive` kind means "do nothing else."
+ */
+async function gateToolCall(client, args) {
+    if ((0, tool_catalog_js_1.isInteractiveTool)(args.harness, args.toolName)) {
+        client.logger.debug("tool.interactive", {
+            harness: args.harness,
+            toolName: args.toolName,
+            note: "user-interaction primitive — skipping permission check",
+        });
+        client.tracer.record("user.interaction", "ok", {
+            attributes: {
+                harness: args.harness,
+                toolName: args.toolName,
+                kind: "tool",
+                ...args.spanAttributes,
+            },
+        });
+        return {
+            kind: "interactive",
+            spanAttributes: { interactive: true, toolName: args.toolName },
+        };
+    }
+    return checkAndDecide(client, args.check, {
+        spanAttributes: args.spanAttributes,
+        modeOverride: args.modeOverride,
+    });
+}
 /**
  * Run a permission check and resolve the configured mode against the
  * result. Never throws — fail-open scenarios are surfaced as a typed

package/dist/setup.js

@@ -374,7 +374,9 @@ Environment variables:
   ORY_PROJECT_URL       Your Ory project URL (required at runtime)
   ORY_AGENT_API_KEY     Agent API key / OAuth2 bearer (preferred name;
                         ORY_API_KEY is honored as a deprecated alias)
-  ORY_USER_LOGIN        Set to "1" to enable the interactive user login
+  ORY_OAUTH2_CLIENT_ID  Public OAuth2 client id for the user PKCE flow
+                        (required when ORY_USER_LOGIN=true)
+  ORY_USER_LOGIN        Set to "true" to enable the interactive user login
   ORY_PERMISSION_MODE   "observe" (default) or "enforce" — what to do on deny
   ORY_AGENT_DEBUG       Set to "true" for debug logging
   ORY_AGENT_LOG_FILE    Path to write debug logs
@@ -392,9 +394,12 @@ function printNextSteps(harnessName, uninstallCmd) {
     console.log("     export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
     console.log("  2. Turn on the interactive user login (opt-in):");
-    console.log("     export ORY_USER_LOGIN=1");
-    console.log(`     Without this, ${harnessName} runs without a human Ory identity attached`);
+    console.log("     export ORY_USER_LOGIN=true");
+    console.log("     export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
+    console.log(`     Without these, ${harnessName} runs without a human Ory identity attached`);
     console.log("     to the session and permission checks fall back to a session:<id> subject.");
+    console.log("     The OAuth2 client id is the public client (no secret) you registered in");
+    console.log("     your Ory project with the four loopback redirect URIs.");
     console.log("");
     console.log("  3. Optionally enable debug logging:");
     console.log("     export ORY_AGENT_DEBUG=true");

package/dist/status-cli.js

@@ -57,7 +57,7 @@ function printUserIdentitySection() {
     const tokens = (0, auth_store_js_1.loadTokens)();
     console.log("");
     console.log("User identity (interactive PKCE login):");
-    console.log(`  Login:       ${loginOn ? "on (ORY_USER_LOGIN)" : "off (set ORY_USER_LOGIN=1 to enable)"}`);
+    console.log(`  Login:       ${loginOn ? "on (ORY_USER_LOGIN)" : "off (set ORY_USER_LOGIN=true to enable)"}`);
     if (!tokens) {
         console.log("  Token cache: empty");
         if (loginOn) {
@@ -209,7 +209,7 @@ async function printPermissionsSection(binName, harness) {
     }
     const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
     if (!hasUser) {
-        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_USER_LOGIN=1 once,`);
+        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_USER_LOGIN=true once,`);
         console.log(`               or set ORY_USER_SUBJECT_ID to probe a known subject)`);
         return;
     }

package/dist/tool-catalog.d.ts

@@ -36,3 +36,34 @@ export declare function getToolCatalog(harness: string): readonly string[];
  * broad access so the same launcher can run every harness end-to-end.
  */
 export declare const ALL_TOOLS: readonly string[];
+/**
+ * Per-harness tool names whose semantics are "ask / inform the user"
+ * rather than "act on an external system". These reach the pre-tool-use
+ * hook the same way real tools do (e.g. Claude Code's `AskUserQuestion`
+ * arrives via `PreToolUse`), but they aren't tool *executions* — gating
+ * them through Ory would either block the user from being asked or, in
+ * observe mode, log a misleading `permission.observe_deny` for an event
+ * the user is about to handle directly.
+ *
+ * Plugins consult this list in their pre-tool gate and short-circuit to
+ * a single `user.interaction` audit span when a match is found. See
+ * `gateToolCall` in `permissions.ts`.
+ *
+ * The list is best-effort and additive: operators can extend it at
+ * runtime via the `ORY_INTERACTIVE_TOOLS` env var (comma-separated names
+ * applied to every harness).
+ */
+export declare const INTERACTIVE_TOOL_CATALOG: Record<string, readonly string[]>;
+/**
+ * Names from {@link INTERACTIVE_TOOL_CATALOG} for the given harness,
+ * merged with any operator-supplied names from `ORY_INTERACTIVE_TOOLS`.
+ * Unknown harnesses still respect the env-var extension.
+ */
+export declare function getInteractiveToolCatalog(harness: string): readonly string[];
+/**
+ * Does the named tool, for the given harness, represent a user-facing
+ * interaction (ask / inform / confirm) rather than an external-system
+ * tool execution? Treats unknown harnesses the same as known ones — the
+ * env-var extension still applies.
+ */
+export declare function isInteractiveTool(harness: string, toolName: string): boolean;

package/dist/tool-catalog.js

@@ -13,8 +13,10 @@
  * catalog update is safe.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = void 0;
+exports.INTERACTIVE_TOOL_CATALOG = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = void 0;
 exports.getToolCatalog = getToolCatalog;
+exports.getInteractiveToolCatalog = getInteractiveToolCatalog;
+exports.isInteractiveTool = isInteractiveTool;
 /**
  * Built-in tool names known to ship with each supported harness.
  */
@@ -67,3 +69,58 @@ function getToolCatalog(harness) {
  * broad access so the same launcher can run every harness end-to-end.
  */
 exports.ALL_TOOLS = Array.from(new Set(Object.values(exports.HARNESS_TOOL_CATALOG).flat()));
+/**
+ * Per-harness tool names whose semantics are "ask / inform the user"
+ * rather than "act on an external system". These reach the pre-tool-use
+ * hook the same way real tools do (e.g. Claude Code's `AskUserQuestion`
+ * arrives via `PreToolUse`), but they aren't tool *executions* — gating
+ * them through Ory would either block the user from being asked or, in
+ * observe mode, log a misleading `permission.observe_deny` for an event
+ * the user is about to handle directly.
+ *
+ * Plugins consult this list in their pre-tool gate and short-circuit to
+ * a single `user.interaction` audit span when a match is found. See
+ * `gateToolCall` in `permissions.ts`.
+ *
+ * The list is best-effort and additive: operators can extend it at
+ * runtime via the `ORY_INTERACTIVE_TOOLS` env var (comma-separated names
+ * applied to every harness).
+ */
+exports.INTERACTIVE_TOOL_CATALOG = {
+    "claude-code": ["AskUserQuestion", "ExitPlanMode", "TodoWrite"],
+    codex: [],
+    "gemini-cli": [],
+    openclaw: [],
+    opencode: [],
+};
+function parseEnvInteractiveTools() {
+    const raw = process.env.ORY_INTERACTIVE_TOOLS;
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+}
+/**
+ * Names from {@link INTERACTIVE_TOOL_CATALOG} for the given harness,
+ * merged with any operator-supplied names from `ORY_INTERACTIVE_TOOLS`.
+ * Unknown harnesses still respect the env-var extension.
+ */
+function getInteractiveToolCatalog(harness) {
+    const builtIn = exports.INTERACTIVE_TOOL_CATALOG[harness] ?? [];
+    const envExtra = parseEnvInteractiveTools();
+    if (envExtra.length === 0)
+        return builtIn;
+    // Stable order: built-ins first, then env additions, deduplicated.
+    return Array.from(new Set([...builtIn, ...envExtra]));
+}
+/**
+ * Does the named tool, for the given harness, represent a user-facing
+ * interaction (ask / inform / confirm) rather than an external-system
+ * tool execution? Treats unknown harnesses the same as known ones — the
+ * env-var extension still applies.
+ */
+function isInteractiveTool(harness, toolName) {
+    return getInteractiveToolCatalog(harness).includes(toolName);
+}

package/dist/tracer.d.ts

@@ -18,7 +18,7 @@
  */
 import { EventEmitter } from "node:events";
 import type { SpanExporter } from "./otel/exporter.js";
-export type TraceEvent = "session.start" | "session.end" | "session.verify" | "user.auth" | "user.prompt" | "agent.auth" | "oauth2.introspect" | "oauth2.login" | "oauth2.refresh" | "permission.check" | "permission.batch_check" | "permission.observe_deny" | "tool.invoke" | "tool.complete" | "tool.block" | "tool.fail" | "turn.stop" | "subagent.start" | "subagent.stop" | "notification" | "compaction" | "relationship.create" | "relationship.delete" | "relationship.patch" | "hook.receive" | "hook.passthrough" | "config.resolve";
+export type TraceEvent = "session.start" | "session.end" | "session.verify" | "user.auth" | "user.prompt" | "user.interaction" | "agent.auth" | "oauth2.introspect" | "oauth2.login" | "oauth2.refresh" | "permission.check" | "permission.batch_check" | "permission.observe_deny" | "tool.invoke" | "tool.complete" | "tool.block" | "tool.fail" | "turn.stop" | "subagent.start" | "subagent.stop" | "notification" | "compaction" | "relationship.create" | "relationship.delete" | "relationship.patch" | "hook.receive" | "hook.passthrough" | "config.resolve";
 export type SpanStatus = "ok" | "error" | "denied" | "skipped";
 export interface TraceSpan {
     traceId: string;

package/dist/user-login.d.ts

@@ -18,7 +18,8 @@
  * the audit trail is complete regardless of outcome.
  *
  * The whole flow is a no-op (mode `disabled`) unless the
- * `ORY_USER_LOGIN` env var is set to `1`/`true`.
+ * `ORY_USER_LOGIN` env var is set to `true` (legacy values `1`, `yes`,
+ * `on` are still accepted for back-compat).
  *
  * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved

package/dist/user-login.js

@@ -19,7 +19,8 @@
  * the audit trail is complete regardless of outcome.
  *
  * The whole flow is a no-op (mode `disabled`) unless the
- * `ORY_USER_LOGIN` env var is set to `1`/`true`.
+ * `ORY_USER_LOGIN` env var is set to `true` (legacy values `1`, `yes`,
+ * `on` are still accepted for back-compat).
  *
  * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved
@@ -39,7 +40,10 @@ function isUserLoginEnabled() {
     return !!v && ENABLED_VALUES.has(v);
 }
 function clientId() {
-    return process.env.ORY_OAUTH2_CLIENT_ID;
+    // resolveConfig already merges env (ORY_OAUTH2_CLIENT_ID) with the
+    // persisted value, env winning. Centralizing here keeps the user gate,
+    // status CLI, and configure command in lockstep on resolution order.
+    return (0, config_js_1.resolveConfig)().oauth2ClientId;
 }
 function recordAuthSpan(client, decision) {
     const status = decision.mode === "ok" || decision.mode === "refreshed" || decision.mode === "env_token"
@@ -211,7 +215,9 @@ async function runUserLogin(client, options) {
             mode: "skipped",
             reason: "ORY_OAUTH2_CLIENT_ID is not set; cannot start browser login (run `npx " +
                 options.binName +
-                " configure` and register an OAuth2 client with the loopback redirect URIs)",
+                " configure --oauth2-client-id <id>` after registering a public OAuth2 client " +
+                "in your Ory project with all four loopback redirect URIs: " +
+                "http://127.0.0.1:47823..47826/callback)",
         };
     }
     // No TTY check here on purpose: PKCE only needs a browser that can reach
@@ -221,7 +227,7 @@ async function runUserLogin(client, options) {
     // complete sign-in by pasting the URL into any browser that can reach
     // 127.0.0.1. Truly unattended runs (CI=true) are short-circuited by
     // `pkceLogin` itself via `detectHeadless`, and operators can bypass
-    // login entirely with `ORY_USER_SESSION_TOKEN` or `ORY_USER_LOGIN=0`.
+    // login entirely with `ORY_USER_SESSION_TOKEN` or `ORY_USER_LOGIN=false`.
     // PKCE-flight lock so concurrent processes share a single browser flow.
     const lock = (0, auth_store_js_1.tryAcquirePkceFlightLock)();
     if (!lock) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Ory Argus: the core API for building authentication, authorization, and audit into AI agent harness plugins, extensions, and custom integrations",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",