@ory/argus 0.13.9 → 1.0.0

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeCredential } from "./runtime-credential.js";
+export interface SessionContext {
+    sessionId?: string;
+    runtimeCredential?: RuntimeCredential;
+}
+export declare function currentSessionContext(): Readonly<SessionContext>;
+export declare function withSessionContext<T>(context: SessionContext, work: () => T): T;
+/** Test and low-level integration helper. Prefer `withHookContext` in adapters. */
+export declare function setSessionContext(context: SessionContext): void;
+export declare function clearSessionContext(): void;

package/dist/context.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentSessionContext = currentSessionContext;
+exports.withSessionContext = withSessionContext;
+exports.setSessionContext = setSessionContext;
+exports.clearSessionContext = clearSessionContext;
+const node_async_hooks_1 = require("node:async_hooks");
+const sessionStorage = new node_async_hooks_1.AsyncLocalStorage();
+function currentSessionContext() {
+    return sessionStorage.getStore() ?? {};
+}
+function withSessionContext(context, work) {
+    return sessionStorage.run({ ...currentSessionContext(), ...context }, work);
+}
+/** Test and low-level integration helper. Prefer `withHookContext` in adapters. */
+function setSessionContext(context) {
+    sessionStorage.enterWith({ ...context });
+}
+function clearSessionContext() {
+    sessionStorage.enterWith({});
+}

package/dist/contract-suite.d.ts

@@ -2,13 +2,13 @@
  * Shared contract suite for harness plugin tests.
  *
  * Every harness plugin translates the same core decisions (session gates,
- * `gateToolCall`, audit-only) onto its own native signals (exit codes,
+ * `gateToolCall`, the not-connected short-circuit) onto its own native signals (exit codes,
  * `{ decision: "block" }`, `{ block: true }`, thrown errors, …). The
  * *decision semantics* are core-owned and tested once in `packages/core`;
  * what varies per harness is only the translation. This suite re-runs the
  * canonical scenario tables through a harness's real entry point via a
  * small adapter, so a plugin cannot ship with a divergent understanding of
- * observe / enforce / fail-open / audit-only — without each plugin
+ * observe / enforce / fail-open / not-connected — without each plugin
  * re-transcribing the tables.
  *
  * A harness test file calls:
@@ -28,7 +28,7 @@
  *
  * and then adds only its genuinely harness-specific tests: export shape,
  * event-name dispatch, block-signal details, input parsing (MCP names,
- * `subagent_type`), unique span enrichment, and the install CLI.
+ * `subagent_type`), unique activity enrichment, and the install CLI.
  */
 import { OryAgentClient } from "./client.js";
 import type { ensureUserAuthenticated } from "./user-login.js";
@@ -61,14 +61,14 @@ export interface HarnessContractAdapter {
     /** A real, non-interactive tool from this harness's catalog. */
     tool: string;
     /**
-     * Whether the harness's session-start primitive can carry a hard block
-     * (subprocess exit-code harnesses: true; in-process advisory: false).
+     * @deprecated Ignored. Session start is now uniformly non-blocking on every
+     * harness (authentication never blocks; enforcement is governed by
+     * `permissionMode` at tool-call time). Kept optional so existing adapters
+     * that still pass it type-check.
      */
-    sessionCanBlock: boolean;
+    sessionCanBlock?: boolean;
     /** Whether the tool gate can hard-block. Defaults to true. */
     toolCanBlock?: boolean;
-    /** Set false when the plugin has no legacy OAuth2-token session path. */
-    legacyOAuth2?: boolean;
     /** Drive the session-start phase through the plugin's real entry point. */
     sessionStart(ctx: ContractContext): Promise<ContractOutcome>;
     /** Drive the pre-tool gate for `tool` through the plugin's real entry point. */

package/dist/contract-suite.js

@@ -3,13 +3,13 @@
  * Shared contract suite for harness plugin tests.
  *
  * Every harness plugin translates the same core decisions (session gates,
- * `gateToolCall`, audit-only) onto its own native signals (exit codes,
+ * `gateToolCall`, the not-connected short-circuit) onto its own native signals (exit codes,
  * `{ decision: "block" }`, `{ block: true }`, thrown errors, …). The
  * *decision semantics* are core-owned and tested once in `packages/core`;
  * what varies per harness is only the translation. This suite re-runs the
  * canonical scenario tables through a harness's real entry point via a
  * small adapter, so a plugin cannot ship with a divergent understanding of
- * observe / enforce / fail-open / audit-only — without each plugin
+ * observe / enforce / fail-open / not-connected — without each plugin
  * re-transcribing the tables.
  *
  * A harness test file calls:
@@ -29,19 +29,18 @@
  *
  * and then adds only its genuinely harness-specific tests: export shape,
  * event-name dispatch, block-signal details, input parsing (MCP names,
- * `subagent_type`), unique span enrichment, and the install CLI.
+ * `subagent_type`), unique activity enrichment, and the install CLI.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runHarnessContractSuite = runHarnessContractSuite;
 const vitest_1 = require("vitest");
-const config_js_1 = require("./config.js");
 const testing_js_1 = require("./testing.js");
-const DISABLED_DECISION = {
+const DEFAULT_DECISION = {
     proceed: true,
-    mode: "disabled",
-    reason: "ORY_USER_LOGIN not enabled",
+    mode: "skipped",
+    reason: "no cached user identity in contract suite",
 };
-function makeGates(userDecision = DISABLED_DECISION) {
+function makeGates(userDecision = DEFAULT_DECISION) {
     return {
         userLogin: vitest_1.vi.fn(async () => userDecision),
         agentGate: vitest_1.vi.fn(async () => ({
@@ -59,16 +58,13 @@ function makeGates(userDecision = DISABLED_DECISION) {
 }
 const ENV_KEYS = [
     "ORY_PROJECT_URL",
-    "ORY_API_KEY",
-    "ORY_SESSION_TOKEN",
-    "ORY_OAUTH2_TOKEN",
-    "ORY_USER_SESSION_TOKEN",
+    "ORY_SDK_URL",
+    "ORY_OAUTH2_CLIENT_ID",
     "ORY_USER_OAUTH2_TOKEN",
-    "ORY_USER_LOGIN",
     "ORY_USER_SUBJECT_ID",
     "ORY_USER_SUBJECT_NAMESPACE",
     "ORY_AGENT_SUBJECT_ID",
-    "ORY_PERMISSION_MODE",
+    "ORY_PERMISSION_MODE_TTL_MS",
     "ORY_PERMISSION_NAMESPACE",
     "ORY_INTERACTIVE_TOOLS",
 ];
@@ -88,7 +84,16 @@ function runHarnessContractSuite(adapter) {
                 delete process.env[key];
             }
             restoreConfigDir = (0, testing_js_1.useTempConfigDir)();
+            // Agent Security runs exactly when both values are present. The contract
+            // matrix exercises the *connected* posture, so set both; the dedicated
+            // not-connected test clears them again.
             process.env.ORY_PROJECT_URL = "https://test.projects.oryapis.com";
+            process.env.ORY_OAUTH2_CLIENT_ID = "test-login-client";
+            // Disable the mode cache TTL so each row re-reads the stubbed mode.
+            process.env.ORY_PERMISSION_MODE_TTL_MS = "0";
+            // Default the stubbed server-read mode to enforce (the matrix rows set it
+            // per-case via setTestPermissionMode).
+            (0, testing_js_1.setTestPermissionMode)("enforce");
             client = (0, testing_js_1.createMockClient)({ harness: adapter.harness });
         });
         (0, vitest_1.afterEach)(() => {
@@ -103,21 +108,23 @@ function runHarnessContractSuite(adapter) {
         const ctx = (gates = makeGates()) => ({ client, gates });
         // ── Session start never blocks on auth/infra failures ─────────
         (0, vitest_1.describe)("session start is fail-open", () => {
+            // The stubs below back APIs the session-start path no longer calls
+            // (`verifySession` / `introspectToken`). They stay because the invariant
+            // under test is that session start proceeds *regardless* of what those
+            // would have said — a plugin that reintroduced a verification
+            // fall-through would start failing these rows.
             vitest_1.it.each([
-                { name: "valid session token", env: "session", stub: testing_js_1.stubSessionSuccess },
-                { name: "inactive session", env: "session", stub: testing_js_1.stubSessionInactive },
-                { name: "session network error", env: "session", stub: testing_js_1.stubSessionNetworkError },
-                { name: "MFA required", env: "session", stub: testing_js_1.stubSessionMfaRequired },
-                { name: "valid OAuth2 token", env: "oauth2", stub: testing_js_1.stubOAuth2Success },
-                { name: "inactive OAuth2 token", env: "oauth2", stub: testing_js_1.stubOAuth2Inactive },
+                { name: "a pre-supplied token", env: "token", stub: testing_js_1.stubSessionSuccess },
+                { name: "an inactive session upstream", env: "token", stub: testing_js_1.stubSessionInactive },
+                { name: "a session network error", env: "token", stub: testing_js_1.stubSessionNetworkError },
+                { name: "MFA required upstream", env: "token", stub: testing_js_1.stubSessionMfaRequired },
+                { name: "an active OAuth2 introspection", env: "token", stub: testing_js_1.stubOAuth2Success },
+                { name: "an inactive OAuth2 introspection", env: "token", stub: testing_js_1.stubOAuth2Inactive },
                 { name: "unconfigured (no project URL)", env: "none", stub: undefined },
-            ])("proceeds with $name", async ({ env, stub, name }) => {
-                if (name.includes("OAuth2") && adapter.legacyOAuth2 === false)
-                    return;
-                if (env === "session")
-                    process.env.ORY_SESSION_TOKEN = "token-under-test";
-                if (env === "oauth2")
-                    process.env.ORY_OAUTH2_TOKEN = "token-under-test";
+            ])("proceeds with $name", async ({ env, stub }) => {
+                // `ORY_USER_OAUTH2_TOKEN` is the one accepted env credential.
+                if (env === "token")
+                    process.env.ORY_USER_OAUTH2_TOKEN = "token-under-test";
                 if (env === "none")
                     delete process.env.ORY_PROJECT_URL;
                 stub?.(client);
@@ -125,42 +132,34 @@ function runHarnessContractSuite(adapter) {
                 (0, vitest_1.expect)(outcome.blocked).toBe(false);
             });
         });
-        // ── User-login gate translation ────────────────────────────────
+        // ── User-login gate is advisory (never blocks the session) ─────
         (0, vitest_1.describe)("user-login gate", () => {
             const declined = {
                 proceed: false,
                 mode: "declined",
                 reason: "User declined the OAuth2 consent screen",
             };
-            (0, vitest_1.it)(adapter.sessionCanBlock
-                ? "translates a declined login into the native session block"
-                : "treats a declined login as advisory (no session block channel)", async () => {
+            (0, vitest_1.it)("never blocks the session even when the user login declines", async () => {
+                // Authentication is non-blocking on every harness; enforcement is
+                // governed by permissionMode at tool-call time, not here.
                 const gates = makeGates(declined);
                 const outcome = await adapter.sessionStart(ctx(gates));
-                (0, vitest_1.expect)(outcome.blocked).toBe(adapter.sessionCanBlock);
-                if (adapter.sessionCanBlock) {
-                    (0, vitest_1.expect)(outcome.reason).toBeTruthy();
-                }
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)((0, testing_js_1.getActivityEvents)(client, "session.start")).toHaveLength(1);
             });
             (0, vitest_1.it)("runs the agent gate even when the user gate declines", async () => {
                 const gates = makeGates(declined);
                 await adapter.sessionStart(ctx(gates));
                 (0, vitest_1.expect)(gates.agentGate).toHaveBeenCalledOnce();
             });
-            (0, vitest_1.it)("proceeds without legacy verification when the gate handled auth", async () => {
-                process.env.ORY_SESSION_TOKEN = "should-not-be-verified";
-                const verify = (0, testing_js_1.stubSessionSuccess)(client);
-                const gates = makeGates({ proceed: true, mode: "ok", reason: "logged in" });
-                const outcome = await adapter.sessionStart(ctx(gates));
-                (0, vitest_1.expect)(outcome.blocked).toBe(false);
-                (0, vitest_1.expect)(verify).not.toHaveBeenCalled();
-            });
-            (0, vitest_1.it)("falls through to legacy verification when the gate is disabled", async () => {
-                process.env.ORY_SESSION_TOKEN = "legacy-token";
+            (0, vitest_1.it)("never runs a legacy session-token verification path", async () => {
+                // The user gate owns authentication; there is no separate legacy
+                // verify/introspect fall-through any longer.
+                process.env.ORY_USER_OAUTH2_TOKEN = "should-not-be-verified";
                 const verify = (0, testing_js_1.stubSessionSuccess)(client);
                 const outcome = await adapter.sessionStart(ctx());
                 (0, vitest_1.expect)(outcome.blocked).toBe(false);
-                (0, vitest_1.expect)(verify).toHaveBeenCalled();
+                (0, vitest_1.expect)(verify).not.toHaveBeenCalled();
             });
         });
         // ── Tool gate translation ──────────────────────────────────────
@@ -169,8 +168,8 @@ function runHarnessContractSuite(adapter) {
                 { check: "allowed", mode: "enforce", blocked: false, invoke: true, block: false },
                 { check: "denied", mode: "enforce", blocked: toolCanBlock, invoke: false, block: true },
                 { check: "denied", mode: "observe", blocked: false, invoke: true, block: true },
-                { check: "network_error", mode: "enforce", blocked: false, invoke: false, block: false },
-                { check: "rate_limited", mode: "enforce", blocked: false, invoke: false, block: false },
+                { check: "network_error", mode: "enforce", blocked: false, invoke: true, block: false },
+                { check: "rate_limited", mode: "enforce", blocked: false, invoke: true, block: false },
             ])("check=$check × $mode → blocked=$blocked", async ({ check, mode, blocked, invoke, block }) => {
                 const stubs = {
                     allowed: testing_js_1.stubPermissionAllowed,
@@ -179,54 +178,74 @@ function runHarnessContractSuite(adapter) {
                     rate_limited: testing_js_1.stubPermissionRateLimited,
                 };
                 stubs[check](client);
-                process.env.ORY_PERMISSION_MODE = mode;
+                (0, testing_js_1.setTestPermissionMode)(mode);
                 const outcome = await adapter.toolBefore(ctx(), adapter.tool);
                 (0, vitest_1.expect)(outcome.blocked).toBe(blocked);
                 if (blocked)
                     (0, vitest_1.expect)(outcome.reason).toBeTruthy();
-                const invokeSpans = (0, testing_js_1.getTraceSpans)(client, "tool.invoke");
-                const blockSpans = (0, testing_js_1.getTraceSpans)(client, "tool.block");
+                const invokeEvents = (0, testing_js_1.getActivityEvents)(client, "tool.invoke");
+                const blockEvents = (0, testing_js_1.getActivityEvents)(client, "tool.block");
                 if (invoke) {
-                    (0, vitest_1.expect)(invokeSpans.length).toBeGreaterThanOrEqual(1);
-                    (0, vitest_1.expect)(invokeSpans[0].attributes?.toolName).toBe(adapter.tool);
+                    (0, vitest_1.expect)(invokeEvents.length).toBeGreaterThanOrEqual(1);
+                    (0, vitest_1.expect)(invokeEvents[0].attributes?.toolName).toBe(adapter.tool);
                 }
                 else {
-                    (0, vitest_1.expect)(invokeSpans).toHaveLength(0);
+                    (0, vitest_1.expect)(invokeEvents).toHaveLength(0);
                 }
                 if (block) {
-                    (0, vitest_1.expect)(blockSpans.length).toBeGreaterThanOrEqual(1);
-                    (0, vitest_1.expect)(blockSpans[0].attributes?.blocked).toBe(mode === "enforce" && toolCanBlock);
+                    (0, vitest_1.expect)(blockEvents.length).toBeGreaterThanOrEqual(1);
+                    (0, vitest_1.expect)(blockEvents[0].attributes?.blocked).toBe(mode === "enforce" && toolCanBlock);
+                    (0, vitest_1.expect)(blockEvents[0].attributes?.observed).toBe(mode === "observe" ? true : undefined);
                 }
                 else {
-                    (0, vitest_1.expect)(blockSpans).toHaveLength(0);
+                    (0, vitest_1.expect)(blockEvents).toHaveLength(0);
                 }
-                // Observe-mode denies also emit the audit span; enforce must not.
-                const observeSpans = (0, testing_js_1.getTraceSpans)(client, "permission.observe_deny");
-                (0, vitest_1.expect)(observeSpans).toHaveLength(check === "denied" && mode === "observe" ? 1 : 0);
+                // Observe-mode denies also emit the audit event; enforce must not.
+                const observeEvents = (0, testing_js_1.getActivityEvents)(client, "permission.observe_deny");
+                (0, vitest_1.expect)(observeEvents).toHaveLength(check === "denied" && mode === "observe" ? 1 : 0);
             });
-            (0, vitest_1.it)("skips the permission check entirely in audit-only mode", async () => {
-                (0, config_js_1.saveConfig)({ auditOnly: true });
+            (0, vitest_1.it)("records tool.invoke when an interactive tool proceeds", async () => {
+                process.env.ORY_INTERACTIVE_TOOLS = adapter.tool;
+                const outcome = await adapter.toolBefore(ctx(), adapter.tool);
+                (0, vitest_1.expect)(outcome.blocked).toBe(false);
+                (0, vitest_1.expect)((0, testing_js_1.getActivityEvents)(client, "tool.invoke")).toHaveLength(1);
+            });
+            // A project URL is the required address. The public login client has a
+            // reserved default, so omitting only its override remains connected.
+            vitest_1.it.each([
+                ["no project URL and no client id", { url: false, clientId: false }],
+                ["a client id but no project URL", { url: false, clientId: true }],
+            ])("skips the permission check entirely with %s", async (_label, { url, clientId }) => {
+                if (!url)
+                    delete process.env.ORY_PROJECT_URL;
+                if (!clientId)
+                    delete process.env.ORY_OAUTH2_CLIENT_ID;
                 const checkSpy = vitest_1.vi.spyOn(client, "checkPermission");
-                process.env.ORY_PERMISSION_MODE = "enforce";
+                (0, testing_js_1.setTestPermissionMode)("enforce");
                 const outcome = await adapter.toolBefore(ctx(), adapter.tool);
+                // Never blocks: with nothing to check against, the tool passes through.
                 (0, vitest_1.expect)(outcome.blocked).toBe(false);
                 (0, vitest_1.expect)(checkSpy).not.toHaveBeenCalled();
             });
-            (0, vitest_1.it)("addresses the check to ORY_USER_SUBJECT_ID when set", async () => {
+            (0, vitest_1.it)("addresses the check to ORY_USER_SUBJECT_ID when set (as a User SubjectSet)", async () => {
                 process.env.ORY_USER_SUBJECT_ID = "user:custom-override";
                 (0, testing_js_1.stubPermissionAllowed)(client);
                 await adapter.toolBefore(ctx(), adapter.tool);
-                const [span] = (0, testing_js_1.getTraceSpans)(client, "tool.invoke");
-                (0, vitest_1.expect)(span.attributes?.subjectId).toBe("user:custom-override");
+                const [activity] = (0, testing_js_1.getActivityEvents)(client, "tool.invoke");
+                // Principals are addressed as SubjectSets under the default `User`
+                // namespace; activity carries the SubjectSet, not a direct subjectId.
+                (0, vitest_1.expect)(activity.attributes?.subjectSet).toBeUndefined();
+                (0, vitest_1.expect)(activity.attributes?.subjectSetHash).toMatch(/^[a-f0-9]{16}$/);
+                (0, vitest_1.expect)(activity.attributes?.subjectId).toBeUndefined();
             });
         });
         // ── Post-tool + passthrough ────────────────────────────────────
         if (adapter.toolAfter) {
             (0, vitest_1.it)("records tool.complete after execution", async () => {
                 await adapter.toolAfter(ctx(), adapter.tool);
-                const spans = (0, testing_js_1.getTraceSpans)(client, "tool.complete");
-                (0, vitest_1.expect)(spans.length).toBeGreaterThanOrEqual(1);
-                (0, vitest_1.expect)(spans[0].attributes?.toolName).toBe(adapter.tool);
+                const events = (0, testing_js_1.getActivityEvents)(client, "tool.complete");
+                (0, vitest_1.expect)(events.length).toBeGreaterThanOrEqual(1);
+                (0, vitest_1.expect)(events[0].attributes?.toolName).toBe(adapter.tool);
             });
         }
         if (adapter.unknownEvent) {

package/dist/denial.d.ts

@@ -15,11 +15,35 @@ export interface DenialContext {
     subjectId: string;
     namespace?: string;
     mcp?: McpToolIdentifier;
+    /**
+     * Shell decomposition (issue #76): the denied command word (`curl`) inside a
+     * `Bash` call. When set, the message names the word and the
+     * `ShellTool:<word>#use` permission instead of the tool.
+     */
+    shellWord?: string;
+    /**
+     * Every denied command word when more than one was blocked in the same shell
+     * call. The message lists them all so the user can grant them in one pass;
+     * {@link shellWord} remains the primary (first) word for back-compat.
+     */
+    shellDeniedWords?: string[];
+    /** Set when a shell command was blocked because it could not be safely parsed. */
+    shellTooComplex?: boolean;
+    /** Namespace for shell-command sub-tools (default `ShellTool`). */
+    shellNamespace?: string;
+    /**
+     * True when the deny was an *explicit block* (a `blocked` relation matched
+     * the subject) rather than a missing grant. Changes the wording from "not
+     * authorized" to "explicitly blocked" and points the user at removing the
+     * block rather than granting a permission. Sourced from a decision's
+     * `activityAttributes.blockReason === "explicit_block"`.
+     */
+    blocked?: boolean;
 }
 /**
- * Span attributes that mark a denial as a security alert.
+ * Activity attributes that mark a denial as a security alert.
  *
- * Spread these onto the existing `tool.block` span attributes whenever an
+ * Spread these onto the existing `tool.block` activity attributes whenever an
  * actual deny comes back from Ory. The shape is stable so downstream
  * alerting rules can hook on `attributes.alert === true` and filter by
  * `attributes.severity` or `attributes.alertKind` without string matching.
@@ -40,7 +64,7 @@ export declare function alertAttributes(blocked: boolean): AlertAttributes;
 /**
  * Human-facing denial reason for an alert that the harness cannot enforce
  * (advisory mode). Prepends an explicit "ORY SECURITY ALERT TRIGGERED"
- * banner and notes that the trace span is the alert signal, so the agent
+ * banner and notes that the activity event is the alert signal, so the agent
  * — and any human reading transcripts — can't miss that a security event
  * was emitted even though the tool was allowed to proceed.
  */
@@ -50,6 +74,15 @@ export declare function formatAlertMessage(ctx: DenialContext): string;
  * systemMessage, etc.) when the denial cannot be enforced.
  */
 export declare function formatAlertSummary(ctx: DenialContext): string;
+/**
+ * Extract the shell-decomposition denial fields (issue #76) from a permission
+ * decision's activity attributes, for spreading into a {@link DenialContext}. Reads
+ * defensively (the outcome union includes non-shell members) so harness
+ * handlers can write `...shellDenialFields(decision)` without narrowing.
+ */
+export declare function shellDenialFields(decision: {
+    activityAttributes?: unknown;
+}): Pick<DenialContext, "shellWord" | "shellDeniedWords" | "shellTooComplex" | "shellNamespace" | "blocked">;
 /**
  * Human-facing denial reason. Shown in agent UIs (Claude Code's `decision`
  * reason, Gemini CLI's systemMessage, OpenClaw's blockReason, OpenCode's

package/dist/denial.js

@@ -15,9 +15,21 @@ exports.OryDenialError = void 0;
 exports.alertAttributes = alertAttributes;
 exports.formatAlertMessage = formatAlertMessage;
 exports.formatAlertSummary = formatAlertSummary;
+exports.shellDenialFields = shellDenialFields;
 exports.formatDenialMessage = formatDenialMessage;
 exports.formatDenialSummary = formatDenialSummary;
-const ADMIN_HINT = "Contact your Ory Keto administrator to grant the required permission.";
+const tool_catalog_js_1 = require("./tool-catalog.js");
+/**
+ * Where a user is sent when a tool is denied.
+ *
+ * Names the **Ory Console** rather than "your Ory Keto administrator": since
+ * #180 the plugin is a read-only Keto client and grants, blocks, and the
+ * permission model are all provisioned in the Console by someone with project
+ * access. There is no "Keto administrator" role to contact, and "Keto" is
+ * internal vocabulary that should never reach an end user (#222).
+ */
+const ADMIN_HINT = "Ask someone with access to your Ory project to grant this permission in the Ory Console (Agent Security).";
+const BLOCK_HINT = "This subject is explicitly blocked from this tool. Ask someone with access to your Ory project to remove the block in the Ory Console (Agent Security).";
 function alertAttributes(blocked) {
     return {
         alert: true,
@@ -30,12 +42,12 @@ const ALERT_PREFIX = "ORY SECURITY ALERT TRIGGERED";
 /**
  * Human-facing denial reason for an alert that the harness cannot enforce
  * (advisory mode). Prepends an explicit "ORY SECURITY ALERT TRIGGERED"
- * banner and notes that the trace span is the alert signal, so the agent
+ * banner and notes that the activity event is the alert signal, so the agent
  * — and any human reading transcripts — can't miss that a security event
  * was emitted even though the tool was allowed to proceed.
  */
 function formatAlertMessage(ctx) {
-    return `[${ALERT_PREFIX}] ${formatDenialMessage(ctx)} A security alert trace span was recorded for this denied tool call.`;
+    return `[${ALERT_PREFIX}] ${formatDenialMessage(ctx)} A security activity event was recorded for this denied tool call.`;
 }
 /**
  * Short alert summary suitable for compact UI fields (Gemini's
@@ -44,38 +56,95 @@ function formatAlertMessage(ctx) {
 function formatAlertSummary(ctx) {
     return `[${ALERT_PREFIX}] ${formatDenialSummary(ctx)}`;
 }
+/**
+ * Extract the shell-decomposition denial fields (issue #76) from a permission
+ * decision's activity attributes, for spreading into a {@link DenialContext}. Reads
+ * defensively (the outcome union includes non-shell members) so harness
+ * handlers can write `...shellDenialFields(decision)` without narrowing.
+ */
+function shellDenialFields(decision) {
+    const sa = (decision.activityAttributes ?? {});
+    return {
+        shellWord: sa.shellWord,
+        shellDeniedWords: sa.shellDeniedWords,
+        shellTooComplex: sa.shellTooComplex,
+        shellNamespace: (0, tool_catalog_js_1.resolveShellCommandNamespace)(),
+        blocked: sa.blockReason === "explicit_block",
+    };
+}
 /**
  * Human-facing denial reason. Shown in agent UIs (Claude Code's `decision`
  * reason, Gemini CLI's systemMessage, OpenClaw's blockReason, OpenCode's
  * thrown error message).
  */
 function formatDenialMessage(ctx) {
+    if (ctx.shellTooComplex) {
+        return (`Ory: shell command blocked — it could not be safely parsed and is ` +
+            `denied in enforce mode. Subject "${ctx.subjectId}". ` +
+            `Simplify the command or split it into individually authorized steps.`);
+    }
+    if (ctx.shellWord) {
+        const ns = ctx.shellNamespace ?? "ShellTool";
+        const shellHint = ctx.blocked ? BLOCK_HINT : ADMIN_HINT;
+        const shellVerb = ctx.blocked
+            ? "is explicitly blocked from running"
+            : "is not authorized to run";
+        const denied = ctx.shellDeniedWords && ctx.shellDeniedWords.length > 0
+            ? ctx.shellDeniedWords
+            : [ctx.shellWord];
+        if (denied.length > 1) {
+            const list = denied.map((w) => `"${w}"`).join(", ");
+            const perms = denied.map((w) => `"${ns}:${w}#use"`).join(", ");
+            return (`Ory: permission denied for shell commands ${list}. ` +
+                `Subject "${ctx.subjectId}" ${shellVerb} them ` +
+                `(permissions ${perms}). ` +
+                shellHint);
+        }
+        return (`Ory: permission denied for shell command "${ctx.shellWord}". ` +
+            `Subject "${ctx.subjectId}" ${shellVerb} "${ctx.shellWord}" ` +
+            `(permission "${ns}:${ctx.shellWord}#use"). ` +
+            shellHint);
+    }
+    const hint = ctx.blocked ? BLOCK_HINT : ADMIN_HINT;
     if (ctx.mcp) {
         const tool = ctx.mcp.toolName
             ? `${ctx.mcp.serverName}/${ctx.mcp.toolName}`
             : ctx.mcp.serverName;
+        const verb = ctx.blocked ? "is explicitly blocked from" : "is not authorized to use";
         return (`Ory: permission denied for MCP server "${ctx.mcp.serverName}". ` +
-            `Subject "${ctx.subjectId}" is not authorized to use "${tool}". ` +
-            ADMIN_HINT);
+            `Subject "${ctx.subjectId}" ${verb} "${tool}". ` +
+            hint);
     }
-    const ns = ctx.namespace ?? "AgentTools";
+    const ns = ctx.namespace ?? "AgentTool";
+    const verb = ctx.blocked ? "is explicitly blocked from invoking" : "is not authorized to invoke";
     return (`Ory: permission denied for "${ctx.tool}". ` +
-        `Subject "${ctx.subjectId}" is not authorized to invoke "${ctx.tool}" ` +
+        `Subject "${ctx.subjectId}" ${verb} "${ctx.tool}" ` +
         `(namespace "${ns}"). ` +
-        ADMIN_HINT);
+        hint);
 }
 /**
  * Short denial summary suitable for compact UI fields (e.g. Gemini's
  * systemMessage which appears inline in the agent's TUI).
  */
 function formatDenialSummary(ctx) {
+    if (ctx.shellTooComplex) {
+        return `Ory: shell command blocked (could not be safely parsed). ${ADMIN_HINT}`;
+    }
+    if (ctx.shellWord) {
+        const denied = ctx.shellDeniedWords && ctx.shellDeniedWords.length > 1
+            ? ctx.shellDeniedWords.map((w) => `"${w}"`).join(", ")
+            : `"${ctx.shellWord}"`;
+        const noun = ctx.shellDeniedWords && ctx.shellDeniedWords.length > 1 ? "commands" : "command";
+        return `Ory: permission denied for shell ${noun} ${denied}. ${ctx.blocked ? BLOCK_HINT : ADMIN_HINT}`;
+    }
+    const hint = ctx.blocked ? BLOCK_HINT : ADMIN_HINT;
     if (ctx.mcp) {
         const tool = ctx.mcp.toolName
             ? `${ctx.mcp.serverName}/${ctx.mcp.toolName}`
             : ctx.mcp.serverName;
-        return `Ory: permission denied for MCP tool "${tool}". ${ADMIN_HINT}`;
+        return `Ory: permission denied for MCP tool "${tool}". ${hint}`;
     }
-    return `Ory: permission denied for "${ctx.tool}". ${ADMIN_HINT}`;
+    return `Ory: permission denied for "${ctx.tool}". ${hint}`;
 }
 /**
  * Thrown by plugins whose hook contract has no native block signal and

package/dist/event-reporter.d.ts

@@ -0,0 +1,77 @@
+import type { ActivityEntry, ActivityStatus, DebugLogger } from "./logger.js";
+export declare const SERVER_ACTIVITY_EVENTS: Set<string>;
+export interface ServerActivityEvent {
+    event_id: string;
+    name: string;
+    status: ActivityStatus;
+    occurred_at: string;
+    session_id?: string;
+    attributes?: Record<string, string | number | boolean | string[]>;
+}
+export interface EventReporterOptions {
+    projectUrl: string;
+    agentSecurityUrl: string;
+    token?: (sessionId?: string, principalKey?: string) => string | undefined;
+    request?: (url: string, init: RequestInit, sessionId?: string, principalKey?: string) => Promise<Response> | undefined;
+    onUnauthorized?: (sessionId: string | undefined, principalKey: string | undefined, rejectedToken: string) => void;
+    logger?: DebugLogger;
+    fetch?: typeof fetch;
+    maxQueueSize?: number;
+    requestTimeoutMs?: number;
+    /** Durable per-event storage. Omitted reporters remain memory-only. */
+    outboxDir?: string;
+    now?: () => number;
+    eventId?: () => string;
+    retryBaseMs?: number;
+    retryMaxMs?: number;
+    random?: () => number;
+}
+export interface PendingEventScope {
+    sessionId?: string;
+    principalKey?: string;
+}
+/** Best-effort delivery of privacy-safe client activity to Agent Security. */
+export declare class AgentSecurityEventReporter {
+    private readonly options;
+    private readonly queue;
+    private readonly fetcher;
+    private readonly maxQueueSize;
+    private readonly requestTimeoutMs;
+    private readonly now;
+    private readonly eventId;
+    private delivery;
+    private scheduled;
+    private activeRequest;
+    private flushDeadline;
+    private suppressRetry;
+    private retryTimer;
+    private retryAttempt;
+    private readonly retryBaseMs;
+    private readonly retryMaxMs;
+    private readonly random;
+    constructor(options: EventReporterOptions);
+    get pending(): number;
+    get pendingScopes(): ReadonlyArray<PendingEventScope>;
+    enqueue(entry: ActivityEntry, principalKey?: string): void;
+    /** Attempt all currently deliverable batches, bounded by the caller's deadline. */
+    flush(timeoutMs?: number): Promise<void>;
+    private schedule;
+    private startDelivery;
+    private scheduleRetry;
+    private drain;
+    private deliver;
+    private request;
+    private persist;
+    private syncOutbox;
+    private acquireOutboxLock;
+    private cleanRenamedLocks;
+    private enforceBounds;
+    private removeFile;
+    private prune;
+    private diagnostic;
+}
+export declare function projectActivityEntry(entry: ActivityEntry, createEventId?: () => string): ServerActivityEvent | undefined;
+/** Stable, non-identifying directory name that prevents cross-project replay. */
+export declare function eventOutboxProjectScope(projectUrl: string): string;
+/** Stable local selector for a bearer without persisting its identifying subject. */
+export declare function eventPrincipalKey(subject: string): string;