@ory/argus 0.13.9 → 1.0.0

package/dist/permissions.js

@@ -9,7 +9,7 @@
  *
  *   1. Runs the check.
  *   2. On a Keto deny (`result.allowed === false`), applies the mode:
- *        - `observe` — record a `permission.observe_deny` audit span,
+ *        - `observe` — record a `permission.observe_deny` audit event,
  *          return `{ kind: "observe", … }` so the caller allows the
  *          tool through.
  *        - `enforce` — return `{ kind: "deny", … }` so the caller blocks.
@@ -29,11 +29,29 @@
  * mode logic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCheckRelation = resolveCheckRelation;
 exports.applyPermissionMode = applyPermissionMode;
 exports.gateToolCall = gateToolCall;
+exports.decomposeAndCheck = decomposeAndCheck;
 exports.checkAndDecide = checkAndDecide;
+const bash_parser_js_1 = require("./bash-parser.js");
 const config_js_1 = require("./config.js");
+const permission_mode_js_1 = require("./permission-mode.js");
+const read_credential_js_1 = require("./read-credential.js");
+const opl_js_1 = require("./opl.js");
+const subject_js_1 = require("./subject.js");
 const tool_catalog_js_1 = require("./tool-catalog.js");
+/**
+ * Map the logical grant relation a caller passes (`use`) onto the relation or
+ * permit Argus actually checks. A `use` check always routes through the
+ * block-aware `access` permit (`use && !blocked`), so an explicit block is
+ * always respected — the permission model must therefore be applied to the
+ * project (done in the Ory Console, Agent Security) for checks to resolve. Any
+ * other relation passes through unchanged.
+ */
+function resolveCheckRelation(relation) {
+    return relation === opl_js_1.RELATION_USERS ? opl_js_1.PERMIT_USE : relation;
+}
 /**
  * Error codes meaning the check call itself was rejected for
  * authentication/authorization reasons — an expired or misconfigured
@@ -42,66 +60,109 @@ const tool_catalog_js_1 = require("./tool-catalog.js");
  * failing open. Infrastructure errors (`network_error`, `rate_limited`,
  * `not_found`, `unknown`) keep the fail-open posture.
  */
-const CHECK_AUTH_REJECTED_CODES = new Set([
+const CHECK_UNTRUSTED_CODES = new Set([
+    // The check reached Ory and was refused — an expired or misconfigured agent
+    // credential, an inactive session, a missing MFA step.
     "forbidden",
     "session_inactive",
     "session_aal2_required",
+    // TLS/certificate verification failed, so we cannot establish that we spoke to
+    // Ory at all. Strictly less trustworthy than the three above — with those we at
+    // least know who refused us. Treating it as a transport blip (fail open) meant a
+    // cert problem silently downgraded an `enforce` project to `observe`, and
+    // breaking TLS was sufficient to disable all tool gating (#218).
+    "tls_error",
 ]);
+/**
+ * Max distinct command words checked per shell command (issue #76). A command
+ * with more than this is pathological (no legitimate command runs 100+ distinct
+ * binaries). Past this we mark the command too-complex (fail-closed in enforce)
+ * rather than issuing an unbounded number of batch round-trips.
+ */
+const MAX_SHELL_WORDS = 100;
+/**
+ * Words per Keto `batchCheckPermission` request. Keto caps a batch at
+ * `limit.max_batch_check_size` (default **10**); a batch over that limit is
+ * rejected with a 400 that would classify as `unknown` and fail the gate OPEN —
+ * silently defeating decomposition, and trivially exploitable by padding a
+ * command with >10 harmless distinct words. So we chunk the word list into
+ * requests of this size and aggregate. Default 10 (Keto's floor); raise via
+ * `ORY_SHELL_BATCH_SIZE` when the project configures a larger Keto limit.
+ */
+const DEFAULT_SHELL_BATCH_SIZE = 10;
+function resolveShellBatchSize() {
+    const raw = process.env.ORY_SHELL_BATCH_SIZE;
+    if (!raw)
+        return DEFAULT_SHELL_BATCH_SIZE;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return DEFAULT_SHELL_BATCH_SIZE;
+    return n;
+}
 function formatSubjectSet(set) {
     if (!set)
         return undefined;
     return `${set.namespace}:${set.object}#${set.relation}`;
 }
-function buildDecisionAttributes(mode, subjectId, subjectSet) {
+function buildDecisionAttributes(mode, subjectId, subjectSet, blockReason) {
     const set = formatSubjectSet(subjectSet);
-    // SubjectSet supersedes subjectId in the span (the printable label is
+    const reason = blockReason ? { blockReason } : {};
+    // SubjectSet supersedes subjectId in activity (the printable label is
     // derivable from it); avoid emitting both so consumers don't need to
     // dedupe.
     if (set)
-        return { permissionMode: mode, subjectSet: set };
+        return { permissionMode: mode, subjectSet: set, ...reason };
     if (subjectId)
-        return { permissionMode: mode, subjectId };
-    return { permissionMode: mode };
+        return { permissionMode: mode, subjectId, ...reason };
+    return { permissionMode: mode, ...reason };
 }
 /**
  * Map an `allowed` boolean from any permission check (plain or MCP)
  * onto a {@link ModeDecision}. When `allowed === false` and the mode
- * is `observe`, emits the `permission.observe_deny` audit span and
+ * is `observe`, emits the `permission.observe_deny` audit event and
  * returns `{ kind: "observe" }` so the caller knows to let the action
  * proceed despite the deny.
  */
 function applyPermissionMode(client, allowed, context = {}) {
     const mode = context.modeOverride ?? (0, config_js_1.resolveConfig)().permissionMode;
-    const spanAttributes = buildDecisionAttributes(mode, context.subjectId, context.subjectSet);
+    const activityAttributes = buildDecisionAttributes(mode, context.subjectId, context.subjectSet, context.blockReason);
     if (allowed)
-        return { kind: "allow", mode, spanAttributes };
+        return { kind: "allow", mode, activityAttributes };
+    const isBlock = context.blockReason === "explicit_block";
     if (mode === "observe") {
-        client.logger.warn("permission.observe_deny", {
+        // An explicit block is still respected *as an observe-mode deny* — it is
+        // logged as a distinct `permission.block_observed` event (so an admin can
+        // see the block would have fired) but, per the observe posture, the tool
+        // still proceeds. Promote to enforce to make blocks actually stop tools.
+        const event = isBlock ? "permission.block_observed" : "permission.observe_deny";
+        client.logger.warn(event, {
             namespace: context.namespace,
             object: context.object,
             relation: context.relation,
             subjectId: context.subjectId,
-            subjectSet: spanAttributes.subjectSet,
-            note: "denied by Ory; allowed by plugin in observe mode",
+            subjectSet: activityAttributes.subjectSet,
+            note: isBlock
+                ? "explicitly blocked by Ory; allowed by plugin in observe mode"
+                : "denied by Ory; allowed by plugin in observe mode",
         });
-        client.tracer.record("permission.observe_deny", "denied", {
+        client.logger.activity(event, "denied", {
             attributes: {
                 namespace: context.namespace,
                 object: context.object,
                 relation: context.relation,
-                ...spanAttributes,
-                ...context.spanAttributes,
+                ...activityAttributes,
+                ...context.activityAttributes,
             },
         });
-        return { kind: "observe", mode: "observe", spanAttributes };
+        return { kind: "observe", mode: "observe", activityAttributes };
     }
-    return { kind: "deny", mode: "enforce", spanAttributes };
+    return { kind: "deny", mode: "enforce", activityAttributes };
 }
 /**
- * Single entry point for the pre-tool-use gate. Applies the
- * `config.auditOnly` kill switch first — when set, Ory is disabled
- * entirely and the caller gets `{ kind: "audit_only" }` back without any
- * permission check (record the invocation as an audit span and proceed).
+ * Single entry point for the pre-tool-use gate. Checks whether Agent Security
+ * is connected first — with no project URL there is
+ * nothing to check against, so the caller gets `{ kind: "not_connected" }`
+ * back and should record the invocation as an audit event and proceed.
  * Otherwise splits the harness's incoming "tool" into two semantic
  * categories:
  *
@@ -111,7 +172,7 @@ function applyPermissionMode(client, allowed, context = {}) {
  *     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`,
+ *     audit event and return — no permission check, no `tool.invoke`,
  *     no `tool.block`.
  *
  *   - **Execution** — every other tool. Delegates to
@@ -123,15 +184,17 @@ function applyPermissionMode(client, allowed, context = {}) {
  * semantics; the new `interactive` kind means "do nothing else."
  */
 async function gateToolCall(client, args) {
-    if ((0, config_js_1.resolveConfig)().auditOnly) {
-        client.logger.debug("tool.audit_only", {
+    const security = (0, config_js_1.resolveConfig)().security;
+    if (!security.connected) {
+        client.logger.debug("tool.security_not_connected", {
             harness: args.harness,
             toolName: args.toolName,
-            note: "audit-only mode — skipping permission check",
+            missing: security.missing,
+            note: "Agent Security is not connected — skipping permission check",
         });
         return {
-            kind: "audit_only",
-            spanAttributes: { auditOnly: true, toolName: args.toolName },
+            kind: "not_connected",
+            activityAttributes: { securityConnected: false, toolName: args.toolName },
         };
     }
     if ((0, tool_catalog_js_1.isInteractiveTool)(args.harness, args.toolName)) {
@@ -140,43 +203,406 @@ async function gateToolCall(client, args) {
             toolName: args.toolName,
             note: "user-interaction primitive — skipping permission check",
         });
-        client.tracer.record("user.interaction", "ok", {
+        client.logger.activity("user.interaction", "ok", {
             attributes: {
                 harness: args.harness,
                 toolName: args.toolName,
                 kind: "tool",
-                ...args.spanAttributes,
+                ...args.activityAttributes,
             },
         });
         return {
             kind: "interactive",
-            spanAttributes: { interactive: true, toolName: args.toolName },
+            activityAttributes: { interactive: true, toolName: args.toolName },
+        };
+    }
+    // Every read below is authenticated by Ory's Oathkeeper `/user` rule, so the
+    // client needs an access token before the first one goes out. On a subprocess
+    // harness this event's process has never run the agent gate, so without this
+    // the only credential is the user's persisted token — and once its hour is up
+    // every read 401s: `session_inactive` denies every tool under `enforce`, and
+    // under `observe` stops checking anything at all (#242).
+    await (0, read_credential_js_1.ensureReadCredential)(client, { harness: args.harness });
+    // Resolve the mode ONCE for this gate — a per-principal Keto permission read
+    // (server → cache → observe), cached with a short TTL. Threaded downstream as
+    // `modeOverride` so the whole gate (top-level check + every decomposed shell
+    // word) decides against one consistent mode. An explicit `modeOverride`
+    // (tests) preempts the server read.
+    const mode = args.modeOverride ??
+        (await (0, permission_mode_js_1.warmPermissionModeCache)(client, {
+            subjectId: args.check.subjectId,
+            subjectSet: args.check.subjectSet,
+        }, {
+            additionalSubjects: [
+                { scope: "agent", subject: (0, subject_js_1.resolveAgentSubject)(client) },
+                { scope: "subagent", subject: (0, subject_js_1.resolveSubAgentSubject)(args.principals?.subAgentClientId) },
+            ].filter((item) => item.subject !== undefined),
+        })).mode;
+    // An explicit block on the acting agent / session / sub-agent / spawn denies
+    // regardless of the user's grants. Run it alongside the user decision rather
+    // than before it, so the extra read costs no serial latency, and let a block
+    // override an allow afterwards.
+    const [decision, blocked] = await Promise.all([
+        args.shellCommand && (0, tool_catalog_js_1.isShellTool)(args.harness, args.toolName)
+            ? // Shell tools (issue #76): decompose the command into per-word sub-checks
+                // in addition to the top-level tool check. Only when the harness marks
+                // this a shell tool AND the raw command was threaded through — otherwise
+                // fall back to the plain single check (never breaks).
+                decomposeAndCheck(client, { ...args, modeOverride: mode })
+            : checkAndDecide(client, args.check, {
+                activityAttributes: args.activityAttributes,
+                modeOverride: mode,
+            }),
+        findBlockedPrincipal(client, {
+            namespace: args.check.namespace,
+            object: args.check.object,
+            principals: args.principals,
+        }),
+    ]);
+    if (!blocked)
+        return decision;
+    // Already denied on the user's own check — nothing to add to the outcome, but
+    // the block is worth recording as the stronger reason it would not have run.
+    if (decision.kind === "deny") {
+        return {
+            ...decision,
+            activityAttributes: {
+                ...decision.activityAttributes,
+                blockReason: "explicit_block",
+                blockedPrincipal: blocked.subject,
+                blockedPrincipalLevel: blocked.level,
+            },
         };
     }
-    return checkAndDecide(client, args.check, {
-        spanAttributes: args.spanAttributes,
+    return applyPrincipalBlock(client, { args, mode, decision, blocked });
+}
+/**
+ * Turn a machine-principal block into the gate's outcome, respecting
+ * `permissionMode` exactly as any other deny does: `enforce` blocks, `observe`
+ * records `permission.block_observed` and passes the tool through.
+ *
+ * The synthesized `PermissionResult` reports the *blocked principal* as the
+ * subject, not the user — the user may well be fully granted, and an audit trail
+ * that named them would send an admin looking at the wrong relation.
+ */
+function applyPrincipalBlock(client, ctx) {
+    const { args, mode, blocked } = ctx;
+    const inner = applyPermissionMode(client, false, {
+        namespace: args.check.namespace,
+        object: args.check.object,
+        relation: opl_js_1.RELATION_BLOCKED_SUBJECTS,
+        subjectId: blocked.subject,
+        blockReason: "explicit_block",
+        modeOverride: mode,
+        activityAttributes: {
+            ...args.activityAttributes,
+            blockedPrincipal: blocked.subject,
+            blockedPrincipalLevel: blocked.level,
+        },
+    });
+    const result = {
+        allowed: false,
+        checkedAt: new Date().toISOString(),
+        check: {
+            namespace: args.check.namespace,
+            object: args.check.object,
+            relation: opl_js_1.RELATION_BLOCKED_SUBJECTS,
+            subjectId: blocked.subject,
+        },
+    };
+    const activityAttributes = {
+        ...inner.activityAttributes,
+        blockedPrincipal: blocked.subject,
+        blockedPrincipalLevel: blocked.level,
+    };
+    return inner.kind === "observe"
+        ? { kind: "observe", result, mode: "observe", activityAttributes }
+        : { kind: "deny", result, mode: "enforce", activityAttributes };
+}
+/**
+ * Gate a shell tool by decomposing its command into the program/builtin words
+ * that will run and checking each as `ShellTool:<word>#use`, on top of the
+ * existing top-level tool check.
+ *
+ * Aggregation: **any deny → deny** (naming the offending word); else any observe
+ * → observe (pass through, per-word `permission.observe_deny` events recorded);
+ * else allow. A too-complex / unparseable command is **fail-closed** in enforce
+ * (deny + alert) and logged-then-passed in observe. A parser-unavailable or
+ * infrastructure error is **fail-open** (top-level decision only) — availability
+ * must not hinge on the parser.
+ */
+async function decomposeAndCheck(client, args) {
+    const top = await checkAndDecide(client, args.check, {
+        activityAttributes: args.activityAttributes,
         modeOverride: args.modeOverride,
     });
+    // Top-level Bash denied (enforce) or unreachable → no point decomposing.
+    if (top.kind === "deny" || top.kind === "fail_open")
+        return top;
+    const mode = top.mode;
+    // The parser is written to be total, but this is a security boundary: if it
+    // ever throws, treat it as too-complex (fail-closed in enforce) rather than
+    // letting the exception bubble to the harness catch, which fails open.
+    let parsed;
+    try {
+        parsed = await (0, bash_parser_js_1.extractBashCommandWords)(args.shellCommand ?? "");
+    }
+    catch {
+        parsed = { words: [], tooComplex: true };
+    }
+    if (parsed.parserUnavailable) {
+        client.logger.warn("bash.parser_unavailable", {
+            harness: args.harness,
+            toolName: args.toolName,
+            note: "shell parser unavailable; falling back to top-level tool check",
+        });
+        client.logger.activity("bash.parser_unavailable", "skipped", {
+            attributes: { harness: args.harness, toolName: args.toolName },
+        });
+        return top;
+    }
+    // Too many distinct words to check safely in one batch — fail closed rather
+    // than send an oversized request that could error into a fail-open fallback.
+    if (parsed.words.length > MAX_SHELL_WORDS) {
+        parsed = { words: [], tooComplex: true };
+    }
+    const subject = { subjectId: args.check.subjectId, subjectSet: args.check.subjectSet };
+    const baseAttrs = buildDecisionAttributes(mode, subject.subjectId, subject.subjectSet);
+    // Decomposition attributes attached to activity so the shell breakdown is
+    // observable in real time — binary/builtin *names* only. The RAW command is
+    // NEVER put in activity; it is written only to the local debug log below,
+    // gated by
+    // `ORY_AGENT_DEBUG`.
+    const decompAttrs = {
+        shellWords: parsed.words,
+        shellCommandCount: parsed.words.length,
+    };
+    // Raw command → local debug log only (DebugLogger writes to stderr + the
+    // optional local log file, and only when ORY_AGENT_DEBUG=true). This keeps
+    // the raw command entirely out of always-filed activity.
+    client.logger.debug("bash.decomposition", {
+        harness: args.harness,
+        toolName: args.toolName,
+        command: args.shellCommand,
+        words: parsed.words,
+        tooComplex: parsed.tooComplex,
+    });
+    // Too-complex → fail-closed in enforce, logged-and-passed in observe.
+    if (parsed.tooComplex) {
+        if (mode === "enforce") {
+            client.logger.warn("bash.too_complex", {
+                harness: args.harness,
+                toolName: args.toolName,
+                note: "shell command could not be safely parsed; enforce mode denies",
+            });
+            return {
+                kind: "deny",
+                result: { allowed: false, checkedAt: new Date().toISOString(), check: args.check },
+                mode: "enforce",
+                activityAttributes: { ...baseAttrs, ...decompAttrs, shellTooComplex: true },
+            };
+        }
+        // observe: record the deny signal, then continue (a partial word set may
+        // still be present and worth logging below).
+        applyPermissionMode(client, false, {
+            namespace: args.check.namespace,
+            object: args.toolName,
+            relation: args.check.relation,
+            subjectId: subject.subjectId,
+            subjectSet: subject.subjectSet,
+            activityAttributes: { ...args.activityAttributes, ...decompAttrs, shellTooComplex: true },
+            modeOverride: args.modeOverride,
+        });
+    }
+    // Check each distinct command word. Chunk into batches no larger than Keto's
+    // `max_batch_check_size` (see DEFAULT_SHELL_BATCH_SIZE) so a word-heavy command
+    // never trips the server's batch limit into a fail-open fallback.
+    const namespace = (0, tool_catalog_js_1.resolveShellCommandNamespace)();
+    const words = parsed.words;
+    const deniedWords = [];
+    const affectedWords = [];
+    let sawObserve = false;
+    const matchedBlocks = new Map();
+    if (words.length > 0) {
+        const batchSize = resolveShellBatchSize();
+        const results = [];
+        for (let start = 0; start < words.length; start += batchSize) {
+            const chunk = words.slice(start, start + batchSize);
+            // Route each word through the block-aware `access` permit (like the
+            // top-level check), so an explicit `ShellTool:<word>#blocked` overrides
+            // a `use` grant. With no block present, `access` == bare `use`.
+            const wordRelation = resolveCheckRelation("users");
+            const checks = chunk.map((word) => ({
+                namespace,
+                object: word,
+                relation: wordRelation,
+                ...subject,
+            }));
+            try {
+                const [batch, blocked] = await Promise.all([
+                    client.batchCheckPermissions(checks, {
+                        activityAttributes: { ...args.activityAttributes, ...decompAttrs, shellDecomposition: true },
+                    }),
+                    findBlockedPrincipals(client, {
+                        namespace,
+                        objects: chunk,
+                        principals: args.principals,
+                    }),
+                ]);
+                results.push(...batch.results);
+                for (const [word, principal] of blocked) {
+                    if (!matchedBlocks.has(word))
+                        matchedBlocks.set(word, principal);
+                }
+            }
+            catch (err) {
+                const oryErr = err;
+                if (mode === "enforce" && oryErr && CHECK_UNTRUSTED_CODES.has(oryErr.code)) {
+                    return {
+                        kind: "deny",
+                        result: { allowed: false, checkedAt: new Date().toISOString(), check: args.check },
+                        mode: "enforce",
+                        activityAttributes: { ...baseAttrs, checkRejected: oryErr.code },
+                    };
+                }
+                // Infrastructure error — fail open to the top-level decision.
+                client.logger.warn("bash.batch_check_failed", {
+                    harness: args.harness,
+                    toolName: args.toolName,
+                    code: oryErr?.code,
+                    note: "shell sub-tool batch check failed; falling back to top-level decision",
+                });
+                return top;
+            }
+        }
+        for (let i = 0; i < words.length; i++) {
+            const word = words[i];
+            const allowed = results[i]?.allowed ?? false;
+            const blocked = matchedBlocks.get(word);
+            const decision = applyPermissionMode(client, blocked ? false : allowed, {
+                namespace,
+                object: word,
+                relation: blocked ? opl_js_1.RELATION_BLOCKED_SUBJECTS : opl_js_1.RELATION_USERS,
+                subjectId: blocked?.subject ?? subject.subjectId,
+                subjectSet: blocked ? undefined : subject.subjectSet,
+                activityAttributes: {
+                    ...args.activityAttributes,
+                    shellWord: word,
+                    ...(blocked ? {
+                        blockedPrincipal: blocked.subject,
+                        blockedPrincipalLevel: blocked.level,
+                    } : {}),
+                },
+                modeOverride: args.modeOverride,
+                blockReason: blocked ? "explicit_block" : undefined,
+            });
+            if (decision.kind === "deny") {
+                deniedWords.push(word);
+                affectedWords.push(word);
+            }
+            else if (decision.kind === "observe") {
+                affectedWords.push(word);
+                sawObserve = true;
+            }
+        }
+    }
+    const primaryBlockedWord = words.find((word) => matchedBlocks.has(word));
+    const primaryBlock = primaryBlockedWord ? matchedBlocks.get(primaryBlockedWord) : undefined;
+    // Aggregate. Enforce: any denied word blocks. Observe: pass through.
+    if (deniedWords.length > 0) {
+        // Disambiguate an explicit block from a plain missing grant on the first
+        // denied word, so the deny event and denial message say "explicitly blocked".
+        const primaryWord = primaryBlockedWord ?? deniedWords[0];
+        const blockReason = primaryBlock
+            ? "explicit_block"
+            : await probeBlockReason(client, {
+                namespace,
+                object: primaryWord,
+                relation: opl_js_1.RELATION_USERS,
+                ...subject,
+            });
+        return {
+            kind: "deny",
+            result: {
+                allowed: false,
+                checkedAt: new Date().toISOString(),
+                check: primaryBlock
+                    ? {
+                        namespace,
+                        object: primaryWord,
+                        relation: opl_js_1.RELATION_BLOCKED_SUBJECTS,
+                        subjectId: primaryBlock.subject,
+                    }
+                    : { namespace, object: primaryWord, relation: opl_js_1.RELATION_USERS, ...subject },
+            },
+            mode: "enforce",
+            activityAttributes: {
+                ...baseAttrs,
+                ...decompAttrs,
+                shellWord: primaryWord,
+                shellDeniedWords: deniedWords,
+                blockReason,
+                ...(primaryBlock ? {
+                    blockedPrincipal: primaryBlock.subject,
+                    blockedPrincipalLevel: primaryBlock.level,
+                } : {}),
+            },
+        };
+    }
+    if (top.kind === "observe" || sawObserve || parsed.tooComplex) {
+        return {
+            kind: "observe",
+            result: top.result,
+            mode: "observe",
+            activityAttributes: {
+                ...baseAttrs,
+                ...decompAttrs,
+                ...(parsed.tooComplex ? { shellTooComplex: true } : {}),
+                ...(affectedWords.length > 0 ? { shellDeniedWords: affectedWords } : {}),
+                ...(primaryBlock && primaryBlockedWord ? {
+                    shellWord: primaryBlockedWord,
+                    blockReason: "explicit_block",
+                    blockedPrincipal: primaryBlock.subject,
+                    blockedPrincipalLevel: primaryBlock.level,
+                } : {}),
+            },
+        };
+    }
+    // Allow: still surface the decomposition so an allowed command's breakdown is
+    // observable too (not just denials).
+    return {
+        kind: "allow",
+        result: top.result,
+        mode: top.mode,
+        activityAttributes: { ...top.activityAttributes, ...decompAttrs },
+    };
 }
 /**
  * Run a permission check and resolve the configured mode against the
  * result. Never throws — infrastructure errors surface as a typed
  * `{ kind: "fail_open" }` decision, and auth-rejected check calls in
  * enforce mode as `{ kind: "deny" }` (see
- * {@link CHECK_AUTH_REJECTED_CODES}).
+ * {@link CHECK_UNTRUSTED_CODES}).
  */
 async function checkAndDecide(client, check, opts = {}) {
-    const mode = opts.modeOverride ?? (0, config_js_1.resolveConfig)().permissionMode;
-    const spanAttributes = buildDecisionAttributes(mode, check.subjectId, check.subjectSet);
+    const resolved = (0, config_js_1.resolveConfig)();
+    const mode = opts.modeOverride ?? resolved.permissionMode;
+    const activityAttributes = buildDecisionAttributes(mode, check.subjectId, check.subjectSet);
+    // Route a `use` grant check through the block-aware `access` permit so
+    // explicit blocks are always respected.
+    const effectiveCheck = {
+        ...check,
+        relation: resolveCheckRelation(check.relation),
+    };
     let result;
     try {
-        result = await client.checkPermission(check, {
-            spanAttributes: opts.spanAttributes,
+        result = await client.checkPermission(effectiveCheck, {
+            activityAttributes: opts.activityAttributes,
         });
     }
     catch (err) {
         const oryErr = err;
-        if (mode === "enforce" && oryErr && CHECK_AUTH_REJECTED_CODES.has(oryErr.code)) {
+        if (mode === "enforce" && oryErr && CHECK_UNTRUSTED_CODES.has(oryErr.code)) {
             // The check call itself was rejected for auth reasons — the
             // result cannot be trusted, so enforce mode must not fail open.
             client.logger.warn("permission.check_rejected", {
@@ -190,23 +616,143 @@ async function checkAndDecide(client, check, opts = {}) {
                 kind: "deny",
                 result: { allowed: false, checkedAt: new Date().toISOString(), check },
                 mode: "enforce",
-                spanAttributes: { ...spanAttributes, checkRejected: oryErr.code },
+                activityAttributes: { ...activityAttributes, checkRejected: oryErr.code },
             };
         }
-        return { kind: "fail_open", error: oryErr, mode, spanAttributes };
+        return { kind: "fail_open", error: oryErr, mode, activityAttributes };
     }
+    // Report the decision against the caller's original check (relation `use`),
+    // not the internal permit rewrite, so callers see the coordinates they passed.
+    result = { ...result, check };
+    // On a deny, disambiguate "explicitly blocked" from "never granted" so the
+    // audit trail and denial messaging can tell them apart. Best-effort.
+    const blockReason = result.allowed
+        ? undefined
+        : await probeBlockReason(client, check);
     const inner = applyPermissionMode(client, result.allowed, {
         namespace: check.namespace,
         object: check.object,
         relation: check.relation,
         subjectId: check.subjectId,
         subjectSet: check.subjectSet,
-        spanAttributes: opts.spanAttributes,
+        activityAttributes: opts.activityAttributes,
         modeOverride: opts.modeOverride,
+        blockReason,
     });
     if (inner.kind === "allow")
-        return { kind: "allow", result, mode: inner.mode, spanAttributes: inner.spanAttributes };
+        return { kind: "allow", result, mode: inner.mode, activityAttributes: inner.activityAttributes };
     if (inner.kind === "observe")
-        return { kind: "observe", result, mode: "observe", spanAttributes: inner.spanAttributes };
-    return { kind: "deny", result, mode: "enforce", spanAttributes: inner.spanAttributes };
+        return { kind: "observe", result, mode: "observe", activityAttributes: inner.activityAttributes };
+    return { kind: "deny", result, mode: "enforce", activityAttributes: inner.activityAttributes };
+}
+const PROJECT_BLOCK_SUBJECT = {
+    subjectSet: {
+        namespace: opl_js_1.PERMISSION_MODE_NAMESPACE,
+        object: opl_js_1.PROJECT_POSTURE_OBJECT,
+        relation: opl_js_1.RELATION_ENFORCED_SUBJECTS,
+    },
+};
+/**
+ * Check whether the project or any acting machine principal is explicitly blocked from this
+ * tool, and name the one that is.
+ *
+ * Project checks are sent separately from the credential-, session-, and
+ * spawn-level forms from `subject.ts`. Older brokers do not understand project
+ * tool blocks; isolating that read keeps their rejection from suppressing the
+ * established machine-principal controls during an asynchronous rollout.
+ *
+ * This can only ever *remove* access: the user's `access` permit remains the
+ * allow decision, so a project that has written no principal blocks behaves
+ * exactly as it did before this pass existed.
+ *
+ * Each read fails open independently. The merged result is empty only when no
+ * successful scope reports a block; a project-read failure cannot erase a
+ * machine hit, and a machine-read failure cannot erase a project hit.
+ */
+async function findBlockedPrincipal(client, args) {
+    return (await findBlockedPrincipals(client, {
+        namespace: args.namespace,
+        objects: [args.object],
+        principals: args.principals,
+    })).get(args.object);
+}
+async function findBlockedPrincipals(client, args) {
+    const p = args.principals ?? {};
+    const machineCandidates = [
+        { level: "agent", ref: (0, subject_js_1.resolveAgentSubject)(client) },
+        { level: "agent_session", ref: (0, subject_js_1.resolveAgentSessionSubject)(client, p.sessionId) },
+        { level: "subagent", ref: (0, subject_js_1.resolveSubAgentSubject)(p.subAgentClientId) },
+        {
+            level: "subagent_spawn",
+            ref: p.subAgentType
+                ? (0, subject_js_1.resolveSubAgentSpawnSubject)(client, {
+                    subAgentClientId: p.subAgentClientId,
+                    subAgentType: p.subAgentType,
+                    perSpawnId: p.perSpawnId,
+                    sessionId: p.sessionId,
+                })
+                : undefined,
+        },
+    ];
+    const presentMachines = machineCandidates.filter((c) => c.ref !== undefined);
+    const read = async (scope, candidates) => {
+        const found = new Map();
+        if (candidates.length === 0)
+            return found;
+        try {
+            const batch = await client.batchCheckPermissions(args.objects.flatMap((object) => candidates.map(({ ref }) => ({
+                namespace: args.namespace,
+                object,
+                relation: opl_js_1.RELATION_BLOCKED_SUBJECTS,
+                ...ref,
+            }))), { activityAttributes: { source: "principal_block", scope } });
+            for (const [i, result] of batch.results.entries()) {
+                const object = args.objects[Math.floor(i / candidates.length)];
+                const candidate = candidates[i % candidates.length];
+                if (object && result.allowed && !result.error && candidate && !found.has(object)) {
+                    found.set(object, {
+                        subject: candidate.level === "project" ? "project" : (0, subject_js_1.subjectLabel)(candidate.ref),
+                        level: candidate.level,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            client.logger.debug("permission.principal_block.failed", {
+                scope,
+                note: `${scope} principal block read failed; falling open for that scope`,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return found;
+    };
+    const [projectBlocks, machineBlocks] = await Promise.all([
+        read("project", [{ level: "project", ref: PROJECT_BLOCK_SUBJECT }]),
+        read("machine", presentMachines),
+    ]);
+    const blocked = new Map(machineBlocks);
+    for (const object of args.objects) {
+        const project = projectBlocks.get(object);
+        if (project)
+            blocked.set(object, project);
+    }
+    return blocked;
+}
+/**
+ * After a denied tool-access check, determine whether the deny was an explicit
+ * block or a plain missing grant by probing the `blocked` relation for the same
+ * subject/object. Uses `checkPermission` (not a literal tuple read) so a block
+ * inherited through a subject-set / group is caught. Best-effort: any error
+ * yields `not_granted` and never changes the decision.
+ */
+async function probeBlockReason(client, check) {
+    try {
+        const probe = await client.checkPermission({ ...check, relation: opl_js_1.RELATION_BLOCKED_SUBJECTS }, { activityAttributes: { source: "block_probe" } });
+        return probe.allowed ? "explicit_block" : "not_granted";
+    }
+    catch {
+        // The probe is diagnostic only; a failure must not upgrade or downgrade
+        // the deny that already stands.
+        return "not_granted";
+    }
 }