sentinelayer-cli 0.42.0 → 0.43.0

package/README.md

@@ -163,6 +163,43 @@ sl session join <session-id> --agent <agent-name>
 sl session action <session-id> working_on --target-sequence <n>
 ```
 
+For a room that requires agent admission, the agent declares its goal, requested
+actions, and TTL. The CLI creates an agent-held Ed25519 identity, waits for a
+human decision, then waits for the minted AIdenID email and verified signed
+purpose receipt. Only after that evidence is ready does it claim the approved
+grant with proof of possession and join. The private key and scoped credential
+are stored locally and are never printed:
+
+```bash
+# Agent: request and wait for the owner's decision (maximum grant TTL is 24h).
+sl session join <session-id> --agent review-agent \
+  --goal "Review the release and report findings" \
+  --scope session.read,session.post --ttl 24h
+
+# Or request without waiting, for an asynchronous handoff.
+sl session access request <session-id> --agent review-agent \
+  --goal "Review the release and report findings" \
+  --scope session.read,session.post --ttl 24h --json
+
+# Owner/admin: inspect the untrusted goal claim, then approve, narrow, or deny.
+sl session access mode <session-id> required
+sl session access list <session-id> --status pending
+sl session access approve <session-id> <admission-id> \
+  --scope session.read,session.post --ttl 24h
+# sl session access deny <session-id> <admission-id> --note "reason"
+# sl session access revoke <session-id> <admission-id> --reason "work complete"
+```
+
+Approval queues the AIdenID email and purpose-receipt work. `session access
+list --json` reports the real `email`, `purpose`, and Jev status; it does not
+invent successful issuance while those jobs are pending or unavailable, and
+the API withholds the claim challenge until both identity artifacts are ready.
+The agent must re-run `session join` with the same goal, scope, and TTL after an
+asynchronous request so it can claim and verify its live session-bound receipt.
+New rooms default to fail-closed `required` mode. Existing rooms retain their
+stored `legacy` mode until an owner explicitly sets `required`; the mode command
+is the activation step for those pre-existing rooms.
+
 Sentinelayer includes a deterministic session coordination surface for multi-agent coding loops:
 
 - session event stream and replay (`start`, `join`, `say`, `read`, `status`, `leave`, `list`, `kill`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -98,6 +98,13 @@ import {
   parseTtlSeconds as parseAdmissionTtlSeconds,
   runAdmissionJoin,
 } from "../session/admission.js";
+import {
+  decideSessionAdmission,
+  getSessionAdmission,
+  listSessionAdmissions,
+  revokeSessionAdmission,
+  setSessionAdmissionMode,
+} from "../session/admission-access.js";
 import {
   assertCanonicalAgentId,
   canonicalAgentId,
@@ -3488,17 +3495,24 @@ export function registerSessionCommand(program) {
           wait: options.wait !== false,
           waitTimeoutMs: (Number.isFinite(waitSeconds) && waitSeconds >= 0 ? waitSeconds : 900) * 1000,
           targetPath,
-          onPending: ({ approveUrl }) => {
+          onPending: ({ approveUrl, phase }) => {
             // stderr, so --json stdout stays a single parseable document.
-            const line = `Waiting for a room owner to approve this agent: ${approveUrl}`;
+            const line = phase === "identity"
+              ? "Approval received; waiting for the AIdenID email and signed purpose receipt."
+              : `Waiting for a room owner to approve this agent: ${terminalText(approveUrl, 1024)}`;
             if (emitJson) process.stderr.write(`${line}\n`);
-            else console.log(pc.yellow(line));
+            // Keep the line containing a remote URL free of all terminal control
+            // bytes. `terminalText()` strips controls from the value itself; adding
+            // local ANSI colour around it would make that guarantee untestable and
+            // lets OSC-looking input hide inside a coloured terminal span.
+            else if (phase === "identity") console.log(pc.yellow(line));
+            else console.log(line);
           },
         });
         if (admission.status !== "active") {
           // Only an ACTIVE admission joins. Pending, denied, cancelled or expired never
           // registers the agent or materializes the room for it.
-          process.exitCode = admission.status === "pending" ? 3 : 4;
+          process.exitCode = ["pending", "approved"].includes(admission.status) ? 3 : 4;
           const payload = {
             command: "session join",
             joined: false,
@@ -3510,9 +3524,12 @@ export function registerSessionCommand(program) {
           if (emitJson) {
             console.log(JSON.stringify(payload, null, 2));
           } else if (admission.status === "pending") {
-            console.log(pc.yellow(`Admission pending. A room owner approves it here: ${admission.approveUrl || "(see the session page)"}`));
+            const approval = terminalText(admission.approveUrl, 1024) || "(see the session page)";
+            console.log(`Admission pending. A room owner approves it here: ${approval}`);
+          } else if (admission.status === "approved") {
+            console.log(pc.yellow("Admission approved; AIdenID identity evidence is still provisioning. The agent was not joined."));
           } else {
-            console.log(pc.red(`Admission ${admission.status}. The agent was not joined.`));
+            console.log(pc.red(`Admission ${terminalText(admission.status, 16) || "unknown"}. The agent was not joined.`));
           }
           return;
         }
@@ -6787,6 +6804,285 @@ export function registerSessionCommand(program) {
       }
     });
 
+  // ------------------------------------------------------- agent access
+  // Human control plane for the Agent Admission Contract. The request command
+  // delegates to the established agent-side flow; list/decision/revoke use the
+  // matching owner-only REST routes. Goal text is an agent claim and is always
+  // rendered as bounded, untrusted data.
+  const access = session
+    .command("access")
+    .description("Request and govern AIdenID-backed, scoped agent access to a session");
+
+  function accessOutput(options, command, payload, render) {
+    if (shouldEmitJson(options, command)) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    render();
+  }
+
+  function terminalText(value, maxLength = 240) {
+    let result = "";
+    for (const ch of normalizeString(value).normalize("NFC")) {
+      // Refuse terminal control/invisible formatting from remote values,
+      // including ANSI/OSC initiators and bidi overrides/isolates.
+      result += /[\p{Cc}\p{Cf}\p{Cs}\p{Co}\p{Cn}\p{Zl}\p{Zp}]/u.test(ch) ? " " : ch;
+      if (result.length >= maxLength) break;
+    }
+    return result.replace(/\s+/gu, " ").trim();
+  }
+
+  function renderAdmissionLine(admission) {
+    const requested = Array.isArray(admission?.requestedScope?.actions)
+      ? terminalText(admission.requestedScope.actions.join(","), 180)
+      : "scope unavailable";
+    const ttl = Number(admission?.requestedScope?.ttlSeconds);
+    const duration = Number.isFinite(ttl) ? ` for ${ttl}s` : "";
+    const identity = terminalText(admission?.displayName, 120) || terminalText(admission?.agentId, 64) || "unknown-agent";
+    console.log(`${terminalText(admission?.admissionId, 64) || "unknown"}  ${terminalText(admission?.status, 16) || "unknown"}  ${identity}`);
+    console.log(pc.gray(`  requested: ${requested}${duration}`));
+    const summary = terminalText(admission?.goal?.summary);
+    if (summary) console.log(pc.gray(`  claimed goal (untrusted): ${JSON.stringify(summary)}`));
+    if (admission?.email) {
+      // Human terminal output is routinely copied into logs and support
+      // transcripts. Keep the address in the explicit --json response only.
+      const inboxStatus = terminalText(admission.email.status, 32) || "unknown";
+      console.log(pc.gray(`  AIdenID inbox: ${inboxStatus}`));
+    }
+  }
+
+  access
+    .command("mode <sessionId> <mode>")
+    .description("Set whether this room requires admission for agent-attributed access (required or legacy)")
+    .option("--idempotency-key <key>", "Retry the same logical mode change safely")
+    .option("--path <path>", "Workspace path for auth context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, mode, options, command) => {
+      const sid = normalizeString(sessionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const changed = await setSessionAdmissionMode(sid, mode, {
+        idempotencyKey: options.idempotencyKey,
+        targetPath,
+      });
+      accessOutput(
+        options,
+        command,
+        {
+          command: "session access mode",
+          idempotencyKey: changed.idempotencyKey,
+          ...changed.result,
+        },
+        () => console.log(
+          `Agent admission mode for ${terminalText(sid, 64)}: ${terminalText(changed.result.agentAdmissionMode, 16) || "unknown"}.`,
+        ),
+      );
+    });
+
+  access
+    .command("request <sessionId>")
+    .description("Request agent access; a human must approve before the agent can claim or join")
+    .requiredOption("--agent <id>", "Canonical agent id requesting access")
+    .requiredOption("--goal <text>", "What the agent is coming to do")
+    .option("--display-name <name>", "Human-readable agent name")
+    .option("--deliverable <text>", "An output this agent will produce (repeatable)", collectOption, [])
+    .option("--stop-when <text>", "A condition that ends this agent's work (repeatable)", collectOption, [])
+    .option(
+      "--scope <actions>",
+      "Comma-separated actions: session.read, session.post, session.react, tickets.read, tickets.work",
+    )
+    .option("--ttl <duration>", "Requested grant lifetime, e.g. 90m or 24h (5m..24h)", "2h")
+    .option("--model <model>", "Agent model hint", "cli")
+    .option("--provider <name>", "Model provider hint")
+    .option("--wait", "Wait for approval and claim the grant on this machine")
+    .option("--wait-seconds <n>", "Maximum approval wait when --wait is set", "900")
+    .option("--path <path>", "Workspace path for local admission state", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const agentId = canonicalAgentId(options.agent);
+      assertCanonicalAgentId(options.agent, "--agent");
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const waitSeconds = Number.parseInt(String(options.waitSeconds ?? "900"), 10);
+      if (!Number.isFinite(waitSeconds) || waitSeconds < 0) {
+        throw new Error("--wait-seconds must be a non-negative integer.");
+      }
+      const admission = await runAdmissionJoin(sid, {
+        agentId,
+        displayName: options.displayName,
+        model: options.model,
+        provider: options.provider,
+        goal: options.goal,
+        deliverables: options.deliverable || [],
+        stopConditions: options.stopWhen || [],
+        actions: parseAdmissionScope(options.scope),
+        ttlSeconds: parseAdmissionTtlSeconds(options.ttl),
+        wait: Boolean(options.wait),
+        waitTimeoutMs: waitSeconds * 1000,
+        targetPath,
+        onPending: ({ approveUrl, phase }) => {
+          const line = phase === "identity"
+            ? "Approval received; waiting for the AIdenID email and signed purpose receipt."
+            : `Waiting for a room owner to approve this agent: ${terminalText(approveUrl, 1024)}`;
+          if (shouldEmitJson(options, command)) process.stderr.write(`${line}\n`);
+          // A line carrying a remote URL must remain free of every terminal
+          // control byte, including trusted colour wrappers. This mirrors the
+          // guarded `session join` path and keeps raw support logs auditable.
+          else if (phase === "identity") console.log(pc.yellow(line));
+          else console.log(line);
+        },
+      });
+      const payload = {
+        command: "session access request",
+        sessionId: sid,
+        agentId,
+        admission,
+        readyToJoin: admission.status === "active",
+      };
+      accessOutput(options, command, payload, () => {
+        if (admission.status === "pending") {
+          console.log(`Access requested for ${agentId}; waiting for a room owner.`);
+          if (admission.approveUrl) console.log(`Approval: ${terminalText(admission.approveUrl, 1024)}`);
+        } else if (admission.status === "active") {
+          console.log(`Access active for ${agentId}. The scoped credential is stored locally and was not printed.`);
+          console.log(pc.gray("Run `sl session join` again with the same goal, scope, and TTL to attach this agent."));
+        } else if (admission.status === "approved") {
+          console.log("Access approved; waiting for the AIdenID inbox and signed purpose receipt before claim.");
+        } else {
+          console.log(`Access ${terminalText(admission.status, 16) || "unknown"} for ${agentId}.`);
+        }
+      });
+    });
+
+  access
+    .command("list <sessionId>")
+    .description("List admission requests visible to a room owner or admin")
+    .option("--status <status>", "Filter by admission status")
+    .option("--path <path>", "Workspace path for auth context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await listSessionAdmissions(sid, {
+        status: options.status,
+        targetPath,
+      });
+      const payload = { command: "session access list", ...result };
+      accessOutput(options, command, payload, () => {
+        console.log(pc.gray(`Admission mode: ${terminalText(result.agentAdmissionMode, 16) || "unknown"}`));
+        if (!Array.isArray(result.admissions) || result.admissions.length === 0) {
+          console.log("No admission requests.");
+          return;
+        }
+        for (const admission of result.admissions) renderAdmissionLine(admission);
+      });
+    });
+
+  access
+    .command("status <sessionId> <admissionId>")
+    .description("Show the requesting delegator's current admission status")
+    .option("--path <path>", "Workspace path for auth context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, admissionId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const aid = normalizeString(admissionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await getSessionAdmission(sid, aid, { targetPath });
+      accessOutput(
+        options,
+        command,
+        { command: "session access status", sessionId: sid, ...result },
+        () => {
+          console.log(`${terminalText(result.admissionId, 64) || aid}  ${terminalText(result.status, 16) || "unknown"}  ${terminalText(result.agentId, 64) || "unknown-agent"}`);
+          if (result.approveUrl) console.log(`Approval: ${terminalText(result.approveUrl, 1024)}`);
+        },
+      );
+    });
+
+  access
+    .command("approve <sessionId> <admissionId>")
+    .description("Approve a pending request, optionally narrowing its scope or TTL")
+    .option("--scope <actions>", "Comma-separated granted actions; must be a subset of the request")
+    .option("--ttl <duration>", "Granted lifetime; may only shorten the request (5m..24h)")
+    .option("--note <text>", "Approval note (max 500 characters)")
+    .option("--idempotency-key <key>", "Retry the same logical approval safely")
+    .option("--path <path>", "Workspace path for auth context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, admissionId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const aid = normalizeString(admissionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const decision = await decideSessionAdmission(sid, aid, {
+        decision: "approve",
+        grantedActions: options.scope === undefined ? undefined : parseAdmissionScope(options.scope),
+        ttlSeconds: options.ttl === undefined ? undefined : parseAdmissionTtlSeconds(options.ttl),
+        note: options.note,
+        idempotencyKey: options.idempotencyKey,
+        targetPath,
+      });
+      const result = decision.result;
+      accessOutput(
+        options,
+        command,
+        { command: "session access approve", sessionId: sid, idempotencyKey: decision.idempotencyKey, admission: result },
+        () => {
+          console.log(`Approved ${terminalText(result.admissionId, 64) || aid} for ${terminalText(result.agentId, 64) || "the agent"}.`);
+          if (result.email) {
+            const inboxStatus = terminalText(result.email.status, 32) || "queued";
+            console.log(pc.gray(`AIdenID inbox: ${inboxStatus}. Use --json to inspect its address.`));
+          }
+        },
+      );
+    });
+
+  access
+    .command("deny <sessionId> <admissionId>")
+    .description("Deny a pending agent admission request")
+    .option("--note <text>", "Denial note (max 500 characters)")
+    .option("--idempotency-key <key>", "Retry the same logical denial safely")
+    .option("--path <path>", "Workspace path for auth context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, admissionId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const aid = normalizeString(admissionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const decision = await decideSessionAdmission(sid, aid, {
+        decision: "deny",
+        note: options.note,
+        idempotencyKey: options.idempotencyKey,
+        targetPath,
+      });
+      accessOutput(
+        options,
+        command,
+        { command: "session access deny", sessionId: sid, idempotencyKey: decision.idempotencyKey, admission: decision.result },
+        () => console.log(`Denied ${terminalText(decision.result.admissionId, 64) || aid}.`),
+      );
+    });
+
+  access
+    .command("revoke <sessionId> <admissionId>")
+    .description("Revoke an approved or active agent admission")
+    .option("--reason <text>", "Revocation reason (max 200 characters)")
+    .option("--idempotency-key <key>", "Retry the same logical revocation safely")
+    .option("--path <path>", "Workspace path for auth context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, admissionId, options, command) => {
+      const sid = normalizeString(sessionId);
+      const aid = normalizeString(admissionId);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const revoked = await revokeSessionAdmission(sid, aid, {
+        reason: options.reason,
+        idempotencyKey: options.idempotencyKey,
+        targetPath,
+      });
+      accessOutput(
+        options,
+        command,
+        { command: "session access revoke", sessionId: sid, idempotencyKey: revoked.idempotencyKey, admission: revoked.result },
+        () => console.log(`Revoked ${terminalText(revoked.result.admissionId, 64) || aid}.`),
+      );
+    });
+
   // ---------------------------------------------------------------- tickets
   // The room's shared backlog (API "Ticket Lease Contract (T2)"). Every subcommand is
   // an ACTOR command: the runCli choke point runs it on the agent's admission.

package/src/session/admission-access.js

@@ -0,0 +1,256 @@
+// Owner/delegator controls for the Agent Admission Contract.
+//
+// Agent-side key generation, approval polling, proof-of-possession claim, and
+// credential storage remain in admission.js. This module is deliberately the
+// human control plane only: inspect requests, approve/deny them, or revoke a
+// live grant. Every mutation uses the same session CSRF + idempotency contract
+// as the existing request/claim path.
+
+import process from "node:process";
+
+import { requestJson, requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import {
+  SESSION_MUTATION_ORIGIN,
+  createSessionMutationHeaders,
+  createSessionMutationIdempotencyKey,
+} from "./invitations.js";
+
+export const ADMISSION_STATUSES = Object.freeze([
+  "pending",
+  "approved",
+  "active",
+  "denied",
+  "cancelled",
+  "expired",
+  "revoked",
+  "stopped",
+]);
+
+const ROUTES = Object.freeze({
+  decision: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/decision",
+  revoke: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/revoke",
+  mode: "POST /api/v1/sessions/{session_id}/admission-mode",
+});
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+function required(value, label) {
+  const normalized = normalizeString(value);
+  if (!normalized) throw new Error(`${label} is required.`);
+  return normalized;
+}
+
+async function authContext(targetPath, resolveAuthSession) {
+  const auth = await resolveAuthSession({
+    cwd: targetPath,
+    env: process.env,
+    autoRotate: false,
+  });
+  if (!auth?.token || !auth?.apiUrl) {
+    throw new Error("Not authenticated. Run `sl auth login` first.");
+  }
+  return {
+    token: auth.token,
+    apiUrl: normalizeString(auth.apiUrl).replace(/\/+$/, ""),
+  };
+}
+
+function admissionsUrl(apiUrl, sessionId, suffix = "") {
+  return `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/admissions${suffix}`;
+}
+
+function boundedIdempotencyKey(value, operation) {
+  const explicit = normalizeString(value);
+  if (explicit.length > 128) throw new Error("--idempotency-key must be at most 128 characters.");
+  return explicit || createSessionMutationIdempotencyKey(operation);
+}
+
+async function mutateAdmission(
+  sessionId,
+  suffix,
+  routeId,
+  body,
+  {
+    targetPath,
+    idempotencyKey,
+    operationName,
+    origin,
+    resolveAuthSession,
+    requestMutation,
+  },
+) {
+  const key = boundedIdempotencyKey(idempotencyKey, operationName);
+  const auth = await authContext(targetPath, resolveAuthSession);
+  const result = await requestMutation(admissionsUrl(auth.apiUrl, sessionId, suffix), {
+    method: "POST",
+    operationName,
+    idempotencyKey: key,
+    headers: createSessionMutationHeaders({
+      bearerToken: auth.token,
+      sessionId,
+      routeId,
+      idempotencyKey: key,
+      origin,
+    }),
+    body,
+  });
+  return { idempotencyKey: key, result };
+}
+
+export async function listSessionAdmissions(
+  sessionId,
+  {
+    status = "",
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestRead = requestJson,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const normalizedStatus = normalizeString(status).toLowerCase();
+  if (normalizedStatus && !ADMISSION_STATUSES.includes(normalizedStatus)) {
+    throw new Error(
+      `--status must be one of: ${ADMISSION_STATUSES.join(", ")}.`,
+    );
+  }
+  const auth = await authContext(targetPath, resolveAuthSession);
+  const query = normalizedStatus ? `?status=${encodeURIComponent(normalizedStatus)}` : "";
+  return requestRead(`${admissionsUrl(auth.apiUrl, sid)}${query}`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${auth.token}` },
+  });
+}
+
+export async function getSessionAdmission(
+  sessionId,
+  admissionId,
+  {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestRead = requestJson,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const aid = required(admissionId, "admission id");
+  const auth = await authContext(targetPath, resolveAuthSession);
+  return requestRead(admissionsUrl(auth.apiUrl, sid, `/${encodeURIComponent(aid)}`), {
+    method: "GET",
+    headers: { Authorization: `Bearer ${auth.token}` },
+  });
+}
+
+export async function decideSessionAdmission(
+  sessionId,
+  admissionId,
+  {
+    decision,
+    grantedActions,
+    ttlSeconds,
+    note,
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const aid = required(admissionId, "admission id");
+  const normalizedDecision = normalizeString(decision).toLowerCase();
+  if (!["approve", "deny"].includes(normalizedDecision)) {
+    throw new Error("decision must be approve or deny.");
+  }
+  if (normalizedDecision === "deny" && (grantedActions !== undefined || ttlSeconds !== undefined)) {
+    throw new Error("A denied admission cannot include --scope or --ttl.");
+  }
+  const body = { decision: normalizedDecision };
+  if (grantedActions !== undefined) body.grantedActions = grantedActions;
+  if (ttlSeconds !== undefined) body.ttlSeconds = ttlSeconds;
+  const normalizedNote = normalizeString(note);
+  if (normalizedNote) body.note = normalizedNote;
+  return mutateAdmission(
+    sid,
+    `/${encodeURIComponent(aid)}/decision`,
+    ROUTES.decision,
+    body,
+    {
+      targetPath,
+      idempotencyKey,
+      operationName: `session.admission_${normalizedDecision}`,
+      origin,
+      resolveAuthSession,
+      requestMutation,
+    },
+  );
+}
+
+export async function revokeSessionAdmission(
+  sessionId,
+  admissionId,
+  {
+    reason,
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const aid = required(admissionId, "admission id");
+  const normalizedReason = normalizeString(reason);
+  return mutateAdmission(
+    sid,
+    `/${encodeURIComponent(aid)}/revoke`,
+    ROUTES.revoke,
+    normalizedReason ? { reason: normalizedReason } : {},
+    {
+      targetPath,
+      idempotencyKey,
+      operationName: "session.admission_revoke",
+      origin,
+      resolveAuthSession,
+      requestMutation,
+    },
+  );
+}
+
+export async function setSessionAdmissionMode(
+  sessionId,
+  mode,
+  {
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const normalizedMode = normalizeString(mode).toLowerCase();
+  if (!["legacy", "required"].includes(normalizedMode)) {
+    throw new Error("mode must be legacy or required.");
+  }
+  const key = boundedIdempotencyKey(idempotencyKey, "session.admission_mode");
+  const auth = await authContext(targetPath, resolveAuthSession);
+  const result = await requestMutation(
+    `${auth.apiUrl}/api/v1/sessions/${encodeURIComponent(sid)}/admission-mode`,
+    {
+      method: "POST",
+      operationName: "session.admission_mode",
+      idempotencyKey: key,
+      headers: createSessionMutationHeaders({
+        bearerToken: auth.token,
+        sessionId: sid,
+        routeId: ROUTES.mode,
+        idempotencyKey: key,
+        origin,
+      }),
+      body: { mode: normalizedMode },
+    },
+  );
+  return { idempotencyKey: key, result };
+}

package/src/session/admission-auth.js

@@ -153,13 +153,20 @@ export const SESSION_AGENT_PRINCIPAL = Object.freeze({
   "ticket release": "actor",
   "ticket submit": "actor",
   "ticket events": "actor",
+  "access mode": "control",
+  "access request": "control",
+  "access list": "control",
+  "access status": "control",
+  "access approve": "control",
+  "access deny": "control",
+  "access revoke": "control",
   kill: "target",
   "stop-listener": "target",
   leave: "target",
   "guard-uninstall": "target",
   join: "control",
 });
-const SESSION_COMMAND_GROUPS = new Set(["checkpoint", "ticket"]);
+const SESSION_COMMAND_GROUPS = new Set(["access", "checkpoint", "ticket"]);
 
 async function implicitAgent(sessionId, targetPath, env) {
   // The same identity the command itself resolves when --agent is omitted

package/src/session/admission.js

@@ -471,12 +471,33 @@ export async function runAdmissionJoin(
       headers: { Authorization: `Bearer ${auth.token}` },
     });
     state.status = polled.status;
-    if (polled.status === "approved" || TERMINAL.has(polled.status) || polled.status === "active") break;
-    onPending({ admissionId: state.admissionId, approveUrl: polled.approveUrl || state.approveUrl });
+    const claimReady =
+      polled.status === "approved" &&
+      polled.identityReady === true &&
+      polled?.claim?.domain === CLAIM_DOMAIN &&
+      polled?.claim?.preimage;
+    if (polled.status === "approved" && polled.identityReady === true && !claimReady) {
+      throw new Error("Identity-ready admission did not include a valid claim challenge.");
+    }
+    if (polled.status === "approved" && polled.identityReady !== true && polled?.claim) {
+      throw new Error("Admission exposed a claim challenge before AIdenID identity evidence was ready.");
+    }
+    if (claimReady || TERMINAL.has(polled.status) || polled.status === "active") break;
+    const phase = polled.status === "approved" ? "identity" : "approval";
+    onPending({
+      admissionId: state.admissionId,
+      approveUrl: polled.approveUrl || state.approveUrl,
+      phase,
+      identityReady: polled.identityReady === true,
+      identity: polled.identity || null,
+    });
     if (now() >= deadline) {
       await fsp.writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
       return {
-        status: "pending",
+        status: polled.status === "approved" ? "approved" : "pending",
+        phase,
+        identityReady: polled.identityReady === true,
+        identity: polled.identity || null,
         admissionId: state.admissionId,
         approveUrl: polled.approveUrl || state.approveUrl,
         waited: true,