@ory/argus 0.14.0 → 1.0.0

package/README.md

@@ -1,23 +1,25 @@
 # Ory Argus: Agent and Developer Experience
 
-The core API behind every Ory Agent Plugin and Extension. Argus wraps [Ory Identities](https://www.ory.com/ory-ecosystem), [Ory Permissions](https://ory.com/permissions), MCP authorization, and distributed tracing into a single client. Each harness package (`@ory/claude-code`, `@ory/codex`, `@ory/gemini-cli`, and the rest — see the [root README](../../README.md) for the full list) is a thin adapter that maps one harness's hook contract onto Argus.
+The core API behind every Ory Agent Plugin and Extension. Argus wraps [Ory Identities](https://www.ory.com/ory-ecosystem), [Ory Permissions](https://ory.com/permissions), MCP authorization, and privacy-safe activity auditing into a single client. Each harness package (`@ory/claude-code`, `@ory/codex`, `@ory/gemini-cli`, and the rest) is a thin adapter that maps one harness's hook contract onto Argus.
 
 Argus is also published on its own so you can build new harness plugins or extensions, embed Ory into a custom agent runtime, or instrument any SDK that exposes event lifecycle hooks for session start, tool execution, and tool completion.
 
 ## Use
 
 ```typescript
-import { OryAgentClient } from "@ory/argus";
+import { OryAgentClient, resolveUserSubject } from "@ory/argus";
 
 const client = OryAgentClient.fromEnv("my-harness");
 
 const session = await client.verifySession(sessionToken);
 
+// Every principal is addressed as a SubjectSet (`User:<id>` by default,
+// `Session:<id>` for the fallback). resolveUserSubject builds the right shape.
 const result = await client.checkPermission({
-  namespace: "AgentTools",
+  namespace: "AgentTool",
   object: "Bash",
   relation: "use",
-  subjectId: `session:${sessionId}`,
+  ...resolveUserSubject(client, `session:${sessionId}`),
 });
 
 if (!result.allowed) {
@@ -29,46 +31,35 @@ if (!result.allowed) {
 
 ## Build a new plugin, extension, or custom integration
 
-Any agent runtime, framework, or SDK that exposes lifecycle hooks for **session start**, **tool execution**, and **tool completion** can use Argus as its authentication, authorization, and audit layer. The integration contract is the same three calls every plugin in this repo makes:
+Any agent runtime, framework, or SDK that exposes lifecycle hooks for **session start**, **tool execution**, and **tool completion** can use Argus as its authentication, authorization, and audit layer. Core adapters own the shared behavior; integrations only translate host fields and block outputs:
 
 ```typescript
 import {
+  complete,
+  gate,
   OryAgentClient,
-  ensureUserAuthenticated,
-  ensureAgentIdentity,
+  sessionStart,
+  withHookContext,
 } from "@ory/argus";
 
 const client = OryAgentClient.fromEnv("my-harness");
 
 // 1. Session start: authenticate the human and the agent process.
 async function onSessionStart() {
-  // Runs every session and never blocks — it establishes the user identity
-  // for attribution; enforcement happens at the tool gate via permissionMode.
-  await ensureUserAuthenticated(client, {
-    binName: "my-harness",
-    harness: "my-harness",
-  });
-  await ensureAgentIdentity(client, {
-    projectUrl: process.env.ORY_PROJECT_URL,
-  });
+  await sessionStart(client, { harness: "my-harness" });
 }
 
 // 2. Before each tool call: check Ory Permissions; block on `deny`.
-async function onBeforeTool(toolName: string, sessionId: string) {
-  const result = await client.checkPermission({
-    namespace: "AgentTools",
-    object: toolName,
-    relation: "use",
-    subjectId: `session:${sessionId}`,
+async function onBeforeTool(toolName: string, args: unknown, sessionId: string) {
+  return withHookContext(client, { sessionId }, async () => {
+    const result = await gate(client, { harness: "my-harness", toolName, toolArgs: args });
+    return result.blocked ? { block: true, reason: result.denialMessage } : {};
   });
-  if (result.allowed === false) {
-    return { block: true, reason: result.reason };
-  }
 }
 
-// 3. After each tool call: record a structured trace span.
-async function onAfterTool(toolName: string, durationMs: number) {
-  client.tracer.record("tool.complete", { toolName, durationMs });
+// 3. After each tool call: record structured completion activity.
+async function onAfterTool(toolName: string, output: unknown) {
+  complete(client, { toolName, output });
 }
 ```
 
@@ -85,8 +76,8 @@ The wrapped Ory client. One instance per harness session.
 | Sessions and tokens | `verifySession`, `introspectToken`, `classifyError` |
 | Permission checks | `checkPermission`, `batchCheckPermissions`, `checkMcpPermission` |
 | Principals (who is acting) | `setUserPrincipal`, `setAgentPrincipal` |
-| Delegation relations | `createRelationship`, `deleteRelationship` |
-| Tracing | `tracer` (see Tracer below) |
+| Delegation | `recordDelegation` (via the Ory Agent Security broker — the only write path; Keto is read-only here) |
+| Activity and debug | `logger` (see Logger below) |
 
 ### Identity gates
 
@@ -95,23 +86,18 @@ Resolve the user and agent identities at session start. Non-blocking by default;
 | Helper | Purpose |
 |---|---|
 | `ensureUserAuthenticated` | Interactive PKCE login, token refresh, or env-token short-circuit |
-| `ensureAgentIdentity` | OAuth2 dynamic client registration with persisted credentials |
-| `ensureSubAgentIdentity` | Per-sub-agent identity for harnesses that fan out |
-| `resolveUserSubject`, `subjectLabel` | Subject resolution and printable labels for spans and denial messages |
-
-### Tracer
-
-`Tracer` is exposed as `client.tracer`. Records every decision as a structured span.
-
-- `record(event, attrs)`: emit a span
-- `EventEmitter` `"span"` events for live observers
-- NDJSON file output
-- OTLP / HTTP export
+| `ensureAgentIdentity` | Injected/Talos runtime authentication with OS-store persistence and session-start enrollment |
+| `ensureSubAgentIdentity` | Spawn-scoped child Talos identity issued through the authenticated parent |
+| `resolveUserSubject`, `subjectLabel` | Subject resolution and printable labels for activity and denial messages |
 
 ### Logger
 
-- `DebugLogger`: structured JSON to stderr plus optional log file
-- Gated by `ORY_AGENT_DEBUG`
+- `DebugLogger`: recursively redacted structured activity plus verbose diagnostics in one NDJSON stream
+- Privacy-safe activity always persists to `<dataDir>/<harness>/ory-agent-debug.log` by default
+- `ORY_AGENT_LOG_FILE` overrides the path; an empty value disables persistence
+- `ORY_AGENT_DEBUG=true` adds the complete live JSON stream to stderr and verbose local diagnostics, including raw shell commands
+- `runWatchCommand` follows the unified log with human-readable event, decision, and error context or raw NDJSON
+- Ory Agent Security owns service telemetry; Argus has no OTel exporter or trace-context surface
 
 ### Skill and command catalog
 
@@ -126,9 +112,8 @@ Materialize the canonical `SKILL.md` templates into each harness's native skill
 ### CLI and dev tooling
 
 - Shared CLI handlers used by every plugin's CLI: `configure`, `status`, `local`, `setup`
-- `runDevLauncher(...)`: the dev-launcher pipeline used by every plugin
 - Local-stack manager: brings up a local Ory instance in Docker Compose
-- Verdaccio registry manager: a local npm registry for dev launchers
+- Verdaccio registry manager: builds and publishes the workspace for local product development
 
 ## License
 

package/assets/commands/temporal-up.md

@@ -26,7 +26,7 @@ The process runs in the foreground. Stop it with `Ctrl+C`; data is preserved.
 For a clean reset, delete `~/.config/temporalio/` and start again.
 
 For the matching Ory side of the stack (Identities, Permissions, OAuth2, login
-UI, Jaeger), use {{REF_LOCAL_UP}}. The two stacks are independent — Temporal
+UI), use {{REF_LOCAL_UP}}. The two stacks are independent — Temporal
 runs on `:7233/:8233`, Ory runs on `:4000` and friends — so they can run side
 by side without port conflicts.
 

package/assets/skills/auth-setup/SKILL.md

@@ -399,7 +399,7 @@ right place:
   route, or in the browser Network tab, is an **app/config** issue — work the
   four contract items and the checks above.
 - **The agent plugin** governs *this coding session* — it authenticates the
-  agent, checks Ory Permissions before each tool call, and writes trace spans. It
+  agent, checks Ory Permissions before each tool call, and writes activity events. It
   never serves your app's HTTP routes. Diagnose it with
   `{{NPX}} status` and the debug log (`ORY_AGENT_DEBUG=true`), **not** by looking
   at your app's auth pages.

package/assets/skills/local-dev/SKILL.md

@@ -38,6 +38,7 @@ After {{REF_LOCAL_UP}} completes:
 | Service       | URL                              | Purpose                              |
 |---------------|----------------------------------|--------------------------------------|
 | Gateway       | `http://localhost:4000`          | Unified API (mirrors Ory Network)    |
+| Agent Security| `https://agents.console.ory:8080`| Canonical permission/delegation broker |
 | Kratos public | `http://localhost:4433`          | Self-service flows (login, etc.)     |
 | Kratos admin  | `http://localhost:4434`          | Identity & session admin             |
 | Keto read     | `http://localhost:4466`          | Permission checks                    |
@@ -49,7 +50,7 @@ The seed step also produces:
 
 - Test identity: `agent@ory-local.dev`
 - A live session token (printed at the end of {{REF_LOCAL_UP}})
-- Permission tuples in the `AgentTools` namespace for common tool names
+- Permission tuples in the `AgentTool` namespace for common tool names
 - An OAuth2 client (`ory-agent-plugins-local`, `client_credentials` grant)
 
 ## Step 1: Verify Docker is running
@@ -73,10 +74,13 @@ Tell the user to run {{REF_LOCAL_UP}}, or the equivalent shell command:
 ```
 
 Wait for the command to print "All services are running!" and the seed
-output. Capture two values from the output:
+output. Configure these connection values:
 
 - `ORY_PROJECT_URL` (always `http://localhost:4000`)
-- `ORY_SESSION_TOKEN` (the seeded session token)
+- `ORY_AGENT_SECURITY_URL` (`https://agents.console.ory:8080`; run the Agent Security service separately)
+- `ORY_OAUTH2_CLIENT_ID` (the seeded PKCE login client)
+- the seeded user's email + password, which you type into the login UI
+  when the browser opens
 
 If the user wants to skip seeding (to bring their own data), use
 `{{NPX}} local up --no-seed` instead.
@@ -134,14 +138,20 @@ Two ways to exercise the flows:
    with password `ory-agent-local-dev-password!` to test session-bearing
    pages without going through registration.
 
-For automated tests against the running stack, use the seeded session
-token directly:
+For automated tests against the running stack, log in through Kratos to
+get a session token and call the session API with it:
 
 ```bash
-curl -H "X-Session-Token: $ORY_SESSION_TOKEN" \
+KRATOS_SESSION_TOKEN=$(...)   # from a Kratos login flow
+curl -H "X-Session-Token: $KRATOS_SESSION_TOKEN" \
      http://localhost:4000/sessions/whoami
 ```
 
+That token is a **Kratos session token** — it authenticates the Kratos
+session API only. It is not what the plugin uses: the plugin's env
+credential (`ORY_USER_OAUTH2_TOKEN`) must be an OAuth2 access token,
+because it authenticates delegation and can bootstrap the agent's OAuth2 client.
+
 ## Step 6: Iterate
 
 Common day-to-day commands:
@@ -191,7 +201,7 @@ plugin updates the bundled service configs.
   config change is needed. For non-localhost dev URLs, switch back to
   the Ory Tunnel + a Network project.
 - **Permission checks always deny** — the seeded tuples live in the
-  `AgentTools` namespace. If your app uses a different namespace, set
+  `AgentTool` namespace. If your app uses a different namespace, set
   `ORY_PERMISSION_NAMESPACE` before `local seed`, or write the tuples
   manually via the Keto write API on `:4467`.
 

package/assets/skills/ory-build-agent/SKILL.md

@@ -1,25 +1,22 @@
 ---
 name: ory-build-agent
-description: Build your own AI agent that authenticates the user, authorizes every tool call against Ory Permissions, and emits trace spans — by dropping `@ory/argus` directly into the Claude Agent SDK, OpenAI Agents SDK, Mastra, Vercel AI SDK, PydanticAI / LangGraph, or as an external service called by Salesforce Agentforce. Use when the user wants to wire Ory into a custom agent they own — phrases like "add Ory to my own agent", "build a custom agent with Ory auth", "wrap my Claude Agent SDK tools with Ory permissions", "OpenAI Agents SDK with Ory", "Mastra agent with Ory permissions", "Agentforce action with Ory", "use `@ory/argus` directly". For wiring Ory into an existing agent harness (Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode) use the corresponding `@ory/<harness>` plugin instead.
+description: Build your own AI agent that authenticates the user, authorizes every tool call against Ory Permissions, and records structured activity — by dropping `@ory/argus` directly into the Claude Agent SDK, OpenAI Agents SDK, Mastra, Vercel AI SDK, PydanticAI / LangGraph, or as an external service called by Salesforce Agentforce. Use when the user wants to wire Ory into a custom agent they own — phrases like "add Ory to my own agent", "build a custom agent with Ory auth", "wrap my Claude Agent SDK tools with Ory permissions", "OpenAI Agents SDK with Ory", "Mastra agent with Ory permissions", "Agentforce action with Ory", "use `@ory/argus` directly". For wiring Ory into an existing agent harness (Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode) use the corresponding `@ory/<harness>` plugin instead.
 ---
 
 # Build your own agent with `@ory/argus`
 
-You are helping the user wire Ory Identities, Permissions, and tracing into
+You are helping the user wire Ory Identities, Permissions, and activity auditing into
 **an agent they are building themselves**. They are not extending Claude Code,
 Codex, or one of the other harness plugins — they own the agent loop and
 choose where to intercept tool calls.
 
 The integration is the same three moves regardless of SDK:
 
-1. **User gate at start.** `ensureUserAuthenticated(client, …)` — the human at
-   the keyboard becomes the subject of every permission check.
-2. **Agent gate at start.** `ensureAgentIdentity(client, …)` — the process
-   making outbound Ory API calls gets its own credential (OAuth2 Dynamic
-   Client Registration by default, persisted across sessions).
-3. **Permission check on every tool call.** Wrap the SDK's tool dispatch with
-   `checkAndDecide(client, …)` and branch on `decision.kind`. Record a
-   `tool.complete` span after the tool returns.
+1. **Session start.** `sessionStart(client, …)` runs user and agent identity,
+   delegation, permission-mode warming, and fail-open handling.
+2. **Permission check on every tool call.** Wrap the SDK's tool dispatch with
+   `gate(client, …)` and translate `result.blocked` into the SDK's veto signal.
+3. **Completion.** Call `complete(client, …)` after the tool returns.
 
 `@ory/argus` ships every helper and handles fail-open semantics (network
 errors, rate limits, unconfigured project → allow). The SDKs differ only in
@@ -52,7 +49,7 @@ Also establish:
 
 - **Interactive vs headless.** Desktop / terminal agents can run PKCE login.
   Headless services (CI, daemons, Salesforce side-cars) must pre-supply
-  `ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN`.
+  `ORY_USER_OAUTH2_TOKEN`.
 - **Which tools to gate.** Usually all of them. Some SDKs have built-in
   "safe" steps (an LLM-only reasoning step, a model-provided memory tool)
   that don't need a permission check.
@@ -70,7 +67,7 @@ That's the only Ory dependency you need. The Ory SDK clients
 (`@ory/client`) and the OAuth2/PKCE plumbing are re-exported and ready to
 use.
 
-## Step 3 — Construct the client and run both gates
+## Step 3 — Construct the client and start the session
 
 Put this at the top of the agent's bootstrap, before the agent loop starts
 processing the first message:
@@ -78,40 +75,15 @@ processing the first message:
 ```ts
 import {
   OryAgentClient,
-  ensureUserAuthenticated,
-  ensureAgentIdentity,
-  resolveConfig,
+  sessionStart,
 } from "@ory/argus";
 
 const client = OryAgentClient.fromEnv("my-agent");
-const { projectUrl } = resolveConfig();
-
-// 1. User gate — interactive PKCE; runs every session and never blocks.
-//    Establishes the user identity for attribution; a declined/skipped login
-//    is audited and the flow proceeds (enforcement is at the tool gate).
-await ensureUserAuthenticated(client, {
-  binName: "my-agent",
-  harness: "my-agent",
-});
-
-// 2. Agent gate — never blocks; resolves machine credentials (DCR by default).
-await ensureAgentIdentity(client, { projectUrl, harness: "my-agent" });
-
-// 3. (optional) write the user→agent delegation tuple for audit.
-if (client.userPrincipal.subject && client.agentPrincipal.subject) {
-  await client
-    .createRelationship({
-      namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools",
-      object: `agent:${client.agentPrincipal.subject}`,
-      relation: "delegate",
-      subjectId: `user:${client.userPrincipal.subject}`,
-    })
-    .catch(() => undefined); // audit-only — swallow failures
-}
+await sessionStart(client, { harness: "my-agent" });
 ```
 
 The user gate runs on every session and is always non-blocking: it refreshes
-tokens, prompts on TTY, and emits the `user.auth` span, but always returns
+tokens, prompts on TTY, and emits the `user.auth` activity event, but always returns
 `proceed: true`. A missing or declined login never stops the agent — the
 consequence surfaces at the tool gate, where `permissionMode: enforce` denies
 and `observe` audits.
@@ -123,48 +95,25 @@ Put it next to where you construct the client.
 
 ```ts
 import {
-  checkAndDecide,
-  resolveUserSubject,
-  subjectLabel,
+  complete,
+  gate,
 } from "@ory/argus";
 
-async function gateTool(toolName: string, sessionId: string) {
-  const subject = resolveUserSubject(client, `session:${sessionId}`);
-  const decision = await checkAndDecide(
-    client,
-    {
-      namespace: process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools",
-      object: toolName,
-      relation: "use",
-      ...subject,
-    },
-    { spanAttributes: { toolName } }
-  );
-
-  switch (decision.kind) {
-    case "allow":
-    case "observe":
-    case "fail_open":
-      return { allow: true as const };
-    case "deny":
-      return {
-        allow: false as const,
-        message: `Ory denied ${toolName} for ${subjectLabel(subject)}.`,
-      };
-  }
+async function gateTool(toolName: string, toolArgs?: unknown) {
+  const result = await gate(client, { harness: "my-agent", toolName, toolArgs });
+  return result.blocked
+    ? { allow: false as const, message: result.denialMessage }
+    : { allow: true as const };
 }
 ```
 
-After the tool finishes (whichever SDK), record a completion span:
+After the tool finishes (whichever SDK), record completion activity:
 
 ```ts
-client.tracer.record("tool.complete", "ok", {
-  attributes: { toolName, durationMs },
-});
+complete(client, { toolName, output });
 ```
 
-`checkAndDecide` already records `permission.check`, `permission.observe_deny`
-(on observe), and `tool.block` (on deny). You only own `tool.complete`.
+`gate` records permission and execution activity; `complete` records the terminal event.
 
 ## Step 5 — SDK-specific wiring
 
@@ -240,7 +189,7 @@ Agentforce is a declarative agent inside the Salesforce platform — you
    operations. The gate runs inside your Node service on every call; denies
    come back as tool errors the agent surfaces to the user.
 
-Pre-supply `ORY_USER_SESSION_TOKEN` (or `ORY_USER_OAUTH2_TOKEN`) to the
+Pre-supply `ORY_USER_OAUTH2_TOKEN` to the
 side-car from a session the user established out-of-band — for example, a
 PKCE flow at sign-on into the Experience Cloud site that fronts the agent.
 A headless side-car cannot run PKCE on its own.
@@ -338,13 +287,11 @@ Pure-Python agents don't link `@ory/argus` directly. The two supported
 patterns:
 
 - **Side-car HTTP service.** Run a small Node process that exposes
-  `POST /gate` (calls `gateTool`) and `POST /trace` (calls
-  `client.tracer.record(...)`). Your Python agent calls these from inside
+  `POST /gate` (calls `gateTool`). Your Python agent calls it from inside
   each `@agent.tool`.
-- **Direct Ory APIs.** Use the official `ory-client` Python SDK to call
-  `PermissionApi.check_permission()` and post audit spans to your own
-  collector. You lose the fail-open / observe-mode helpers; re-implement
-  them in Python.
+- **Native Python integration.** Use `ory-argus`, which routes checks through
+  the canonical Agent Security broker and preserves the same fail-open,
+  observe/enforce, identity, and activity behavior as the TypeScript core.
 
 Side-car pattern:
 
@@ -402,21 +349,22 @@ The `gateTool` body does not change.
 ## Step 6 — Test against the local Ory stack
 
 Before pointing at production, run the gate against the local stack so the
-PKCE flow, permission tuples, and trace spans are all visible:
+PKCE flow, permission tuples, and activity events are all visible:
 
 1. {{REF_LOCAL_UP}} — brings up Kratos / Keto / Hydra on `localhost:4000`
    and seeds a demo user. The banner prints the email + password.
 2. Export the env vars the launcher writes (`ORY_PROJECT_URL`,
-   `ORY_OAUTH2_CLIENT_ID`, optional `ORY_AGENT_TRACE_FILE` for an NDJSON
-   span log). The user login runs every session.
+   `ORY_OAUTH2_CLIENT_ID`, and optionally `ORY_AGENT_LOG_FILE` to override the
+   default unified NDJSON log). The user login runs every session.
 3. Start your agent. Confirm the browser opens for PKCE login.
-4. Invoke a gated tool and `tail -f $ORY_AGENT_TRACE_FILE | jq .` — you
+4. Invoke a gated tool and tail `<dataDir>/<harness>/ory-agent-debug.log` with
+   `jq` — you
    should see `user.auth` → `agent.auth` → `permission.check` →
    `tool.complete` for every call.
-5. Promote to enforce once the `use` tuples are seeded: either
-   `ORY_PERMISSION_MODE=enforce` for one launch, or use one of the harness
-   CLIs to flip it persistently (e.g. `npx -y -p @ory/claude-code ory-claude
-   permissions enforce` — same shared config file).
+5. Promote to enforce once the tools are granted. The posture is a
+   permission on the Ory project, read on every session — an admin sets it
+   in the Ory Console (Agent Security); see the resolved value with
+   `... permissions` via any harness CLI (same shared config file).
 6. {{REF_LOCAL_DOWN}} when done. Volumes persist, so the seeded user
    survives across runs.
 
@@ -428,9 +376,9 @@ For full env-var coverage (including the user/agent split,
 - It does not generate the agent. The user owns the agent loop, tool
   catalog, and deployment shape. This skill only drops `@ory/argus` into
   whatever they already have.
-- It does not write the permission tuples. Seed them with
-  `... permissions bootstrap` (run via any of the harness CLIs — same shared
-  config file) or by calling `client.createRelationship` directly.
+- It does not grant permissions. Those are provisioned in the Ory Console
+  (Agent Security); `@ory/argus` only reads them. Locally, the dev stack's
+  seed step grants the catalog for you.
 - It does not adapt one of the existing harness plugins (`@ory/claude-code`,
   `@ory/codex`, `@ory/gemini-cli`, `@ory/openclaw`, `@ory/opencode`). Those
   are for users running those harnesses — not building a custom agent.

package/assets/skills/ory-e2b-sandbox/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ory-e2b-sandbox
-description: Scaffold an E2B (e2b.dev) sandbox template that boots with {{PKG}} preinstalled, so every Claude/Codex/Gemini/OpenClaw/OpenCode session running inside the sandbox is gated by Ory auth, permissions, and tracing without any per-sandbox setup. Use when the user asks to "create an E2B sandbox with Ory agent security", "build an E2B template with the Ory plugin", "make an E2B image that includes Ory auth", or any close variant. The skill generates the template files in the user's project — it does not deploy them.
+description: Scaffold an E2B (e2b.dev) sandbox template that boots with {{PKG}} preinstalled, so every Claude/Codex/Gemini/OpenClaw/OpenCode session running inside the sandbox is gated by Ory auth and permissions and records structured activity without any per-sandbox setup. Use when the user asks to "create an E2B sandbox with Ory agent security", "build an E2B template with the Ory plugin", "make an E2B image that includes Ory auth", or any close variant. The skill generates the template files in the user's project — it does not deploy them.
 ---
 
 # E2B sandbox with Ory agent security
@@ -9,8 +9,8 @@ You are helping the user scaffold an [E2B](https://e2b.dev) sandbox template
 that preinstalls and registers the {{PKG}} plugin. The resulting template
 publishes a named image; every `Sandbox.create("<tag>")` call from their SDK
 gets a runtime where the agent's tool calls are already authenticated against
-Ory Identities, authorized against Ory Permissions, and emitted as trace
-spans — with **no** install step at sandbox boot.
+Ory Identities, authorized against Ory Permissions, and recorded as structured
+activity events — with **no** install step at sandbox boot.
 
 This skill carries the full workflow and the file contents. You generate the
 files in the user's repo; the user runs the build.
@@ -66,8 +66,7 @@ export const template = Template()
   // Sandbox runtime defaults. Per-tenant secrets (project URL, tokens, client
   // IDs) MUST be passed at Sandbox.create() time, never baked into the image.
   .setEnvs({
-    ORY_PERMISSION_MODE: "observe",
-    ORY_PERMISSION_NAMESPACE: "AgentTools",
+    ORY_PERMISSION_NAMESPACE: "AgentTool",
     ORY_AGENT_DEBUG: "true",
     ORY_AGENT_LOG_FILE: "/root/ory-agent-debug.log",
   })
@@ -114,9 +113,10 @@ E2B_API_KEY=e2b_***
 # the template. Listed here so operators know what to plumb through.
 ORY_PROJECT_URL=https://<slug>.projects.oryapis.com
 ORY_OAUTH2_CLIENT_ID=
-ORY_USER_SESSION_TOKEN=
+ORY_USER_OAUTH2_TOKEN=
 # Optional: pin a static agent identity instead of DCR.
-# ORY_AGENT_API_KEY=
+# ORY_AGENT_CLIENT_ID=
+# ORY_AGENT_CLIENT_SECRET=
 ```
 
 ### `integrations/e2b/package.json`
@@ -152,8 +152,8 @@ Generate a README that captures:
   `npm run build:prod`.
 - A `Sandbox.create("agent-ory", { envs: { ... } })` example showing which env
   vars to inject at runtime (`ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`,
-  `ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN`, optional
-  `ORY_AGENT_API_KEY`).
+  `ORY_USER_OAUTH2_TOKEN`, optional
+  `ORY_AGENT_CLIENT_ID` + `ORY_AGENT_CLIENT_SECRET`).
 - A pointer to {{REF_AUTH_SETUP}} for full env-var coverage and to
   {{REF_LOCAL_DEV}} for testing the same plugin locally before publishing the
   template.
@@ -189,7 +189,7 @@ const sbx = await Sandbox.create("agent-ory", {
     ORY_PROJECT_URL: process.env.ORY_PROJECT_URL!,
     ORY_OAUTH2_CLIENT_ID: process.env.ORY_OAUTH2_CLIENT_ID!,
     // Pre-supply a user token so the headless sandbox skips PKCE.
-    ORY_USER_SESSION_TOKEN: process.env.ORY_USER_SESSION_TOKEN!,
+    ORY_USER_OAUTH2_TOKEN: process.env.ORY_USER_OAUTH2_TOKEN!,
   },
 });
 
@@ -197,18 +197,19 @@ await sbx.commands.run("{{BIN}} --version");  // sanity check
 ```
 
 Sandboxes are headless, so the user **must** pre-supply
-`ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN` — otherwise user login's
+`ORY_USER_OAUTH2_TOKEN` — otherwise user login's
 PKCE browser flow has no target and hangs. See {{REF_AUTH_SETUP}} for the full
 env-var matrix.
 
 ## Step 5 — Promotion path
 
-The template ships with `ORY_PERMISSION_MODE=observe` baked in so first-run
-sandboxes never block. To promote a sandbox to hard enforcement without
-rebuilding the template, either pass `ORY_PERMISSION_MODE=enforce` at
-`Sandbox.create()` time, or run `{{NPX}} permissions enforce` inside a running
-sandbox. Run `{{NPX}} permissions bootstrap` first on a fresh Ory project so
-the `use` tuples exist before enforcement turns on.
+A sandbox starts in observe mode, so first-run sandboxes never block. The
+deny posture is a property of the **Ory project**, read on every session: an
+admin promotes it to `enforce` in the Ory Console (Agent Security), project-wide
+or for a single principal, and running sandboxes pick that up without a rebuild.
+Grant `use` on the tools first, also in the Console — otherwise flipping to
+enforce blocks everything. Check what a sandbox resolves with
+`{{NPX}} permissions`.
 
 ## What this skill does NOT do