@ory/argus 1.5.1 → 1.5.3

package/README.md

@@ -112,8 +112,11 @@ Headless deployments normally supply only `ORY_AGENT_API_KEY` (or an injected ru
 authenticator such as SPIFFE) plus `ORY_PROJECT_URL` and `ORY_AGENT_SECURITY_URL`.
 Before PKCE, Argus resolves the administrator-provisioned subject and opaque root from
 Agent Security, keeps them in process memory, and reuses the root unchanged for child
-lineage. `ORY_AGENT_SUBJECT_ID` and `ORY_AGENT_ROOT_DELEGATION` remain compatibility
-overrides; a complete legacy package skips the context request.
+lineage. Subprocess hooks restore that context from a non-secret, credential-bound
+per-session record in `config.json` instead of requesting it per tool call. Without a
+user, tools are checked as the deployment owner. `ORY_AGENT_SUBJECT_ID` and
+`ORY_AGENT_ROOT_DELEGATION` remain compatibility overrides; a complete legacy package
+skips the context request.
 
 ### Logger
 

package/dist/adapters.js

@@ -119,6 +119,15 @@ async function sessionStart(client, opts) {
                 fetchImpl: opts.runtimeContextFetch,
             });
             rootDelegation = context?.rootDelegation;
+            // Subprocess harnesses gate tools in later processes; let them restore
+            // this context instead of resolving it again on every tool call.
+            if (context) {
+                (0, agent_auth_js_1.saveRuntimeContext)(client, context, {
+                    harness: opts.harness,
+                    sessionId: opts.sessionId ?? client.sessionId,
+                    projectUrl,
+                });
+            }
         }
         catch (err) {
             client.logger.warn("agent.runtime_context.failed", describeThrown(err));
@@ -290,6 +299,13 @@ async function writeUserDelegatesAgent(client, harness, sessionId, env = process
 async function registerSubagent(client, opts) {
     const projectUrl = opts.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
     const subAgentGate = opts.subAgentGate ?? agent_auth_js_1.ensureSubAgentIdentity;
+    // A child of a headless deployment hangs off the deployment root; a
+    // subprocess restores it from the session's persisted runtime context.
+    await (0, agent_auth_js_1.ensureRuntimeContext)(client, {
+        harness: opts.harness,
+        sessionId: opts.sessionId,
+        env: opts.env,
+    });
     let identity;
     try {
         identity = await subAgentGate(client, {
@@ -403,6 +419,12 @@ function gateActivityAttributes(opts) {
  * separately reports actual execution; {@link gate} adds the standard events.
  */
 async function decideTool(client, opts) {
+    if ((0, config_js_1.isSecurityConnected)()) {
+        // A subprocess hook of a headless deployment starts without the context
+        // its session-start process resolved. Restore it (or resolve it once) so
+        // the deployment owner, not a session placeholder, is checked (#338).
+        await (0, agent_auth_js_1.ensureRuntimeContext)(client, { harness: opts.harness, allowResolve: true });
+    }
     const namespace = resolveNamespace();
     const subjectRef = (0, subject_js_1.resolveUserSubject)(client, opts.subjectFallback);
     const label = (0, subject_js_1.subjectLabel)(subjectRef);

package/dist/agent-auth.d.ts

@@ -25,6 +25,51 @@ export interface ResolvePreprovisionedRuntimeContextOptions {
 }
 /** Resolve missing headless deployment metadata using the existing runtime proof. */
 export declare function resolvePreprovisionedRuntimeContext(client: OryAgentClient, options: ResolvePreprovisionedRuntimeContextOptions): Promise<RuntimeContext | undefined>;
+/**
+ * SHA-256 binding of a runtime credential for persisted runtime context. It is
+ * derived from the credential's existing non-secret fingerprint and is never
+ * the secret itself. Credentials without a stable fingerprint (programmatic
+ * injected authenticators) are not persisted.
+ */
+export declare function runtimeCredentialBinding(credential: RuntimeCredential | undefined): string | undefined;
+export interface SaveRuntimeContextOptions {
+    harness: string;
+    sessionId?: string;
+    /** Project the context was resolved for. Defaults to the client's project. */
+    projectUrl?: string;
+}
+/** Persist a resolved runtime context for later hook processes of the same session. */
+export declare function saveRuntimeContext(client: OryAgentClient, context: RuntimeContext, options: SaveRuntimeContextOptions): boolean;
+export interface RestoreRuntimeContextOptions {
+    harness: string;
+    sessionId?: string;
+    /** Authoritative agent type required of the context. Defaults to `harness`. */
+    agentType?: string;
+}
+/**
+ * Restore a persisted runtime context into a fresh client. Loads only: it
+ * succeeds when the persisted entry is bound to the active runtime credential,
+ * the client's project and Agent Security URLs, and the expected agent type.
+ */
+export declare function restoreRuntimeContext(client: OryAgentClient, options: RestoreRuntimeContextOptions): RuntimeContext | undefined;
+export interface EnsureRuntimeContextOptions extends RestoreRuntimeContextOptions {
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    /** Allow one bounded runtime-context request when nothing is persisted. */
+    allowResolve?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Make the headless deployment context available to a tool or event path.
+ *
+ * Restores the session's persisted context (no network). When none exists —
+ * for example a harness that skipped its session-start hook — and
+ * `allowResolve` is set, it resolves the context once with a bounded request
+ * and persists it so later hook processes only load. A failed resolution is
+ * not retried by the same client for {@link LAZY_RUNTIME_CONTEXT_RETRY_MS}.
+ * Never throws.
+ */
+export declare function ensureRuntimeContext(client: OryAgentClient, options: EnsureRuntimeContextOptions): Promise<RuntimeContext | undefined>;
 /**
  * Delegation context handed to {@link registerAgentClient} so the freshly
  * minted OAuth2 client is stamped with its delegator at the identity layer.
@@ -356,6 +401,8 @@ export interface EnsureAgentIdentityOptions {
      * What prompted this resolution, recorded on the `agent.auth` activity event. Absent for
      * the session-start gate; `read_credential` when the tool gate resolved the
      * identity because it needed a credential to authenticate a permission read.
+     * A triggered resolution that cleanly loads a stored credential records no
+     * activity; only its failures and warnings do.
      */
     trigger?: string;
 }
@@ -363,8 +410,10 @@ export interface EnsureAgentIdentityOptions {
  * Resolve the agent's credentials and attach them to the client.
  *
  * Always returns the resolved credentials; never throws and never blocks.
- * Emits exactly one `agent.auth` activity event so the audit trail records whether
- * the agent identity was available for the session.
+ * Emits one `agent.auth` activity event so the audit trail records whether the
+ * agent identity was available for the session. A `trigger`ed (tool-path)
+ * resolution emits it only when the credential is missing or resolved with
+ * warnings; a clean reload of the stored credential is logged at debug level.
  */
 export declare function ensureAgentIdentity(client: OryAgentClient, options?: EnsureAgentIdentityOptions): Promise<AgentCredentials>;
 /**

package/dist/agent-auth.js

@@ -16,6 +16,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SESSION_RETENTION = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = void 0;
 exports.resolvePreprovisionedRootDelegation = resolvePreprovisionedRootDelegation;
 exports.resolvePreprovisionedRuntimeContext = resolvePreprovisionedRuntimeContext;
+exports.runtimeCredentialBinding = runtimeCredentialBinding;
+exports.saveRuntimeContext = saveRuntimeContext;
+exports.restoreRuntimeContext = restoreRuntimeContext;
+exports.ensureRuntimeContext = ensureRuntimeContext;
 exports.resolveRuntimeAgentCredentials = resolveRuntimeAgentCredentials;
 exports._resetAgentCredentialsCache = _resetAgentCredentialsCache;
 exports.invalidateAgentAccessToken = invalidateAgentAccessToken;
@@ -46,6 +50,7 @@ exports.resolveAgentCredentials = resolveAgentCredentials;
 exports.fetchClientCredentialsToken = fetchClientCredentialsToken;
 exports.ensureAgentIdentity = ensureAgentIdentity;
 exports.ensureSubAgentIdentity = ensureSubAgentIdentity;
+const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -53,6 +58,7 @@ const promises_2 = require("node:timers/promises");
 const client_1 = require("@ory/client");
 const config_js_1 = require("./config.js");
 const branding_js_1 = require("./branding.js");
+const context_js_1 = require("./context.js");
 const subject_js_1 = require("./subject.js");
 const runtime_credential_js_1 = require("./runtime-credential.js");
 const ENROLLMENT_LOCK_STALE_MS = 120_000;
@@ -147,12 +153,192 @@ async function resolvePreprovisionedRuntimeContext(client, options) {
     if (context.agentType !== options.expectedAgentType) {
         throw new Error("Runtime context agent type does not match the adapter type");
     }
+    activateRuntimeContext(client, credential, context);
+    return context;
+}
+function activateRuntimeContext(client, credential, context) {
     const contextualCredential = { ...credential, subject: context.subjectId };
     validatedRuntimeSubjects.add(contextualCredential);
     client.setRuntimeCredential(contextualCredential);
     client.setRuntimeContext(context);
+}
+// ─── Persisted runtime context (subprocess hooks) ────────────────────
+//
+// Subprocess harnesses run every hook event in a new process, so the context
+// resolved at session start would otherwise exist only in the session-start
+// process. The non-secret context is persisted per (harness, session) and bound
+// to a fingerprint of the runtime credential plus the canonical project and
+// Agent Security URLs; a rotated key or another project never reuses it.
+const LAZY_RUNTIME_CONTEXT_TIMEOUT_MS = 10_000;
+const LAZY_RUNTIME_CONTEXT_RETRY_MS = 60_000;
+const lazyRuntimeContextAttempts = new WeakMap();
+/**
+ * SHA-256 binding of a runtime credential for persisted runtime context. It is
+ * derived from the credential's existing non-secret fingerprint and is never
+ * the secret itself. Credentials without a stable fingerprint (programmatic
+ * injected authenticators) are not persisted.
+ */
+function runtimeCredentialBinding(credential) {
+    let source;
+    if (credential?.kind === "talos" && credential.apiKeyFingerprint) {
+        source = `talos\0${credential.apiKeyFingerprint}`;
+    }
+    else if (credential?.kind === "injected" && credential.spiffeIdFingerprint) {
+        source = `spiffe\0${credential.spiffeIdFingerprint}`;
+    }
+    return source ? (0, node_crypto_1.createHash)("sha256").update(source).digest("hex") : undefined;
+}
+function canonicalUrlOrUndefined(url) {
+    if (!url)
+        return undefined;
+    try {
+        return (0, runtime_credential_js_1.canonicalProjectUrl)(url);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Persist a resolved runtime context for later hook processes of the same session. */
+function saveRuntimeContext(client, context, options) {
+    const credential = runtimeCredentialBinding(client.rootRuntimeCredential);
+    const projectUrl = canonicalUrlOrUndefined(options.projectUrl ?? client.projectUrl);
+    const agentSecurityUrl = canonicalUrlOrUndefined(client.agentSecurityUrl);
+    if (!credential || !projectUrl || !agentSecurityUrl)
+        return false;
+    const sessionKey = options.sessionId?.trim() || config_js_1.SESSIONLESS_KEY;
+    const entry = {
+        credential,
+        projectUrl,
+        agentSecurityUrl,
+        subjectId: context.subjectId,
+        rootDelegation: context.rootDelegation,
+        deploymentId: context.deploymentId,
+        agentType: context.agentType,
+    };
+    (0, config_js_1.mutateConfig)((current) => {
+        const existing = current.runtimeContexts?.[options.harness] ?? {};
+        const previous = existing[sessionKey];
+        if (previous && JSON.stringify(previous) === JSON.stringify(entry))
+            return current;
+        const merged = { ...existing };
+        delete merged[sessionKey];
+        merged[sessionKey] = entry;
+        const keys = Object.keys(merged);
+        const kept = keys.slice(Math.max(0, keys.length - config_js_1.DELEGATION_NODE_HISTORY));
+        return {
+            ...current,
+            runtimeContexts: {
+                ...(current.runtimeContexts ?? {}),
+                [options.harness]: Object.fromEntries(kept.map((key) => [key, merged[key]])),
+            },
+        };
+    });
+    return true;
+}
+/**
+ * Restore a persisted runtime context into a fresh client. Loads only: it
+ * succeeds when the persisted entry is bound to the active runtime credential,
+ * the client's project and Agent Security URLs, and the expected agent type.
+ */
+function restoreRuntimeContext(client, options) {
+    const active = client.runtimeContext;
+    if (active)
+        return active;
+    const credential = client.rootRuntimeCredential;
+    const binding = runtimeCredentialBinding(credential);
+    if (!credential || !binding)
+        return undefined;
+    const sessionKey = (options.sessionId ?? client.sessionId)?.trim() || config_js_1.SESSIONLESS_KEY;
+    const entry = (0, config_js_1.loadConfig)().runtimeContexts?.[options.harness]?.[sessionKey];
+    if (!entry ||
+        entry.credential !== binding ||
+        entry.projectUrl !== canonicalUrlOrUndefined(client.projectUrl) ||
+        entry.agentSecurityUrl !== canonicalUrlOrUndefined(client.agentSecurityUrl) ||
+        entry.agentType !== (options.agentType ?? options.harness)) {
+        return undefined;
+    }
+    let context;
+    try {
+        context = parseRuntimeContext({
+            agent_type: entry.agentType,
+            authenticated: true,
+            deployment_id: entry.deploymentId,
+            root_delegation: entry.rootDelegation,
+            subject_id: entry.subjectId,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    activateRuntimeContext(client, credential, context);
     return context;
 }
+/**
+ * True when a hook may act for a headless deployment owner: an
+ * administrator-supplied runtime credential (`ORY_AGENT_API_KEY` or an injected
+ * authenticator) is configured, no user principal is known, and no complete
+ * environment package already identifies the runtime. A Talos credential the
+ * plugin enrolled for an interactive user never qualifies.
+ */
+function runtimeOwnerContextEligible(client, env) {
+    if (client.userPrincipal.subject || env.ORY_USER_SUBJECT_ID?.trim())
+        return false;
+    if (resolvePreprovisionedRootDelegation(env, undefined, client.runtimeCredential))
+        return false;
+    return Boolean(env.ORY_AGENT_API_KEY?.trim()) || client.rootRuntimeCredential?.kind === "injected";
+}
+/**
+ * Make the headless deployment context available to a tool or event path.
+ *
+ * Restores the session's persisted context (no network). When none exists —
+ * for example a harness that skipped its session-start hook — and
+ * `allowResolve` is set, it resolves the context once with a bounded request
+ * and persists it so later hook processes only load. A failed resolution is
+ * not retried by the same client for {@link LAZY_RUNTIME_CONTEXT_RETRY_MS}.
+ * Never throws.
+ */
+async function ensureRuntimeContext(client, options) {
+    const active = client.runtimeContext;
+    if (active)
+        return active;
+    const env = options.env ?? process.env;
+    try {
+        if (!runtimeOwnerContextEligible(client, env))
+            return undefined;
+        const restored = restoreRuntimeContext(client, options);
+        // Resolve only as the root runtime: an acting child credential must not
+        // stand in for its deployment's root.
+        if (restored || !options.allowResolve || (0, context_js_1.currentSessionContext)().runtimeCredential) {
+            return restored;
+        }
+        const sessionKey = (options.sessionId ?? client.sessionId)?.trim() || config_js_1.SESSIONLESS_KEY;
+        const attempts = lazyRuntimeContextAttempts.get(client) ?? new Map();
+        lazyRuntimeContextAttempts.set(client, attempts);
+        const lastAttempt = attempts.get(sessionKey);
+        if (lastAttempt !== undefined && Date.now() - lastAttempt < LAZY_RUNTIME_CONTEXT_RETRY_MS) {
+            return undefined;
+        }
+        attempts.set(sessionKey, Date.now());
+        const context = await resolvePreprovisionedRuntimeContext(client, {
+            projectUrl: client.projectUrl,
+            expectedAgentType: options.agentType ?? options.harness,
+            env,
+            fetchImpl: options.fetchImpl,
+            signal: AbortSignal.timeout(options.timeoutMs ?? LAZY_RUNTIME_CONTEXT_TIMEOUT_MS),
+        });
+        if (context) {
+            attempts.delete(sessionKey);
+            saveRuntimeContext(client, context, { harness: options.harness, sessionId: sessionKey });
+        }
+        return context;
+    }
+    catch (err) {
+        client.logger.warn("agent.runtime_context.unavailable", {
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+    }
+}
 async function withEnrollmentLock(identity, work) {
     const lockRoot = (0, node_path_1.join)((0, config_js_1.getDataDir)(), "runtime-credential-locks");
     const lockPath = (0, node_path_1.join)(lockRoot, `${(0, runtime_credential_js_1.credentialAccount)(identity)}.lock`);
@@ -1102,8 +1288,10 @@ async function fetchClientCredentialsToken(args) {
  * Resolve the agent's credentials and attach them to the client.
  *
  * Always returns the resolved credentials; never throws and never blocks.
- * Emits exactly one `agent.auth` activity event so the audit trail records whether
- * the agent identity was available for the session.
+ * Emits one `agent.auth` activity event so the audit trail records whether the
+ * agent identity was available for the session. A `trigger`ed (tool-path)
+ * resolution emits it only when the credential is missing or resolved with
+ * warnings; a clean reload of the stored credential is logged at debug level.
  */
 async function ensureAgentIdentity(client, options = {}) {
     const sessionId = options.sessionId ?? client.sessionId;
@@ -1239,6 +1427,19 @@ async function ensureAgentIdentity(client, options = {}) {
     // resolver match" should not clear it. With nothing set, the read path falls
     // back to the rehydrated user token (see `buildApis`).
     const sessionKey = sessionId?.trim() || config_js_1.SESSIONLESS_KEY;
+    // Subprocess harnesses start a fresh process for every hook, so a tool-path
+    // resolution that merely reloads the stored credential would otherwise record
+    // one `agent.auth` per tool call. Only the session-start gate, a failure, or a
+    // partial resolution is an authentication outcome worth auditing.
+    if (options.trigger && creds.kind !== "none" && !creds.warnings?.length) {
+        client.logger.debug("agent.auth.loaded", {
+            kind: creds.kind,
+            sessionKey,
+            trigger: options.trigger,
+            ...(creds.subject ? { subject: creds.subject } : {}),
+        });
+        return creds;
+    }
     client.logger.activity("agent.auth", creds.kind === "none" ? "skipped" : "ok", {
         attributes: {
             kind: creds.kind,

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "repo": "ory-agent-plugins",
-  "commit": "e0d37342a77d3ffe2922926142992924b126154e",
-  "commitShort": "e0d37342",
+  "commit": "6d5a4dd670531925d1a0807d25406ccc4db24bf5",
+  "commitShort": "6d5a4dd6",
   "branch": "main",
-  "commitDate": "2026-10-21T08:37:08-07:00",
+  "commitDate": "2026-10-22T14:21:25-07:00",
   "dirty": false,
-  "builtAt": "2026-10-21T15:41:02.900Z"
+  "builtAt": "2026-10-22T21:25:21.096Z"
 }

package/dist/client.d.ts

@@ -140,6 +140,8 @@ export declare class OryAgentClient {
     constructor(config: OryAgentConfig);
     /** Build a fresh set of Ory API instances using the current agent token. */
     private buildApis;
+    /** Ory project URL this client sends with Agent Security requests. */
+    get projectUrl(): string;
     /** Canonical broker origin, with the shipped project URL fallback applied. */
     get agentSecurityUrl(): string;
     private buildBrokerPermissionTransport;
@@ -154,9 +156,22 @@ export declare class OryAgentClient {
     get agentPrincipal(): PrincipalIdentity;
     /** Active noninteractive broker credential. It is process memory only. */
     get runtimeCredential(): RuntimeCredential | undefined;
+    /** The session's root broker credential, ignoring an ambient child credential. */
+    get rootRuntimeCredential(): RuntimeCredential | undefined;
     get hasRuntimeCredential(): boolean;
-    /** Process-local deployment context. It is never persisted or copied to the environment. */
+    /**
+     * Active deployment context. It is never copied to the environment; a
+     * subprocess harness restores it from the credential-bound, non-secret
+     * per-session record written at session start (see `restoreRuntimeContext`).
+     */
     get runtimeContext(): RuntimeContext | undefined;
+    /**
+     * True when this client runs as an administrator-preprovisioned runtime whose
+     * owner only the broker knows: a resolved runtime context, or a complete
+     * `ORY_AGENT_ROOT_DELEGATION` + `ORY_AGENT_SUBJECT_ID` environment package
+     * with its runtime credential.
+     */
+    get actsForRuntimeOwner(): boolean;
     get runtimeRootDelegation(): string | undefined;
     setRuntimeContext(context: RuntimeContext): void;
     setRuntimeCredential(credential: RuntimeCredential | undefined): void;

package/dist/client.js

@@ -180,6 +180,10 @@ class OryAgentClient {
             permission: this.buildBrokerPermissionTransport(),
         };
     }
+    /** Ory project URL this client sends with Agent Security requests. */
+    get projectUrl() {
+        return this.config.projectUrl;
+    }
     /** Canonical broker origin, with the shipped project URL fallback applied. */
     get agentSecurityUrl() {
         return this.config.agentSecurityUrl ?? this.config.projectUrl;
@@ -268,7 +272,7 @@ class OryAgentClient {
             }
             // A preprovisioned runtime with no local user: the broker derives the
             // owner from the authenticated runtime, and no owner ID is sent.
-            if (userSubject === undefined && subject.object === subject_js_1.RUNTIME_OWNER_SUBJECT && this._runtimeContext) {
+            if (userSubject === undefined && subject.object === subject_js_1.RUNTIME_OWNER_SUBJECT && this.actsForRuntimeOwner) {
                 return { kind: "owner", namespace: subject.namespace };
             }
             throw httpError(403, "Permission owner does not match the authenticated user");
@@ -331,9 +335,11 @@ class OryAgentClient {
     }
     /** Active noninteractive broker credential. It is process memory only. */
     get runtimeCredential() {
+        return (0, context_js_1.currentSessionContext)().runtimeCredential ?? this.rootRuntimeCredential;
+    }
+    /** The session's root broker credential, ignoring an ambient child credential. */
+    get rootRuntimeCredential() {
         const context = (0, context_js_1.currentSessionContext)();
-        if (context.runtimeCredential)
-            return context.runtimeCredential;
         if (context.sessionId) {
             const credential = this._runtimeCredentialsBySession.get(context.sessionId);
             if (credential)
@@ -341,7 +347,7 @@ class OryAgentClient {
         }
         if (this._runtimeCredential)
             return this._runtimeCredential;
-        const principal = this.agentPrincipal;
+        const principal = this.agentPrincipalForSession(this.sessionId);
         return principal.token
             ? (0, runtime_credential_js_1.talosRuntimeCredential)(principal.token, { subject: principal.subject })
             : undefined;
@@ -349,10 +355,25 @@ class OryAgentClient {
     get hasRuntimeCredential() {
         return this.runtimeCredential !== undefined;
     }
-    /** Process-local deployment context. It is never persisted or copied to the environment. */
+    /**
+     * Active deployment context. It is never copied to the environment; a
+     * subprocess harness restores it from the credential-bound, non-secret
+     * per-session record written at session start (see `restoreRuntimeContext`).
+     */
     get runtimeContext() {
         return this._runtimeContext ? { ...this._runtimeContext } : undefined;
     }
+    /**
+     * True when this client runs as an administrator-preprovisioned runtime whose
+     * owner only the broker knows: a resolved runtime context, or a complete
+     * `ORY_AGENT_ROOT_DELEGATION` + `ORY_AGENT_SUBJECT_ID` environment package
+     * with its runtime credential.
+     */
+    get actsForRuntimeOwner() {
+        if (this._runtimeContext)
+            return true;
+        return (0, agent_auth_js_1.resolvePreprovisionedRootDelegation)(process.env, undefined, this.runtimeCredential) !== undefined;
+    }
     get runtimeRootDelegation() {
         return this._runtimeContext?.rootDelegation;
     }

package/dist/config.d.ts

@@ -104,6 +104,20 @@ export interface OryAgentDynamicCredentials {
  * bounded so a long-lived install's config doesn't grow without limit.
  */
 export declare const DELEGATION_NODE_HISTORY = 10;
+/**
+ * A runtime context resolved for one headless session, persisted without any
+ * secret. `credential` is a SHA-256 binding of the runtime credential (never the
+ * credential itself); `projectUrl` and `agentSecurityUrl` are canonical URLs.
+ */
+export interface PersistedRuntimeContext {
+    credential: string;
+    projectUrl: string;
+    agentSecurityUrl: string;
+    subjectId: string;
+    rootDelegation: string;
+    deploymentId: string;
+    agentType: string;
+}
 /** Opaque, administrator-provisioned root delegation node for headless agents. */
 export declare const AGENT_ROOT_DELEGATION_ENV_VAR = "ORY_AGENT_ROOT_DELEGATION";
 /** Validate an opaque broker node without interpreting its server-owned format. */
@@ -213,6 +227,14 @@ export interface OryPluginConfig {
     workspaceName?: string;
     /** Opaque broker node ids keyed by harness and session. Contains no credentials. */
     delegationAnchors?: Record<string, Record<string, string>>;
+    /**
+     * Non-secret headless deployment context keyed by harness and session, so a
+     * later subprocess hook of the same session can act for the deployment owner
+     * without a runtime-context request per tool call. Each entry is bound to a
+     * fingerprint of the runtime credential and to the project and Agent Security
+     * URLs it was resolved for; a different credential or project never reuses it.
+     */
+    runtimeContexts?: Record<string, Record<string, PersistedRuntimeContext>>;
     /**
      * Public OAuth2 client id used by the user PKCE browser flow when
      * the interactive user login runs (every session). The client must be registered ahead of time

package/dist/config.js

@@ -62,6 +62,46 @@ const cli_invocation_js_1 = require("./cli-invocation.js");
  * bounded so a long-lived install's config doesn't grow without limit.
  */
 exports.DELEGATION_NODE_HISTORY = 10;
+const PERSISTED_RUNTIME_CONTEXT_KEYS = [
+    "agentSecurityUrl",
+    "agentType",
+    "credential",
+    "deploymentId",
+    "projectUrl",
+    "rootDelegation",
+    "subjectId",
+];
+function parsePersistedRuntimeContext(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const entry = {};
+    for (const key of PERSISTED_RUNTIME_CONTEXT_KEYS) {
+        const field = raw[key];
+        if (typeof field !== "string" || !field.trim())
+            return undefined;
+        entry[key] = field;
+    }
+    return entry;
+}
+function parseRuntimeContexts(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const result = {};
+    for (const [harness, rawSessions] of Object.entries(value)) {
+        if (!rawSessions || typeof rawSessions !== "object" || Array.isArray(rawSessions))
+            continue;
+        const sessions = {};
+        for (const [session, rawEntry] of Object.entries(rawSessions)) {
+            const entry = parsePersistedRuntimeContext(rawEntry);
+            if (entry)
+                sessions[session] = entry;
+        }
+        if (Object.keys(sessions).length > 0)
+            result[harness] = sessions;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 /** Opaque, administrator-provisioned root delegation node for headless agents. */
 exports.AGENT_ROOT_DELEGATION_ENV_VAR = "ORY_AGENT_ROOT_DELEGATION";
 /** Validate an opaque broker node without interpreting its server-owned format. */
@@ -197,6 +237,7 @@ function loadConfig() {
                 : undefined,
             installedHarnesses: parseInstalledHarnesses(parsed.installedHarnesses),
             delegationAnchors: parseDelegationAnchors(parsed.delegationAnchors),
+            runtimeContexts: parseRuntimeContexts(parsed.runtimeContexts),
             user: parseUserCredentials(parsed),
             agent: parseAgentCredentials(parsed),
         };
@@ -928,6 +969,7 @@ function compactPersistedConfig(config) {
             ? { installedHarnesses: config.installedHarnesses }
             : {}),
         ...(config.delegationAnchors ? { delegationAnchors: config.delegationAnchors } : {}),
+        ...(config.runtimeContexts ? { runtimeContexts: config.runtimeContexts } : {}),
         ...(user ? { user } : {}),
         ...(agent ? { agent } : {}),
     };

package/dist/runtime-credential.d.ts

@@ -48,6 +48,8 @@ export interface RuntimeCredential {
     subject?: string;
     /** @internal Non-secret binding used to recognize the same Talos key after re-resolution. */
     apiKeyFingerprint?: string;
+    /** @internal Non-secret binding of an environment-configured SPIFFE workload identity. */
+    spiffeIdFingerprint?: string;
     authenticate: RuntimeRequestAuthenticator;
 }
 export interface ResolveRuntimeCredentialOptions {

package/dist/runtime-credential.js

@@ -666,6 +666,7 @@ function resolveRuntimeCredential(options = {}) {
         return {
             kind: "injected",
             ...(options.subject ? { subject: options.subject } : {}),
+            spiffeIdFingerprint: (0, node_crypto_1.createHash)("sha256").update(expectedClientSpiffeId).digest("hex"),
             authenticate: createSpiffeFileRequestAuthenticator({
                 ...(generationPath ? {
                     generationPath,

package/dist/subject.d.ts

@@ -61,8 +61,8 @@ export declare function runWithUserSubject<T>(subject: string | undefined, fn: (
  * Resolve the user subject for permission checks. Prefers a per-call
  * override installed via {@link runWithUserSubject}, then the user
  * login's `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
- * legacy `ORY_AGENT_SUBJECT_ID`, then the deployment owner of a preprovisioned
- * runtime ({@link RUNTIME_OWNER_SUBJECT}), then the caller-supplied `fallback`
+ * deployment owner of a preprovisioned runtime ({@link RUNTIME_OWNER_SUBJECT}),
+ * then the legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).
  *
  * Always returns a SubjectSet. A resolved principal is addressed under the

package/dist/subject.js

@@ -80,8 +80,8 @@ function subjectSet(namespace, object) {
  * Resolve the user subject for permission checks. Prefers a per-call
  * override installed via {@link runWithUserSubject}, then the user
  * login's `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
- * legacy `ORY_AGENT_SUBJECT_ID`, then the deployment owner of a preprovisioned
- * runtime ({@link RUNTIME_OWNER_SUBJECT}), then the caller-supplied `fallback`
+ * deployment owner of a preprovisioned runtime ({@link RUNTIME_OWNER_SUBJECT}),
+ * then the legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).
  *
  * Always returns a SubjectSet. A resolved principal is addressed under the
@@ -92,22 +92,26 @@ function subjectSet(namespace, object) {
  * marker that must never match a stored tuple.
  */
 function resolveUserSubject(client, fallback) {
-    const principal = perCallUserSubject.getStore()
-        ?? client.userPrincipal.subject
-        ?? process.env.ORY_USER_SUBJECT_ID
-        // Validated, not read raw: the same value feeds the agent subject, so a
-        // value rejected there must not slip in here (#241).
-        ?? readAgentSubjectOverride();
     const ns = process.env.ORY_USER_SUBJECT_NAMESPACE?.trim()
         || client.userSubjectNamespace
         || exports.DEFAULT_USER_SUBJECT_NAMESPACE;
+    const principal = perCallUserSubject.getStore()
+        ?? client.userPrincipal.subject
+        ?? process.env.ORY_USER_SUBJECT_ID;
     if (principal)
         return subjectSet(ns, principal);
     // A preprovisioned runtime acts for its deployment's owner, whom only the
     // broker knows. Without this, a headless deployment resolves no subject and
-    // every native tool is denied in enforce mode (#338).
-    if (client.runtimeContext)
+    // every native tool is denied in enforce mode (#338). Its
+    // `ORY_AGENT_SUBJECT_ID` names the runtime Agent, never a user, so the legacy
+    // fallback below does not apply to it.
+    if (client.actsForRuntimeOwner)
         return subjectSet(ns, exports.RUNTIME_OWNER_SUBJECT);
+    // Validated, not read raw: the same value feeds the agent subject, so a
+    // value rejected there must not slip in here (#241).
+    const legacyAgentSubject = readAgentSubjectOverride();
+    if (legacyAgentSubject)
+        return subjectSet(ns, legacyAgentSubject);
     // No principal — use the caller's fallback. A `session:<id>` fallback is
     // addressed under the Session namespace so it is a well-formed SubjectSet that
     // could match a Session-scoped grant, rather than being wrapped under `User`.

package/dist/uninstall.js

@@ -229,6 +229,14 @@ async function clearCredentialsForUninstall(options = {}) {
                 else
                     delete next.delegationAnchors;
             }
+            if (current.runtimeContexts?.[harness]) {
+                const contexts = { ...current.runtimeContexts };
+                delete contexts[harness];
+                if (Object.keys(contexts).length > 0)
+                    next.runtimeContexts = contexts;
+                else
+                    delete next.runtimeContexts;
+            }
             return next;
         });
         log(`Removed the ${harness} agent identities. Shared Ory configuration is kept for: ${remainingHarnesses.join(", ")}.`);

package/package.json

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