@ory/argus 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Persistent configuration for Ory agent plugins.
+ *
+ * Config is stored at ~/.config/ory-agent-plugins/config.json and shared
+ * across all harness plugins. Environment variables always take precedence
+ * over values in the config file.
+ */
+export interface OryOAuth2Tokens {
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix epoch seconds at which the access token expires. */
+    expiresAt: number;
+    /** Subject (sub claim) the token was issued for. */
+    subject?: string;
+    /** Client ID the token was issued under. */
+    clientId?: string;
+    /** Optional id_token (OpenID Connect). */
+    idToken?: string;
+    /** Scope string returned by the token endpoint. */
+    scope?: string;
+}
+/** Credentials for the human user principal (interactive login). */
+export interface OryUserCredentials {
+    /** Persisted OAuth2 tokens from a browser-based PKCE login. */
+    oauth2?: OryOAuth2Tokens;
+}
+/**
+ * Credentials returned by an OAuth2 Dynamic Client Registration flow
+ * (RFC 7591). Persisted so that subsequent dev launches and process
+ * restarts re-use the same agent identity instead of re-registering on
+ * every session.
+ */
+export interface OryAgentDynamicCredentials {
+    /** Issued client_id. */
+    clientId: string;
+    /** Issued client_secret. Omitted for public clients. */
+    clientSecret?: string;
+    /** Bearer used to manage this registration via RFC 7592. */
+    registrationAccessToken?: string;
+    /** RFC 7592 management URI for this registration. */
+    registrationClientUri?: string;
+    /** Unix epoch seconds when this registration was issued. */
+    registeredAt: number;
+    /** Project URL the registration was issued against. */
+    projectUrl: string;
+    /** Harness name baked into the client_name (audit aid). */
+    harness?: string;
+}
+/** Credentials for the AI agent principal (machine identity). */
+export interface OryAgentCredentialsBlock {
+    /** Per-install credentials issued via dynamic client registration. */
+    dynamic?: OryAgentDynamicCredentials;
+    /**
+     * Per-sub-agent dynamic client registrations, keyed by sub-agent type
+     * (e.g. `"Explore"`, `"general-purpose"`). Each entry is a distinct
+     * OAuth2 client registered via RFC 7591 so the audit trail can
+     * attribute actions to a specific sub-agent identity. Reused across
+     * sessions for the same `(projectUrl, subAgentType)` pair.
+     */
+    subAgents?: Record<string, OryAgentDynamicCredentials>;
+}
+export interface OryPluginConfig {
+    projectUrl?: string;
+    apiKey?: string;
+    /** When true, only audit logging is enabled — no auth or permission checks. */
+    auditOnly?: boolean;
+    /** Credentials for the human user (interactive PKCE login). */
+    user?: OryUserCredentials;
+    /** Credentials for the AI agent process (machine identity). */
+    agent?: OryAgentCredentialsBlock;
+}
+/**
+ * Single OS-agnostic data directory for *all* Ory agent plugin state:
+ * the shared config file, persisted DCR credentials, and any harness
+ * asset directories. One place per platform — never split across
+ * `~/.ory/` and `~/.config/`.
+ *
+ *   - Windows: `%APPDATA%/ory-agent-plugins` (e.g.
+ *     `C:\Users\<user>\AppData\Roaming\ory-agent-plugins`).
+ *   - Unix (macOS + Linux): `$XDG_CONFIG_HOME/ory-agent-plugins` when set,
+ *     otherwise `~/.config/ory-agent-plugins`.
+ *
+ * `XDG_CONFIG_HOME` is also honored on Windows when set — useful for
+ * tests and for users who explicitly opt into XDG layout on Windows.
+ */
+export declare function getDataDir(): string;
+/**
+ * Per-harness sub-directory under the shared data dir. Use this for
+ * harness-owned asset trees (e.g. the Claude Code plugin's marketplace
+ * checkout) so all plugin state lives under one root.
+ */
+export declare function getHarnessDataDir(harness: string): string;
+/**
+ * Return the path to the config file.
+ */
+export declare function getConfigPath(): string;
+/**
+ * Load config from the config file. Returns an empty object if the file
+ * does not exist or is invalid.
+ */
+export declare function loadConfig(): OryPluginConfig;
+/**
+ * Save config to the config file. Merges with existing values — only
+ * provided fields are overwritten. Concurrent processes serialize via a
+ * sibling lockfile and the write is atomic (write-temp + rename).
+ *
+ * To clear a field rather than ignore it, set it to `null` in `update`
+ * (e.g. `saveConfig({ user: null })`); `undefined` is treated as
+ * "leave alone" for backwards compatibility.
+ */
+export declare function saveConfig(update: Partial<{
+    [K in keyof OryPluginConfig]: OryPluginConfig[K] | null;
+}>): void;
+/**
+ * Read-modify-write the config under a sibling lockfile. The mutator
+ * receives the current on-disk config and must return the new config.
+ * Concurrent processes serialize on the lock; the write itself is
+ * atomic via write-temp + rename.
+ */
+export declare function mutateConfig(mutator: (current: OryPluginConfig) => OryPluginConfig): void;
+/**
+ * Resolve config by checking environment variables first, then the config file.
+ * Returns the merged result with the source of each value.
+ */
+export declare function resolveConfig(): {
+    projectUrl?: string;
+    apiKey?: string;
+    auditOnly: boolean;
+    projectUrlSource: "env" | "config" | "none";
+    apiKeySource: "env" | "config" | "none";
+};
+/**
+ * Build the "not configured" prompt message for a given harness CLI bin name.
+ */
+export declare function configPromptMessage(binName: string): string;

package/dist/config.js

@@ -0,0 +1,344 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDataDir = getDataDir;
+exports.getHarnessDataDir = getHarnessDataDir;
+exports.getConfigPath = getConfigPath;
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.mutateConfig = mutateConfig;
+exports.resolveConfig = resolveConfig;
+exports.configPromptMessage = configPromptMessage;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Single OS-agnostic data directory for *all* Ory agent plugin state:
+ * the shared config file, persisted DCR credentials, and any harness
+ * asset directories. One place per platform — never split across
+ * `~/.ory/` and `~/.config/`.
+ *
+ *   - Windows: `%APPDATA%/ory-agent-plugins` (e.g.
+ *     `C:\Users\<user>\AppData\Roaming\ory-agent-plugins`).
+ *   - Unix (macOS + Linux): `$XDG_CONFIG_HOME/ory-agent-plugins` when set,
+ *     otherwise `~/.config/ory-agent-plugins`.
+ *
+ * `XDG_CONFIG_HOME` is also honored on Windows when set — useful for
+ * tests and for users who explicitly opt into XDG layout on Windows.
+ */
+function getDataDir() {
+    const xdgOverride = process.env.XDG_CONFIG_HOME?.trim();
+    if (xdgOverride)
+        return path.join(xdgOverride, "ory-agent-plugins");
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA?.trim() ||
+            path.join(getHomeDir(), "AppData", "Roaming");
+        return path.join(appData, "ory-agent-plugins");
+    }
+    return path.join(getHomeDir(), ".config", "ory-agent-plugins");
+}
+/**
+ * Per-harness sub-directory under the shared data dir. Use this for
+ * harness-owned asset trees (e.g. the Claude Code plugin's marketplace
+ * checkout) so all plugin state lives under one root.
+ */
+function getHarnessDataDir(harness) {
+    return path.join(getDataDir(), harness);
+}
+function configDir() {
+    return getDataDir();
+}
+function configFile() {
+    return path.join(configDir(), "config.json");
+}
+function configLockFile() {
+    return configFile() + ".lock";
+}
+/** A lock that is older than this is considered stale and may be broken. */
+const LOCK_STALE_MS = 30_000;
+/** Polling interval while waiting to acquire the lock. */
+const LOCK_POLL_MS = 25;
+/** Maximum total time to wait for the lock before giving up. */
+const LOCK_TIMEOUT_MS = 5_000;
+function getHomeDir() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? "~";
+}
+/**
+ * Return the path to the config file.
+ */
+function getConfigPath() {
+    return configFile();
+}
+/**
+ * Load config from the config file. Returns an empty object if the file
+ * does not exist or is invalid.
+ */
+function loadConfig() {
+    try {
+        const file = configFile();
+        if (!fs.existsSync(file))
+            return {};
+        const raw = fs.readFileSync(file, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            projectUrl: typeof parsed.projectUrl === "string" ? parsed.projectUrl : undefined,
+            apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : undefined,
+            auditOnly: parsed.auditOnly === true ? true : undefined,
+            user: parseUserCredentials(parsed),
+            agent: parseAgentCredentials(parsed),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function parseAgentCredentials(parsed) {
+    const raw = parsed.agent;
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const block = raw;
+    const dynamic = parseAgentDynamicCredentials(block.dynamic);
+    const subAgents = parseSubAgentCredentials(block.subAgents);
+    if (!dynamic && !subAgents)
+        return undefined;
+    return {
+        ...(dynamic ? { dynamic } : {}),
+        ...(subAgents ? { subAgents } : {}),
+    };
+}
+function parseSubAgentCredentials(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const entries = value;
+    const result = {};
+    for (const [key, raw] of Object.entries(entries)) {
+        const creds = parseAgentDynamicCredentials(raw);
+        if (creds)
+            result[key] = creds;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+function parseAgentDynamicCredentials(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const v = value;
+    if (typeof v.clientId !== "string" || v.clientId.length === 0)
+        return undefined;
+    if (typeof v.projectUrl !== "string" || v.projectUrl.length === 0)
+        return undefined;
+    const registeredAt = typeof v.registeredAt === "number" ? v.registeredAt : Math.floor(Date.now() / 1000);
+    return {
+        clientId: v.clientId,
+        clientSecret: typeof v.clientSecret === "string" ? v.clientSecret : undefined,
+        registrationAccessToken: typeof v.registrationAccessToken === "string" ? v.registrationAccessToken : undefined,
+        registrationClientUri: typeof v.registrationClientUri === "string" ? v.registrationClientUri : undefined,
+        registeredAt,
+        projectUrl: v.projectUrl,
+        harness: typeof v.harness === "string" ? v.harness : undefined,
+    };
+}
+function parseUserCredentials(parsed) {
+    // Prefer the new nested shape; fall back to the legacy root-level
+    // `oauth2` block so configs written before the user/agent split still
+    // round-trip. The next saveConfig() drops the legacy field.
+    const nested = parsed.user && typeof parsed.user === "object"
+        ? parsed.user
+        : undefined;
+    const oauth2 = parseOAuth2(nested?.oauth2 ?? parsed.oauth2);
+    if (!oauth2)
+        return undefined;
+    return { oauth2 };
+}
+function parseOAuth2(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const v = value;
+    if (typeof v.accessToken !== "string" || v.accessToken.length === 0)
+        return undefined;
+    if (typeof v.expiresAt !== "number")
+        return undefined;
+    return {
+        accessToken: v.accessToken,
+        refreshToken: typeof v.refreshToken === "string" ? v.refreshToken : undefined,
+        expiresAt: v.expiresAt,
+        subject: typeof v.subject === "string" ? v.subject : undefined,
+        clientId: typeof v.clientId === "string" ? v.clientId : undefined,
+        idToken: typeof v.idToken === "string" ? v.idToken : undefined,
+        scope: typeof v.scope === "string" ? v.scope : undefined,
+    };
+}
+/**
+ * Save config to the config file. Merges with existing values — only
+ * provided fields are overwritten. Concurrent processes serialize via a
+ * sibling lockfile and the write is atomic (write-temp + rename).
+ *
+ * To clear a field rather than ignore it, set it to `null` in `update`
+ * (e.g. `saveConfig({ user: null })`); `undefined` is treated as
+ * "leave alone" for backwards compatibility.
+ */
+function saveConfig(update) {
+    mutateConfig((existing) => mergeConfig(existing, update));
+}
+/**
+ * Read-modify-write the config under a sibling lockfile. The mutator
+ * receives the current on-disk config and must return the new config.
+ * Concurrent processes serialize on the lock; the write itself is
+ * atomic via write-temp + rename.
+ */
+function mutateConfig(mutator) {
+    ensureConfigDir();
+    const lock = acquireLock();
+    try {
+        const existing = loadConfig();
+        const next = mutator(existing);
+        writeConfigAtomic(next);
+    }
+    finally {
+        releaseLock(lock);
+    }
+}
+function mergeConfig(existing, update) {
+    const result = { ...existing };
+    for (const key of Object.keys(update)) {
+        const value = update[key];
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            delete result[key];
+        }
+        else {
+            // Type system can't track the per-key narrowing; the runtime is correct.
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function ensureConfigDir() {
+    const dir = configDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+function acquireLock() {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    const lockPath = configLockFile();
+    for (;;) {
+        try {
+            const fd = fs.openSync(lockPath, "wx", 0o600);
+            fs.writeSync(fd, String(process.pid));
+            return { fd };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // Lock exists — check if it's stale.
+            try {
+                const stat = fs.statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+                    // Best-effort break; if another process beats us, we'll retry.
+                    try {
+                        fs.unlinkSync(lockPath);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    continue;
+                }
+            }
+            catch {
+                // Lockfile vanished between EEXIST and stat — retry immediately.
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for config lock at ${lockPath}. ` +
+                    "Another process may be holding it; remove the file if you are sure no other process is running.");
+            }
+            sleepSync(LOCK_POLL_MS);
+        }
+    }
+}
+const SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(SLEEP_BUF, 0, 0, ms);
+}
+function releaseLock(lock) {
+    try {
+        fs.closeSync(lock.fd);
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        fs.unlinkSync(configLockFile());
+    }
+    catch {
+        /* ignore */
+    }
+}
+function writeConfigAtomic(config) {
+    const target = configFile();
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, target);
+}
+/**
+ * Resolve config by checking environment variables first, then the config file.
+ * Returns the merged result with the source of each value.
+ */
+function resolveConfig() {
+    const file = loadConfig();
+    const envProjectUrl = process.env.ORY_PROJECT_URL;
+    const envApiKey = process.env.ORY_API_KEY;
+    return {
+        projectUrl: envProjectUrl ?? file.projectUrl,
+        apiKey: envApiKey ?? file.apiKey,
+        auditOnly: file.auditOnly === true,
+        projectUrlSource: envProjectUrl ? "env" : file.projectUrl ? "config" : "none",
+        apiKeySource: envApiKey ? "env" : file.apiKey ? "config" : "none",
+    };
+}
+/**
+ * Build the "not configured" prompt message for a given harness CLI bin name.
+ */
+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` +
+        "\n" +
+        "  Option 2 — Continue without authentication (audit logging only):\n" +
+        `    npx ${binName} configure --audit-only\n` +
+        "\n" +
+        `Configuration is saved to ${configFile()} and shared across all agent plugins.`);
+}

package/dist/denial.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Standardized denial messaging for tool calls blocked by Ory Permissions.
+ *
+ * All harness plugins format their deny reason / system message via these
+ * helpers so the human-facing text is consistent: tells the user which
+ * subject lacks which permission, and points them at their Ory Keto admin.
+ *
+ * For harnesses whose plugin contract has no native "block" signal
+ * (currently OpenCode), throw `OryDenialError` from the pre-tool hook —
+ * that aborts execution and surfaces `error.message` to the agent.
+ */
+import type { McpToolIdentifier } from "./mcp.js";
+export interface DenialContext {
+    tool: string;
+    subjectId: string;
+    namespace?: string;
+    mcp?: McpToolIdentifier;
+}
+/**
+ * Span attributes that mark a denial as a security alert.
+ *
+ * Spread these onto the existing `tool.block` span 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.
+ *
+ * The `blocked` field distinguishes harnesses whose plugin contract can
+ * stop the tool (claude-code/codex/gemini-cli exit-2, openclaw `{ block:
+ * true }`) from those that can only advise (opencode throws and relies on
+ * the harness to honor the exception). When `blocked === false` the agent
+ * may still execute the tool, so the alert is the only enforcement signal.
+ */
+export interface AlertAttributes {
+    alert: true;
+    severity: "high";
+    alertKind: "permission_denied";
+    blocked: boolean;
+}
+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
+ * — and any human reading transcripts — can't miss that a security event
+ * was emitted even though the tool was allowed to proceed.
+ */
+export declare function formatAlertMessage(ctx: DenialContext): string;
+/**
+ * Short alert summary suitable for compact UI fields (Gemini's
+ * systemMessage, etc.) when the denial cannot be enforced.
+ */
+export declare function formatAlertSummary(ctx: DenialContext): string;
+/**
+ * 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).
+ */
+export declare function formatDenialMessage(ctx: DenialContext): string;
+/**
+ * Short denial summary suitable for compact UI fields (e.g. Gemini's
+ * systemMessage which appears inline in the agent's TUI).
+ */
+export declare function formatDenialSummary(ctx: DenialContext): string;
+/**
+ * Thrown by plugins whose hook contract has no native block signal and
+ * which fall back to aborting tool execution via an exception (OpenCode
+ * pattern). Because the harness may or may not honor the throw, the
+ * message uses `formatAlertMessage()` so the agent — and any human
+ * reading transcripts — sees explicit "ORY SECURITY ALERT TRIGGERED"
+ * text. The `code` field stays stable for callers/tests.
+ */
+export declare class OryDenialError extends Error {
+    readonly code: "ory_permission_denied";
+    readonly tool: string;
+    readonly subjectId: string;
+    readonly namespace?: string;
+    readonly mcp?: McpToolIdentifier;
+    constructor(ctx: DenialContext);
+}

package/dist/denial.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Standardized denial messaging for tool calls blocked by Ory Permissions.
+ *
+ * All harness plugins format their deny reason / system message via these
+ * helpers so the human-facing text is consistent: tells the user which
+ * subject lacks which permission, and points them at their Ory Keto admin.
+ *
+ * For harnesses whose plugin contract has no native "block" signal
+ * (currently OpenCode), throw `OryDenialError` from the pre-tool hook —
+ * that aborts execution and surfaces `error.message` to the agent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OryDenialError = void 0;
+exports.alertAttributes = alertAttributes;
+exports.formatAlertMessage = formatAlertMessage;
+exports.formatAlertSummary = formatAlertSummary;
+exports.formatDenialMessage = formatDenialMessage;
+exports.formatDenialSummary = formatDenialSummary;
+const ADMIN_HINT = "Contact your Ory Keto administrator to grant the required permission.";
+function alertAttributes(blocked) {
+    return {
+        alert: true,
+        severity: "high",
+        alertKind: "permission_denied",
+        blocked,
+    };
+}
+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
+ * — 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.`;
+}
+/**
+ * Short alert summary suitable for compact UI fields (Gemini's
+ * systemMessage, etc.) when the denial cannot be enforced.
+ */
+function formatAlertSummary(ctx) {
+    return `[${ALERT_PREFIX}] ${formatDenialSummary(ctx)}`;
+}
+/**
+ * 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.mcp) {
+        const tool = ctx.mcp.toolName
+            ? `${ctx.mcp.serverName}/${ctx.mcp.toolName}`
+            : ctx.mcp.serverName;
+        return (`Ory: permission denied for MCP server "${ctx.mcp.serverName}". ` +
+            `Subject "${ctx.subjectId}" is not authorized to use "${tool}". ` +
+            ADMIN_HINT);
+    }
+    const ns = ctx.namespace ?? "AgentTools";
+    return (`Ory: permission denied for "${ctx.tool}". ` +
+        `Subject "${ctx.subjectId}" is not authorized to invoke "${ctx.tool}" ` +
+        `(namespace "${ns}"). ` +
+        ADMIN_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.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 "${ctx.tool}". ${ADMIN_HINT}`;
+}
+/**
+ * Thrown by plugins whose hook contract has no native block signal and
+ * which fall back to aborting tool execution via an exception (OpenCode
+ * pattern). Because the harness may or may not honor the throw, the
+ * message uses `formatAlertMessage()` so the agent — and any human
+ * reading transcripts — sees explicit "ORY SECURITY ALERT TRIGGERED"
+ * text. The `code` field stays stable for callers/tests.
+ */
+class OryDenialError extends Error {
+    code = "ory_permission_denied";
+    tool;
+    subjectId;
+    namespace;
+    mcp;
+    constructor(ctx) {
+        super(formatAlertMessage(ctx));
+        this.name = "OryDenialError";
+        this.tool = ctx.tool;
+        this.subjectId = ctx.subjectId;
+        this.namespace = ctx.namespace;
+        this.mcp = ctx.mcp;
+    }
+}
+exports.OryDenialError = OryDenialError;