@ory/argus 0.14.0 → 1.0.0

package/dist/testing.js

@@ -40,19 +40,21 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BATCH_SERVER_DENIED = exports.BATCH_SERVER_ALLOWED_TOOL_DENIED = exports.BATCH_BOTH_ALLOWED = exports.PERMISSION_DENIED = exports.PERMISSION_ALLOWED = exports.MOCK_INACTIVE_OAUTH2_RESPONSE = exports.MOCK_OAUTH2_RESPONSE = exports.MOCK_INACTIVE_SESSION_RESPONSE = exports.MOCK_SESSION_RESPONSE = exports.runHarnessContractSuite = void 0;
+exports.TEST_OAUTH2_CLIENT_ID = exports.TEST_AGENT_SECURITY_URL = exports.TEST_PROJECT_URL = exports.BATCH_SERVER_DENIED = exports.BATCH_SERVER_ALLOWED_TOOL_DENIED = exports.BATCH_BOTH_ALLOWED = exports.PERMISSION_DENIED = exports.PERMISSION_ALLOWED = exports.MOCK_INACTIVE_OAUTH2_RESPONSE = exports.MOCK_OAUTH2_RESPONSE = exports.MOCK_INACTIVE_SESSION_RESPONSE = exports.MOCK_SESSION_RESPONSE = exports.runHarnessContractSuite = void 0;
 exports.createMockClient = createMockClient;
-exports.stubRelationshipExists = stubRelationshipExists;
+exports.spyRecordDelegation = spyRecordDelegation;
 exports.stubApi = stubApi;
 exports.makeAxiosError = makeAxiosError;
 exports.makeNetworkError = makeNetworkError;
 exports.makeRateLimitError = makeRateLimitError;
 exports.makeMfaRequiredError = makeMfaRequiredError;
 exports.makeSessionInactiveError = makeSessionInactiveError;
-exports.getTraceSpans = getTraceSpans;
-exports.expectTracedTools = expectTracedTools;
+exports.getActivityEvents = getActivityEvents;
+exports.expectActivityTools = expectActivityTools;
 exports.setOryEnv = setOryEnv;
 exports.useTempConfigDir = useTempConfigDir;
+exports.connectSecurity = connectSecurity;
+exports.disconnectSecurity = disconnectSecurity;
 exports.clearOryEnv = clearOryEnv;
 exports.stubSessionSuccess = stubSessionSuccess;
 exports.stubSessionInactive = stubSessionInactive;
@@ -61,12 +63,11 @@ exports.stubSessionMfaRequired = stubSessionMfaRequired;
 exports.stubSessionExpired = stubSessionExpired;
 exports.stubOAuth2Success = stubOAuth2Success;
 exports.stubOAuth2Inactive = stubOAuth2Inactive;
+exports.setTestPermissionMode = setTestPermissionMode;
 exports.stubPermissionAllowed = stubPermissionAllowed;
 exports.stubPermissionDenied = stubPermissionDenied;
 exports.stubPermissionNetworkError = stubPermissionNetworkError;
 exports.stubPermissionRateLimited = stubPermissionRateLimited;
-exports.spyRelationshipCreated = spyRelationshipCreated;
-exports.spyRelationshipCreateError = spyRelationshipCreateError;
 exports.stubMcpAllowed = stubMcpAllowed;
 exports.stubMcpServerDenied = stubMcpServerDenied;
 exports.stubMcpToolDenied = stubMcpToolDenied;
@@ -76,8 +77,12 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const vitest_1 = require("vitest");
 const client_js_1 = require("./client.js");
+const config_js_1 = require("./config.js");
+const opl_js_1 = require("./opl.js");
+const permission_mode_js_1 = require("./permission-mode.js");
 // Shared per-harness contract scenarios (session fail-open, gate
-// translation, audit-only). See contract-suite.ts for the adapter shape.
+// translation, Agent Security not connected). See contract-suite.ts for the
+// adapter shape.
 var contract_suite_js_1 = require("./contract-suite.js");
 Object.defineProperty(exports, "runHarnessContractSuite", { enumerable: true, get: function () { return contract_suite_js_1.runHarnessContractSuite; } });
 // ─── Client Helpers ────────────────────────────────────────────────
@@ -88,29 +93,31 @@ Object.defineProperty(exports, "runHarnessContractSuite", { enumerable: true, ge
 function createMockClient(overrides) {
     const client = new client_js_1.OryAgentClient({
         projectUrl: "https://test.projects.oryapis.com",
-        apiKey: "test-api-key",
         harness: "test",
         sessionCacheTtlMs: 0,
         ...overrides,
     });
-    // `ensureRelationship` probes for the exact tuple before writing. Default
-    // to "no tuple exists" so a plain createRelationship-asserting test sees the
-    // write proceed; tests that model an already-present tuple override this via
-    // `stubRelationshipExists`. We spy the public `relationshipExists` method
-    // (not the internal getRelationships API) because setAgentPrincipal rebuilds
-    // the Keto API instance and would discard an API-level stub.
-    vitest_1.vi.spyOn(client, "relationshipExists").mockResolvedValue(false);
+    // Delegation edges are recorded through the agent-security broker (a real
+    // `fetch` in production). Default it to a resolved no-op so session-start /
+    // sub-agent paths under test never make a network call; tests that assert the
+    // broker call override this via `spyRecordDelegation`.
+    vitest_1.vi.spyOn(client, "recordDelegation").mockResolvedValue({
+        nodeId: "agent:mock-node",
+        delegationChain: [],
+    });
     return client;
 }
 /**
- * Control what the exact-tuple existence probe ({@link OryAgentClient.relationshipExists},
- * used by `ensureRelationship`) reports. Pass `true` to model a tuple that is
- * already stored (the write is then skipped), `false` for absent (the write
- * proceeds). Returns the spy so callers can e.g. `.mockRejectedValue(...)` to
- * model a failed probe.
+ * Spy on {@link OryAgentClient.recordDelegation} (the agent-security broker
+ * call the delegation writers use). Resolves to `result` (a stub node by
+ * default). Returns the spy so callers assert the broker inputs or
+ * `.mockRejectedValue(...)` a broker failure.
  */
-function stubRelationshipExists(client, exists) {
-    return vitest_1.vi.spyOn(client, "relationshipExists").mockResolvedValue(exists);
+function spyRecordDelegation(client, result = {
+    nodeId: "agent:mock-node",
+    delegationChain: [],
+}) {
+    return vitest_1.vi.spyOn(client, "recordDelegation").mockResolvedValue(result);
 }
 /**
  * Stub an internal API instance method on the client.
@@ -209,28 +216,27 @@ function makeSessionInactiveError() {
         error: { id: "session_inactive", message: "No active session" },
     });
 }
-// ─── Trace Span Assertions ────────────────────────────────────────
+// ─── Activity Assertions ──────────────────────────────────────────
 /**
- * Get all recorded trace spans from a client, optionally filtered by event.
+ * Get all recorded activity events from a client, optionally filtered by event.
  */
-function getTraceSpans(client, event) {
-    const all = client.tracer.spans();
-    return event ? all.filter((s) => s.event === event) : all;
+function getActivityEvents(client, event) {
+    const all = client.logger.activities();
+    return event ? all.filter((entry) => entry.event === event) : all;
 }
 /**
- * Assert the tracer recorded the expected tool names for a given event type.
- * Checks the `toolName` attribute on each span.
+ * Assert the activity log recorded the expected tool names for an event type.
  */
-function expectTracedTools(client, event, expectedTools) {
-    const spans = getTraceSpans(client, event);
-    const tools = spans.map((s) => s.attributes?.toolName);
+function expectActivityTools(client, event, expectedTools) {
+    const events = getActivityEvents(client, event);
+    const tools = events.map((entry) => entry.attributes?.toolName);
     for (const tool of expectedTools) {
         if (!tools.includes(tool)) {
-            throw new Error(`Expected trace event "${event}" for tool "${tool}" but got: [${tools.join(", ")}]`);
+            throw new Error(`Expected activity event "${event}" for tool "${tool}" but got: [${tools.join(", ")}]`);
         }
     }
-    if (spans.length !== expectedTools.length) {
-        throw new Error(`Expected ${expectedTools.length} "${event}" spans but got ${spans.length}: [${tools.join(", ")}]`);
+    if (events.length !== expectedTools.length) {
+        throw new Error(`Expected ${expectedTools.length} "${event}" events but got ${events.length}: [${tools.join(", ")}]`);
     }
 }
 // ─── Environment Helpers ───────────────────────────────────────────
@@ -244,12 +250,28 @@ function setOryEnv(overrides = {}) {
         ORY_PROJECT_URL: "projectUrl" in overrides
             ? overrides.projectUrl
             : "https://test.projects.oryapis.com",
-        ORY_SESSION_TOKEN: "sessionToken" in overrides ? overrides.sessionToken : "valid-token",
-        ORY_OAUTH2_TOKEN: overrides.oauth2Token,
+        ORY_AGENT_SECURITY_URL: "agentSecurityUrl" in overrides
+            ? overrides.agentSecurityUrl
+            : "https://agents.console.ory.com",
+        // Both connection values default to present: tests exercise the
+        // *connected* posture unless they explicitly clear one.
+        ORY_OAUTH2_CLIENT_ID: "oauth2ClientId" in overrides ? overrides.oauth2ClientId : "test-login-client",
+        ORY_USER_OAUTH2_TOKEN: "userToken" in overrides ? overrides.userToken : "valid-token",
         ORY_AGENT_SUBJECT_ID: overrides.subjectId,
         ORY_PERMISSION_NAMESPACE: overrides.namespace,
-        ORY_PERMISSION_MODE: "permissionMode" in overrides ? overrides.permissionMode : "enforce",
+        // Disable the mode cache's TTL so each gate re-reads the stub — no stale
+        // memo bleeds across tests.
+        ORY_PERMISSION_MODE_TTL_MS: "0",
     };
+    const prevMode = currentTestMode;
+    setTestPermissionMode("permissionMode" in overrides ? overrides.permissionMode : "enforce");
+    // Isolate the config dir too. The mode is now server-read and the session-start
+    // warm persists it to config.json; without isolation that warm would write the
+    // developer's real ~/.config and bleed between tests. A test that also calls
+    // useTempConfigDir just nests another temp dir on top (both restore cleanly).
+    const prevXdg = process.env.XDG_CONFIG_HOME;
+    const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "ory-env-config-"));
+    process.env.XDG_CONFIG_HOME = tmpHome;
     for (const [key, value] of Object.entries(vars)) {
         saved[key] = process.env[key];
         if (value !== undefined) {
@@ -260,6 +282,7 @@ function setOryEnv(overrides = {}) {
         }
     }
     return () => {
+        setTestPermissionMode(prevMode);
         for (const [key, value] of Object.entries(saved)) {
             if (value !== undefined) {
                 process.env[key] = value;
@@ -268,6 +291,11 @@ function setOryEnv(overrides = {}) {
                 delete process.env[key];
             }
         }
+        if (prevXdg !== undefined)
+            process.env.XDG_CONFIG_HOME = prevXdg;
+        else
+            delete process.env.XDG_CONFIG_HOME;
+        fs.rmSync(tmpHome, { recursive: true, force: true });
     };
 }
 /**
@@ -277,7 +305,7 @@ function setOryEnv(overrides = {}) {
  * that restores the env var and removes the temp directory.
  *
  * Use `saveConfig(...)` from `./config.js` inside the test to shape the
- * isolated config (e.g. `saveConfig({ auditOnly: true })`).
+ * isolated config (e.g. `saveConfig({ projectUrl, oauth2ClientId })`).
  */
 function useTempConfigDir() {
     const saved = process.env.XDG_CONFIG_HOME;
@@ -291,21 +319,65 @@ function useTempConfigDir() {
         fs.rmSync(tmpHome, { recursive: true, force: true });
     };
 }
+/** Placeholder values `connectSecurity` / `disconnectSecurity` write. */
+exports.TEST_PROJECT_URL = "https://test.projects.oryapis.com";
+exports.TEST_AGENT_SECURITY_URL = "https://agents.console.ory.com";
+exports.TEST_OAUTH2_CLIENT_ID = "test-login-client";
+/**
+ * Put the isolated config into the **connected** state so the auth gates and
+ * permission checks actually run.
+ *
+ * Agent Security is connected exactly when a project URL and an OAuth2 client
+ * id both resolve — there is no flag to set. Tests that exercise checks need
+ * both, and writing them through one named call keeps that requirement in one
+ * place instead of two literals in every `beforeEach`.
+ *
+ * Call after `useTempConfigDir()` so it writes to the temp config.
+ */
+function connectSecurity(overrides = {}) {
+    (0, config_js_1.saveConfig)({
+        projectUrl: overrides.projectUrl ?? exports.TEST_PROJECT_URL,
+        agentSecurityUrl: overrides.agentSecurityUrl ?? exports.TEST_AGENT_SECURITY_URL,
+        oauth2ClientId: overrides.oauth2ClientId ?? exports.TEST_OAUTH2_CLIENT_ID,
+    });
+}
+/**
+ * Put the isolated config into a partial connection state for contract tests.
+ *
+ * `which` selects which connection values are absent. The `no-client-id` case
+ * now exercises the reserved client default rather than a disconnected state.
+ * The `neither` and `no-project-url` forms remain disconnected.
+ */
+function disconnectSecurity(which = "neither") {
+    (0, config_js_1.saveConfig)({
+        projectUrl: which === "no-client-id" ? exports.TEST_PROJECT_URL : null,
+        agentSecurityUrl: which === "no-client-id" ? exports.TEST_AGENT_SECURITY_URL : null,
+        oauth2ClientId: which === "no-project-url" ? exports.TEST_OAUTH2_CLIENT_ID : null,
+    });
+    // Env wins over the file, so a leaked env var would silently reconnect.
+    delete process.env.ORY_PROJECT_URL;
+    delete process.env.ORY_SDK_URL;
+    delete process.env.ORY_AGENT_SECURITY_URL;
+    delete process.env.ORY_OAUTH2_CLIENT_ID;
+    if (which === "no-client-id")
+        process.env.ORY_PROJECT_URL = exports.TEST_PROJECT_URL;
+    if (which === "no-project-url")
+        process.env.ORY_OAUTH2_CLIENT_ID = exports.TEST_OAUTH2_CLIENT_ID;
+}
 /**
  * Clear all Ory env vars (simulate unconfigured state).
  */
 function clearOryEnv() {
     delete process.env.ORY_PROJECT_URL;
-    delete process.env.ORY_API_KEY;
-    delete process.env.ORY_SESSION_TOKEN;
-    delete process.env.ORY_OAUTH2_TOKEN;
+    delete process.env.ORY_AGENT_SECURITY_URL;
+    delete process.env.ORY_OAUTH2_CLIENT_ID;
+    delete process.env.ORY_USER_OAUTH2_TOKEN;
     delete process.env.ORY_AGENT_SUBJECT_ID;
     delete process.env.ORY_USER_SUBJECT_ID;
     delete process.env.ORY_USER_SUBJECT_NAMESPACE;
     delete process.env.ORY_PERMISSION_NAMESPACE;
-    // Intentionally leave ORY_PERMISSION_MODE alone — it's typically set
-    // once at the top of a test file to pin the historical enforce-mode
-    // behavior, and unconfigured-Ory tests don't exercise permission
+    // The mode is a server-read permission now (no env var). Leave the stub's
+    // `currentTestMode` alone — unconfigured-Ory tests don't exercise permission
     // checks anyway.
 }
 // ─── Stub Presets ──────────────────────────────────────────────────
@@ -337,55 +409,100 @@ function stubOAuth2Success(client) {
 function stubOAuth2Inactive(client) {
     return stubApi(client, "oauth2", "introspectOAuth2Token", () => Promise.resolve(exports.MOCK_INACTIVE_OAUTH2_RESPONSE));
 }
+// ─── Permission mode (server-read) test control ────────────────────
+//
+// The gate now resolves observe/enforce by issuing a `checkPermission` against
+// the reserved `__ory_permission_mode__#enforce` object (see permission-mode.ts).
+// So the generic checkPermission stubs must answer THAT check with the desired
+// mode and every OTHER check with the tool decision. `currentTestMode` holds the
+// mode a test wants (default `enforce`, preserving the historical default where
+// `setOryEnv` pinned enforce so deny-path assertions blocked).
+let currentTestMode = "enforce";
+/**
+ * Set the mode the server-read stub reports. Also clears the in-memory
+ * permission-mode cache so the new value takes effect immediately (tests run
+ * with `ORY_PERMISSION_MODE_TTL_MS=0`, but resetting is belt-and-suspenders).
+ */
+function setTestPermissionMode(mode) {
+    currentTestMode = mode;
+    (0, permission_mode_js_1.resetPermissionModeCache)();
+}
+/** True when a checkPermission's params target the permission-mode object. */
+function isModeCheck(args) {
+    const p = args[0];
+    return p?.object === opl_js_1.PERMISSION_MODE_OBJECT && p?.relation === opl_js_1.RELATION_ENFORCED_SUBJECTS;
+}
+/**
+ * Build a `checkPermission` impl that answers the mode check with
+ * `currentTestMode` and every other check with `toolResponse`. Every stub below
+ * routes through this so a single test setting controls the mode independently
+ * of the tool decision.
+ */
+function checkPermissionResponder(toolResponse) {
+    return (...args) => {
+        if (isModeCheck(args)) {
+            return Promise.resolve(currentTestMode === "enforce" ? exports.PERMISSION_ALLOWED : exports.PERMISSION_DENIED);
+        }
+        return Promise.resolve(toolResponse);
+    };
+}
+function ensurePermissionCredential(client) {
+    if (client.agentPrincipal.token)
+        return;
+    client.setAgentPrincipal({ ...client.agentPrincipal, token: "test-agent-token" });
+}
 /** Stub checkPermission to allow. */
 function stubPermissionAllowed(client) {
-    return stubApi(client, "permission", "checkPermission", () => Promise.resolve(exports.PERMISSION_ALLOWED));
+    ensurePermissionCredential(client);
+    stubApi(client, "permission", "batchCheckPermission", (request) => {
+        const tuples = request.batchCheckPermissionBody?.tuples ?? [];
+        return Promise.resolve({
+            data: {
+                results: tuples.map((tuple) => ({
+                    // "Allowed" means the requested action is granted; an explicit
+                    // block probe must remain absent or it would reverse that decision.
+                    allowed: tuple.relation !== "blockedSubjects",
+                })),
+            },
+        });
+    });
+    return stubApi(client, "permission", "checkPermission", checkPermissionResponder(exports.PERMISSION_ALLOWED));
 }
-/** Stub checkPermission to deny. */
+/** Stub checkPermission to deny (the tool check; the mode check still answers `currentTestMode`). */
 function stubPermissionDenied(client) {
-    return stubApi(client, "permission", "checkPermission", () => Promise.resolve(exports.PERMISSION_DENIED));
+    ensurePermissionCredential(client);
+    return stubApi(client, "permission", "checkPermission", checkPermissionResponder(exports.PERMISSION_DENIED));
 }
 /** Stub checkPermission to throw a network error. */
 function stubPermissionNetworkError(client) {
+    ensurePermissionCredential(client);
     return stubApi(client, "permission", "checkPermission", () => Promise.reject(makeNetworkError()));
 }
 /** Stub checkPermission to throw a rate-limit error. */
 function stubPermissionRateLimited(client) {
+    ensurePermissionCredential(client);
     return stubApi(client, "permission", "checkPermission", () => Promise.reject(makeRateLimitError()));
 }
-/**
- * Spy on the public `createRelationship` method and resolve successfully.
- * Prefer this over stubbing the internal relationship API: `setAgentPrincipal`
- * rebuilds the API instances when the agent token changes (e.g. inside
- * `sessionStart`), which silently discards API-level stubs.
- */
-function spyRelationshipCreated(client) {
-    return vitest_1.vi
-        .spyOn(client, "createRelationship")
-        .mockResolvedValue({ created: true, alreadyExisted: false });
-}
-/** Spy on the public `createRelationship` method and reject. */
-function spyRelationshipCreateError(client) {
-    return vitest_1.vi
-        .spyOn(client, "createRelationship")
-        .mockRejectedValue(new Error("relationship write failed"));
-}
 // ─── MCP Stub Presets ─────────────────────────────────────────────
 /** Stub both checkPermission (server allow) and batchCheckPermission (both allow). */
 function stubMcpAllowed(client) {
-    stubApi(client, "permission", "checkPermission", () => Promise.resolve(exports.PERMISSION_ALLOWED));
+    ensurePermissionCredential(client);
+    stubApi(client, "permission", "checkPermission", checkPermissionResponder(exports.PERMISSION_ALLOWED));
     return stubApi(client, "permission", "batchCheckPermission", () => Promise.resolve(exports.BATCH_BOTH_ALLOWED));
 }
 /** Stub checkPermission to deny (server-only MCP check). */
 function stubMcpServerDenied(client) {
-    return stubApi(client, "permission", "checkPermission", () => Promise.resolve(exports.PERMISSION_DENIED));
+    ensurePermissionCredential(client);
+    return stubApi(client, "permission", "checkPermission", checkPermissionResponder(exports.PERMISSION_DENIED));
 }
 /** Stub batchCheckPermission: server allowed, tool denied. */
 function stubMcpToolDenied(client) {
-    stubApi(client, "permission", "checkPermission", () => Promise.resolve(exports.PERMISSION_ALLOWED));
+    ensurePermissionCredential(client);
+    stubApi(client, "permission", "checkPermission", checkPermissionResponder(exports.PERMISSION_ALLOWED));
     return stubApi(client, "permission", "batchCheckPermission", () => Promise.resolve(exports.BATCH_SERVER_ALLOWED_TOOL_DENIED));
 }
 /** Stub checkPermission to throw network error (MCP fail-open). */
 function stubMcpNetworkError(client) {
+    ensurePermissionCredential(client);
     return stubApi(client, "permission", "checkPermission", () => Promise.reject(makeNetworkError()));
 }

package/dist/tool-catalog.d.ts

@@ -1,15 +1,14 @@
 /**
- * Canonical per-harness tool catalog used by `permissions bootstrap` to
- * seed Keto tuples granting the current user `use` on each tool.
+ * Canonical per-harness tool catalog: the objects an Ory project grants `use`
+ * on, and the set `permissions status` probes coverage across.
  *
  * These lists cover each harness's built-in tools — the names the harness
  * passes to the pre-tool-use hook. MCP server tools are intentionally
  * omitted because they're discovered dynamically per session and can't be
- * enumerated at bootstrap time.
+ * enumerated ahead of time.
  *
- * The lists are best-effort: harness vendors add and rename tools over
- * time. `bootstrap` is idempotent and additive, so re-running it after a
- * catalog update is safe.
+ * The lists are best-effort: harness vendors add and rename tools over time,
+ * so a project's grants may cover more or fewer names than the catalog knows.
  */
 /**
  * Built-in tool names known to ship with each supported harness.
@@ -27,6 +26,7 @@ export declare const HARNESS_TOOL_CATALOG: {
     readonly amp: readonly ["Bash", "Read", "create_file", "edit_file", "undo_edit", "glob", "Grep", "finder", "read_web_page", "web_search", "todo_read", "todo_write", "oracle", "Task"];
     readonly pi: readonly ["read", "write", "edit", "bash", "grep", "find", "ls"];
     readonly antigravity: readonly ["run_command", "view_file", "write_to_file", "replace_file_content", "multi_replace_file_content", "list_directory", "grep_search", "find", "read_url_content", "search_web", "call_mcp_tool"];
+    readonly cursor: readonly ["Read", "Write", "Edit", "Delete", "Shell", "List", "Search", "MCP", "Task"];
 };
 /** Names of the harnesses with a known tool catalog. */
 export type KnownHarness = keyof typeof HARNESS_TOOL_CATALOG;
@@ -34,13 +34,12 @@ export declare const KNOWN_HARNESSES: readonly KnownHarness[];
 /**
  * Tools for a specific harness. Returns the canonical list when known;
  * empty array for unknown harnesses (callers can fall back to {@link
- * ALL_TOOLS} or skip bootstrap with a warning).
+ * ALL_TOOLS} or skip the catalog-scoped step with a warning).
  */
 export declare function getToolCatalog(harness: string): readonly string[];
 /**
- * Union of every known tool across all harnesses, deduplicated. Used by
- * the dev launcher's seed routine, which grants the local user identity
- * broad access so the same launcher can run every harness end-to-end.
+ * Union of every known tool across all harnesses, deduplicated. Used by local
+ * environment seeding to grant broad access across every built-in tool set.
  */
 export declare const ALL_TOOLS: readonly string[];
 /**
@@ -53,7 +52,7 @@ export declare const ALL_TOOLS: readonly string[];
  * 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
+ * a single `user.interaction` audit event when a match is found. See
  * `gateToolCall` in `permissions.ts`.
  *
  * The list is best-effort and additive: operators can extend it at
@@ -74,3 +73,46 @@ export declare function getInteractiveToolCatalog(harness: string): readonly str
  * env-var extension still applies.
  */
 export declare function isInteractiveTool(harness: string, toolName: string): boolean;
+/**
+ * Per-harness name(s) of the shell/exec tool whose input is decomposed into
+ * `ShellTool:<word>#use` sub-checks. Validated against each harness's
+ * types/handlers. Names vary (`Bash`, `shell`, `exec`, `run_command`, …) so a
+ * precise map is used rather than the {@link isBashLikeTool} heuristic.
+ */
+export declare const SHELL_TOOL_CATALOG: Record<string, readonly string[]>;
+/**
+ * Shell-tool names for a harness, merged with the operator env extension
+ * `ORY_SHELL_TOOLS` (same pattern as `ORY_INTERACTIVE_TOOLS`) so a vendor tool
+ * rename can be handled without a plugin release.
+ */
+export declare function getShellToolCatalog(harness: string): readonly string[];
+/** Is the named tool, for this harness, the shell/exec tool to decompose? */
+export declare function isShellTool(harness: string, toolName: string): boolean;
+/**
+ * Broad list of shell command *words* — common dev binaries, sensitive
+ * binaries, and builtins — that an Ory project is expected to grant `use` on
+ * so enforce mode is practical out of the box; revoke a specific word in the
+ * Ory Console to close it. Builtins are included because they are a real
+ * bypass surface (`echo "$SECRET" >/dev/tcp/…`, `read`, redirection tricks).
+ * `permissions status` reports coverage against this list.
+ */
+export declare const SHELL_COMMAND_CATALOG: readonly string[];
+/**
+ * The shell command word list, merged with the operator env extension
+ * `ORY_SHELL_COMMANDS`.
+ */
+export declare function getShellCommandCatalog(): readonly string[];
+/**
+ * Keto namespace for shell-command sub-tools. Defaults to `ShellTool`,
+ * parallel to `mcp_servers` / `mcp_tools`. The object is the bare word (`curl`),
+ * relation `use`. Override with `ORY_SHELL_COMMAND_NAMESPACE`.
+ */
+export declare function resolveShellCommandNamespace(): string;
+/**
+ * Extract the shell command string from a harness's tool-args object — the same
+ * object the handler already passes to `summarizeToolInput`. Returns `undefined`
+ * when the tool isn't a shell tool for this harness or no command field is
+ * present (the gate then skips decomposition and degrades to the top-level
+ * `Bash` check — it never breaks).
+ */
+export declare function extractShellCommand(harness: string, toolName: string, args: unknown): string | undefined;