@adtl/gateway 0.7.0 → 0.8.1

package/src/config.ts

@@ -12,11 +12,16 @@
  *       docs:
  *         url: https://example.com/mcp
  *         headers: { Authorization: "Bearer ${DOCS_TOKEN}" }
+ *     interceptorServers:                # optional: more interceptor servers, run beside ADTL's
+ *       pii: { url: https://pii.example.com/mcp }
+ *     interceptorOverrides:              # optional: per-interceptor execution policy (SEP-2624)
+ *       adtl.label: { timeoutMs: 10000 }
  *     principal: { id: "${USER}" }       # optional: who runs this gateway (default: anonymous)
  *     roles:                             # optional: who may use which tools (deny by default)
  *       maintainers: { members: [alice], tools: ["github.*"] }
  *       readers:     { members: ["*"],   tools: ["github.read_*", "github.get_*"] }
  *     cedar: { policies: ./adtl.cedar }  # optional: attribute-based rules (see cedar.ts)
+ *     openfga: { url: http://localhost:8080, storeId: "${FGA_STORE_ID}" }  # optional: relationship rules (see openfga.ts)
  *     approvals:                         # optional: make "ask" really ask
  *       timeoutSeconds: 50
  *       ntfy: { topic: "${ADTL_NTFY_TOPIC}" }
@@ -27,7 +32,7 @@
  *         from: adtl@example.com
  *         to: you@example.com
  *
- * `${VAR}` in command, args, env, cwd, url, headers, approval settings and principal.id is
+ * `${VAR}` in command, args, env, cwd, url, headers, approval settings, openfga settings and principal.id is
  * replaced from the gateway's environment. A missing variable is a config error,
  * unless a default is given: `${VAR:-default}`.
  */
@@ -40,7 +45,7 @@ export const StdioUpstreamSchema = z
   .object({
     command: z.string().min(1),
     args: z.array(z.string()).default([]),
-    env: z.record(z.string()).default({}),
+    env: z.record(z.string(), z.string()).default({}),
     cwd: z.string().optional(),
   })
   .strict();
@@ -48,7 +53,7 @@ export const StdioUpstreamSchema = z
 export const HttpUpstreamSchema = z
   .object({
     url: z.string().min(1),
-    headers: z.record(z.string()).default({}),
+    headers: z.record(z.string(), z.string()).default({}),
   })
   .strict();
 
@@ -100,11 +105,16 @@ export const ApprovalsConfigSchema = z
      * default: a client that accepts elicitations by itself would approve calls.
      */
     elicitation: z.boolean().default(false),
+    /**
+     * Ask in the MCP client for a code from an authenticator app (`adtl-gateway
+     * totp setup`), instead of Allow or Deny. Wins over `elicitation`.
+     */
+    totp: z.boolean().default(false),
     /**
      * Each approver's own channel, by principal id. Policy rules with
      * `approvers: [role]` ask only these people, so the answer names who approved.
      */
-    approvers: z.record(z.object({ ntfy: NtfyConfigSchema }).strict()).optional(),
+    approvers: z.record(z.string(), z.object({ ntfy: NtfyConfigSchema }).strict()).optional(),
   })
   .strict();
 export type ApprovalsConfig = z.infer<typeof ApprovalsConfigSchema>;
@@ -119,7 +129,7 @@ export const PrincipalConfigSchema = z
   .object({
     type: z.enum(["user", "service"]).default("user"),
     id: z.string().min(1),
-    claims: z.record(z.unknown()).optional(),
+    claims: z.record(z.string(), z.unknown()).optional(),
   })
   .strict();
 export type PrincipalConfig = z.infer<typeof PrincipalConfigSchema>;
@@ -162,16 +172,66 @@ export const CedarConfigSchema = z
   .strict();
 export type CedarConfig = z.infer<typeof CedarConfigSchema>;
 
+export const OpenFgaConfigSchema = z
+  .object({
+    url: z.string().min(1),
+    storeId: z.string().min(1),
+    modelId: z.string().min(1).optional(),
+    token: z.string().min(1).optional(),
+    /** Relation checked when a tool has no rule of its own. */
+    relation: z.string().min(1).default("can_use"),
+    timeoutMs: z.number().int().positive().max(60_000).default(2000),
+    /** Per-tool rules, keyed `server.tool`. `object` is `type:id`, and `{argument}` is taken from the call. */
+    tools: z
+      .record(
+        z.string(),
+        z
+          .object({
+            relation: z.string().min(1).optional(),
+            object: z.string().regex(/^[^:\s]+:.+$/, 'Use "type:id", e.g. "repo:{owner}/{repo}"').optional(),
+          })
+          .strict(),
+      )
+      .default({}),
+  })
+  .strict();
+export type OpenFgaConfig = z.infer<typeof OpenFgaConfigSchema>;
+
+const PhaseSchema = z.enum(["request", "response"]);
+
+/** SEP-2624 InterceptorOverrides, set by the gateway owner for one interceptor. */
+export const InterceptorOverridesSchema = z
+  .object({
+    failOpen: z.boolean().optional(),
+    priorityHint: z
+      .union([z.number().int(), z.object({ request: z.number().int().optional(), response: z.number().int().optional() }).strict()])
+      .optional(),
+    mode: z.enum(["active", "audit"]).optional(),
+    timeoutMs: z.number().int().positive().max(600_000).optional(),
+    hooks: z
+      .array(z.object({ events: z.array(z.string().min(1)).min(1), phase: PhaseSchema }).strict())
+      .min(1, "hooks: list at least one hook, or leave it out to keep the declared hooks")
+      .optional(),
+  })
+  .strict();
+
 export const GatewayConfigSchema = z
   .object({
     upstreams: z
-      .record(UpstreamSchema)
+      .record(z.string(), UpstreamSchema)
       .refine((u) => Object.keys(u).length > 0, "At least one upstream server is required")
       .refine((u) => Object.keys(u).every((id) => UPSTREAM_ID.test(id)), {
         message: "Upstream ids may only contain letters, digits and '-' (they prefix tool names as <id>__<tool>)",
       }),
     /** How to start the interceptor server. Default: the bundled adtl-interceptors with this same config file. */
     interceptors: StdioUpstreamSchema.optional(),
+    /** More interceptor servers (stdio or Streamable HTTP) whose interceptors run beside ADTL's. */
+    interceptorServers: z
+      .record(z.string(), UpstreamSchema)
+      .refine((u) => Object.keys(u).every((id) => UPSTREAM_ID.test(id)), {
+        message: "Interceptor server ids may only contain letters, digits and '-'",
+      })
+      .default({}),
     /** Path of a JSONL audit log. Relative paths are resolved against the config file's directory. */
     audit: z.string().min(1).optional(),
     /**
@@ -183,15 +243,19 @@ export const GatewayConfigSchema = z
     approvals: ApprovalsConfigSchema.optional(),
     /** Timeout for each interceptor invocation, in milliseconds. */
     interceptorTimeoutMs: z.number().int().positive().default(5000),
+    /** Per-interceptor overrides of failOpen, priorityHint, mode, timeoutMs and hooks, by interceptor name. */
+    interceptorOverrides: z.record(z.string(), InterceptorOverridesSchema).default({}),
     /** Who runs this gateway. Passed to the authorizer and the interceptors. Default: anonymous. */
     principal: PrincipalConfigSchema.optional(),
     /** Role-based authorization: when present, a call no role grants is denied. */
     roles: z
-      .record(RoleSchema)
+      .record(z.string(), RoleSchema)
       .refine((r) => Object.keys(r).length > 0, "roles: needs at least one role (remove it to allow everyone)")
       .optional(),
     /** Cedar authorization. With roles as well, both must allow. */
     cedar: CedarConfigSchema.optional(),
+    /** OpenFGA authorization. With roles or cedar as well, all must allow. */
+    openfga: OpenFgaConfigSchema.optional(),
   })
   .strict();
 export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;

package/src/elicitation.ts

@@ -9,10 +9,15 @@
  * when `gateway.approvals.elicitation` is on and the client declares the
  * elicitation capability, and never for rules with named approvers: the
  * client can't say who answered.
+ *
+ * With `gateway.approvals.totp`, the prompt asks for a code from the person's
+ * authenticator app instead of Allow or Deny, so a client that accepts
+ * prompts by itself can't approve anything. Three wrong codes count as Deny.
  */
 import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { ElicitResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import type { AnswerFn, ApprovalEvent, ApprovalRequest, Notifier } from "./approvals.js";
+import type { TotpVerifier } from "./totp.js";
 
 interface Listening {
   answer: AnswerFn;
@@ -29,11 +34,22 @@ function message(request: ApprovalRequest): string {
   return `ADTL: allow ${request.server}.${request.tool}?\n\n${request.reason}\n\nRule: ${rule}. Allow runs this one call; Deny or no answer stops it.`;
 }
 
+function codeMessage(request: ApprovalRequest, wrong: number): string {
+  const rule = request.matched.join(", ") || "default";
+  const again = wrong > 0 ? "That code was not right. " : "";
+  return `ADTL: allow ${request.server}.${request.tool}?\n\n${request.reason}\n\nRule: ${rule}. ${again}Enter the code from your authenticator app to run this one call; decline or no answer stops it.`;
+}
+
+const MAX_CODE_ATTEMPTS = 3;
+
 export class ElicitationChannel implements Notifier {
   readonly name = "elicitation";
   private readonly listening = new Map<string, Listening>();
 
-  constructor(private readonly server: Server) {}
+  constructor(
+    private readonly server: Server,
+    private readonly totp?: TotpVerifier,
+  ) {}
 
   async listen(request: ApprovalRequest, answer: AnswerFn, signal: AbortSignal): Promise<void> {
     this.listening.set(request.id, { answer, signal });
@@ -46,22 +62,24 @@ export class ElicitationChannel implements Notifier {
     const l = this.listening.get(event.request.id);
     if (!l) throw new Error("not listening for this request");
     // A plain request, not Server.elicitInput(): clients that declare only `elicitation: {}` support forms too.
-    const result = await this.server.request(
-      {
-        method: "elicitation/create",
-        params: {
-          message: message(event.request),
-          requestedSchema: {
-            type: "object",
-            properties: {
-              decision: { type: "string", title: "Decision", enum: ["allow", "deny"], description: "allow runs this one call; deny stops it" },
-            },
-            required: ["decision"],
-          },
-        },
-      },
-      ElicitResultSchema,
-      { signal: l.signal, timeout: Math.max(1, event.request.expiresAt.getTime() - Date.now()) },
+    const ask = (text: string, properties: Record<string, unknown>, required: string) =>
+      this.server.request(
+        { method: "elicitation/create", params: { message: text, requestedSchema: { type: "object", properties, required: [required] } } } as never,
+        ElicitResultSchema,
+        { signal: l.signal, timeout: Math.max(1, event.request.expiresAt.getTime() - Date.now()) },
+      );
+    if (this.totp) {
+      for (let wrong = 0; wrong < MAX_CODE_ATTEMPTS; wrong++) {
+        const r = await ask(codeMessage(event.request, wrong), { code: { type: "string", title: "Code", description: "6 digits from your authenticator app" } }, "code");
+        if (r.action !== "accept") break;
+        if (this.totp.verify(String(r.content?.code ?? ""))) return void l.answer(event.tokens.allow);
+      }
+      return void l.answer(event.tokens.deny);
+    }
+    const result = await ask(
+      message(event.request),
+      { decision: { type: "string", title: "Decision", enum: ["allow", "deny"], description: "allow runs this one call; deny stops it" } },
+      "decision",
     );
     const allow = result.action === "accept" && result.content?.decision === "allow";
     l.answer(allow ? event.tokens.allow : event.tokens.deny);

package/src/gateway.ts

@@ -57,12 +57,13 @@ import type { InvocationContext } from "@adtl/interceptors";
 import { callBindingHash } from "@adtl/labels";
 import type { ApprovalBroker, ApprovalResult } from "./approvals.js";
 import { ElicitationChannel, supportsElicitation } from "./elicitation.js";
+import type { TotpVerifier } from "./totp.js";
 import type { AuditEntry, AuditSink } from "./audit.js";
 import { authorize, type AuthorizationRequest, type Authorizer, type Denial, type Principal } from "./authorizer.js";
 import { TOOL_SEPARATOR } from "./config.js";
 import type { Blocked, InterceptorInvoker, InterceptorRun, PhaseOutcome } from "./invoker.js";
 
-export const GATEWAY_VERSION = "0.7.0";
+export const GATEWAY_VERSION = "0.8.1";
 
 /** `_meta` key on gateway-generated error results describing why a call was stopped. */
 export const GATEWAY_DECISION_KEY = "adtl/gateway";
@@ -115,6 +116,10 @@ export interface AdtlGatewayOptions {
   approverRoles?: Map<string, string[]>;
   /** Also ask for approval in the MCP client, when it supports elicitation. */
   elicitApprovals?: boolean;
+  /** Ask for a code from an authenticator app in the MCP client, instead of Allow or Deny. */
+  totp?: TotpVerifier;
+  /** The (sub-)agent this gateway serves, recorded on every audit entry. */
+  agent?: { id: string; type?: string };
 }
 
 /**
@@ -174,8 +179,10 @@ export class AdtlGateway {
   private readonly approvals: ApprovalBroker | undefined;
   private readonly authorizers: Authorizer[];
   private readonly principal: Principal;
+  private readonly agent: { agent: { id: string; type?: string } } | Record<string, never>;
   private readonly approverRoles: Map<string, string[]>;
   private readonly elicitApprovals: boolean;
+  private readonly totp: TotpVerifier | undefined;
   /** The server the agent is connected to, for elicitation. */
   private server: Server | undefined;
   private routes = new Map<string, Route>();
@@ -193,8 +200,10 @@ export class AdtlGateway {
     this.approvals = opts.approvals;
     this.authorizers = opts.authorizer === undefined ? [] : [opts.authorizer].flat();
     this.principal = opts.principal ?? { type: "anonymous" };
+    this.agent = opts.agent ? { agent: opts.agent } : {};
     this.approverRoles = opts.approverRoles ?? new Map();
     this.elicitApprovals = opts.elicitApprovals === true;
+    this.totp = opts.totp;
   }
 
   /** Ask each authorizer in turn. Returns the first denial; in audit mode the caller logs it and carries on. */
@@ -450,6 +459,7 @@ export class AdtlGateway {
       this.audit?.write({
         ts: context.timestamp!,
         sessionId: this.sessionId,
+        ...this.agent,
         event,
         server: upstream,
         ...target,
@@ -501,7 +511,7 @@ export class AdtlGateway {
     }
     const label = infoOf(res, "adtl.label");
     finish({ outcome: "forwarded", ...audit, label: label.label, ...(label.ledger ? { ledger: label.ledger } : {}),
-      ...(label.records ? { records: label.records } : {}), sessionLabel: label.sessionLabel, warnings });
+      ...(label.records ? { records: label.records } : {}), ...(label.recordIds ? { recordIds: label.recordIds } : {}), sessionLabel: label.sessionLabel, warnings });
     return (res.payload as { result: R }).result;
   }
 
@@ -525,7 +535,7 @@ export class AdtlGateway {
       server: route.upstream,
       ...(route.annotations ? { toolAnnotations: route.annotations } : {}),
     };
-    const base = { sessionId: this.sessionId, event: "tools/call" as const, server: route.upstream, tool: route.tool };
+    const base = { sessionId: this.sessionId, ...this.agent, event: "tools/call" as const, server: route.upstream, tool: route.tool };
     let denied: Denial | undefined;
     const ran: InterceptorRun[] = [];
     const finish = (entry: Omit<AuditEntry, keyof typeof base | "ts" | "durationMs">) =>
@@ -568,7 +578,7 @@ export class AdtlGateway {
       const lists = Array.isArray(policy.approvers) ? (policy.approvers as string[][]) : undefined;
       const approvers = lists ? eligibleApprovers(lists, this.approverRoles) : undefined;
       // The client's own prompt, if enabled and supported; never for named approvers (it can't say who answered).
-      const elicit = this.elicitApprovals && !approvers && this.server && supportsElicitation(this.server) ? [new ElicitationChannel(this.server)] : [];
+      const elicit = (this.elicitApprovals || this.totp) && !approvers && this.server && supportsElicitation(this.server) ? [new ElicitationChannel(this.server, this.totp)] : [];
       if (b.decision === "ask" && this.approvals && (this.approvals.canApprove || elicit.length > 0) && typeof hash === "string") {
         this.log.info(`ask ${name}: waiting for approval${approvers ? ` from ${approvers.join(", ") || "nobody"}` : ""} (${b.reason})`);
         approval = await this.waitForApproval(opts, () =>
@@ -630,7 +640,9 @@ export class AdtlGateway {
     // 2. Forward to the upstream server.
     let result: CallToolResult;
     try {
-      result = (await client.callTool({ name: forwarded.name, arguments: forwarded.arguments })) as CallToolResult;
+      // A mutator may add request _meta (e.g. fides-gateway labels); pass it on.
+      const meta = (forwarded as { _meta?: Record<string, unknown> })._meta;
+      result = (await client.callTool({ name: forwarded.name, arguments: forwarded.arguments, ...(meta ? { _meta: meta } : {}) })) as CallToolResult;
     } catch (err) {
       const reason = (err as Error).message;
       finish({ outcome: "upstream_error", ...(decision ? { decision } : {}), ...approved, reason, callHash: policy.callHash, ...(audit ? { mode: "audit" as const } : {}), warnings: req.warnings });
@@ -663,6 +675,7 @@ export class AdtlGateway {
       label: label.label,
       ...(label.ledger ? { ledger: label.ledger } : {}),
       ...(label.records ? { records: label.records } : {}),
+      ...(label.recordIds ? { recordIds: label.recordIds } : {}),
       sessionLabel: label.sessionLabel,
       warnings: [...req.warnings, ...res.warnings],
     });

package/src/hooks/agentLinks.ts

@@ -0,0 +1,58 @@
+/**
+ * Which session a Claude Code sub-agent belongs to.
+ *
+ * Claude Code's SubagentStart hook reports the parent's `session_id` with the
+ * new sub-agent's `agent_id`. Recording that link lets the sub-agent's later
+ * hook calls use the parent's label even if they ever report a session id of
+ * their own: the sub-agent starts from what its parent has seen, and what it
+ * reads taints the parent. Links live beside the session files, which the
+ * hooks already protect from the agent.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+export interface AgentLinks {
+  /** The session `agentId` was started in, if known. */
+  parentOf(agentId: string): string | undefined;
+  link(agentId: string, sessionId: string): void;
+}
+
+const SAFE_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+export class FileAgentLinks implements AgentLinks {
+  private readonly dir: string;
+
+  constructor(sessionsDir: string) {
+    this.dir = join(sessionsDir, "agents");
+  }
+
+  private pathOf(agentId: string): string {
+    const name = SAFE_ID.test(agentId) ? agentId : `h-${createHash("sha256").update(agentId).digest("hex")}`;
+    return join(this.dir, `${name}.parent`);
+  }
+
+  parentOf(agentId: string): string | undefined {
+    try {
+      return readFileSync(this.pathOf(agentId), "utf8").trim() || undefined;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw err;
+    }
+  }
+
+  link(agentId: string, sessionId: string): void {
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    writeFileSync(this.pathOf(agentId), sessionId, { encoding: "utf8", mode: 0o600 });
+  }
+}
+
+export class InMemoryAgentLinks implements AgentLinks {
+  private readonly links = new Map<string, string>();
+  parentOf(agentId: string): string | undefined {
+    return this.links.get(agentId);
+  }
+  link(agentId: string, sessionId: string): void {
+    this.links.set(agentId, sessionId);
+  }
+}

package/src/hooks/claudeCode.ts

@@ -8,6 +8,8 @@
  *                       allow → no answer, so Claude Code's own permissions apply
  *   PostToolUse         labels the tool's output and adds it to the session label
  *   PostToolUseFailure  same: a failed tool's error output still reaches the model
+ *   SubagentStart       links the new sub-agent to its parent's session, so its
+ *                       calls start from the parent's label and taint it
  *
  * Built-in tools are labeled as the server `claude-code` (see preset.ts); MCP
  * tools `mcp__<server>__<tool>` as `<server>`. Tools of the gateway's own MCP
@@ -24,7 +26,7 @@
  *
  * Errors fail closed: a PreToolUse hook that can't decide denies the call.
  */
-import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import {
   callHash,
   evaluatePolicy,
@@ -33,11 +35,14 @@ import {
   type AdtlConfig,
   type Decision,
   type PolicyDecision,
+  type Label,
   type SessionStore,
   join,
 } from "@adtl/labels";
 import { chunkHashes, valueHashes, type Ledger } from "@adtl/ledger";
 import type { AuditEntry, AuditSink } from "../audit.js";
+import { TOTP_KEYCHAIN_SERVICE } from "../totp.js";
+import type { AgentLinks } from "./agentLinks.js";
 import { CLAUDE_CODE_PRESET, CLAUDE_CODE_SERVER } from "./preset.js";
 
 export interface HookInput {
@@ -64,8 +69,10 @@ export interface HookOptions {
   audit?: AuditSink;
   /** Label ledger shared with the gateway. */
   ledger?: Ledger;
+  /** Sub-agent → parent session links, from SubagentStart. */
+  agents?: AgentLinks;
   /** Files the agent must not change: the ADTL config, the session directory and the ledger. */
-  protect?: { configPath?: string; sessionsDir?: string; ledgerPath?: string; auditPath?: string; signingKeyPath?: string };
+  protect?: { configPath?: string; sessionsDir?: string; ledgerPath?: string; auditPath?: string; signingKeyPath?: string; totpPath?: string };
 }
 
 /** What the hook process prints and exits with. */
@@ -138,6 +145,9 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (protect.signingKeyPath && abs === resolve(protect.signingKeyPath)) {
       return { decision: "block", reason: "The agent may not touch the ADTL signing key" };
     }
+    if (protect.totpPath && abs.startsWith(dirname(resolve(protect.totpPath)) + sep + "totp-")) {
+      return { decision: "block", reason: "The agent may not touch the ADTL TOTP secret" };
+    }
   }
   const command = typeof args.command === "string" ? args.command : undefined;
   if (command !== undefined && ["Bash", "Monitor"].includes(route.tool)) {
@@ -155,6 +165,9 @@ function protectedTarget(input: HookInput, route: { server: string; tool: string
     if (protect.signingKeyPath && command.includes(basename(protect.signingKeyPath))) {
       return { decision: "ask", reason: "This command touches the ADTL signing key" };
     }
+    if ([TOTP_KEYCHAIN_SERVICE, "totp-secret", "totp-last-step", protect.totpPath].some((m) => m && command.includes(m))) {
+      return { decision: "ask", reason: "This command touches the ADTL TOTP secret" };
+    }
   }
   return undefined;
 }
@@ -172,19 +185,37 @@ export function addedLines(output: unknown): string[] {
   return out;
 }
 
+/**
+ * The session whose label a hook call reads and adds to: a linked sub-agent's
+ * parent session, else the call's own. When the two differ, the sub-agent's own
+ * label is read too, so nothing it saw is lost.
+ */
+function sessionFor(input: HookInput & { session_id: string }, opts: HookOptions): { id: string; get(): Label } {
+  const parent = typeof input.agent_id === "string" ? opts.agents?.parentOf(input.agent_id) : undefined;
+  if (!parent || parent === input.session_id) return { id: input.session_id, get: () => opts.sessions.get(input.session_id) };
+  return { id: parent, get: () => join(opts.sessions.get(parent), opts.sessions.get(input.session_id)) };
+}
+
 export function handleHook(input: HookInput, opts: HookOptions): HookOutcome {
   const event = input.hook_event_name;
+  if (event === "SubagentStart") {
+    if (typeof input.agent_id === "string" && typeof input.session_id === "string" && input.session_id !== "") {
+      opts.agents?.link(input.agent_id, input.session_id);
+    }
+    return NOTHING;
+  }
   if (event !== "PreToolUse" && event !== "PostToolUse" && event !== "PostToolUseFailure") return NOTHING;
   if (typeof input.tool_name !== "string" || typeof input.session_id !== "string" || input.session_id === "") {
     return failure(event, "hook input has no tool_name or session_id");
   }
+  const session = sessionFor(input as HookInput & { session_id: string }, opts);
   const route = routeTool(input.tool_name, opts.gatewayServer);
   if (!route) return NOTHING;
   const config = withClaudeCodePreset(opts.config);
   const ts = new Date().toISOString();
   const agent =
     typeof input.agent_id === "string" ? { agent: { id: input.agent_id, ...(typeof input.agent_type === "string" ? { type: input.agent_type } : {}) } } : {};
-  const base = { ts, sessionId: input.session_id, event: "tools/call" as const, ...route, via: "claude-code-hook" as const, ...agent };
+  const base = { ts, sessionId: session.id, event: "tools/call" as const, ...route, via: "claude-code-hook" as const, ...agent };
 
   if (event !== "PreToolUse") {
     const output = input.tool_response ?? input.error ?? null;
@@ -197,20 +228,20 @@ export function handleHook(input: HookInput, opts: HookOptions): HookOutcome {
         ledger = { chunks: match.chunks, writers: match.writers };
       }
       // What the tool was given came from the session as it was before this output.
-      const before = opts.sessions.get(input.session_id);
+      const before = session.get();
       const written = [...valueHashes(input.tool_input ?? {}), ...addedLines(output).flatMap(chunkHashes)];
-      opts.ledger.record(written, before, input.session_id, route);
+      opts.ledger.record(written, before, session.id, route);
     }
-    const sessionLabel = opts.sessions.observe(input.session_id, label);
+    const sessionLabel = join(session.get(), opts.sessions.observe(session.id, label));
     opts.audit?.write({ ...base, outcome: "forwarded", label, ...(ledger ? { ledger } : {}), sessionLabel, durationMs: 0 });
     return NOTHING;
   }
 
   const hash = callHash(route.server, route.tool, input.tool_input ?? {});
-  const session = opts.sessions.get(input.session_id);
+  const current = session.get();
   const guard = protectedTarget(input, route, opts.protect);
   const policy: PolicyDecision = evaluatePolicy(config.policy, {
-    session,
+    session: current,
     ...route,
     egress: toolEgress(config, route.server, route.tool),
   });
@@ -229,7 +260,7 @@ export function handleHook(input: HookInput, opts: HookOptions): HookOutcome {
     reason: d.reason,
     matched: d.matched,
     callHash: hash,
-    sessionLabel: session,
+    sessionLabel: current,
     durationMs: 0,
   };
   opts.audit?.write(entry);

package/src/hooks/index.ts

@@ -1,3 +1,4 @@
 export * from "./claudeCode.js";
 export * from "./preset.js";
 export * from "./run.js";
+export * from "./agentLinks.js";

package/src/hooks/run.ts

@@ -1,6 +1,6 @@
 /**
  * `adtl-gateway hook --config adtl.yaml`: the command Claude Code runs for
- * PreToolUse, PostToolUse and PostToolUseFailure. Reads the hook event from
+ * PreToolUse, PostToolUse, PostToolUseFailure and SubagentStart. Reads the hook event from
  * stdin and answers on stdout (JSON) or stderr (with exit code 2).
  *
  * The config needs no `gateway:` section; if there is one, its `audit` log and
@@ -13,6 +13,8 @@ import { Ledger, defaultLedgerPath } from "@adtl/ledger";
 import { parseConfigText } from "@adtl/interceptors";
 import { parse as parseYaml } from "yaml";
 import { JsonlAuditLog } from "../audit.js";
+import { totpSecretPath } from "../totp.js";
+import { FileAgentLinks } from "./agentLinks.js";
 import { failure, handleHook, type HookInput, type HookOutcome } from "./claudeCode.js";
 
 export interface RunHookOptions {
@@ -46,11 +48,12 @@ export async function runHook(opts: RunHookOptions): Promise<HookOutcome> {
     return handleHook(input, {
       config,
       sessions: new FileSessionStore(sessionsDir),
+      agents: new FileAgentLinks(sessionsDir),
       ...(ledger ? { ledger } : {}),
       ...(opts.gatewayServer ? { gatewayServer: opts.gatewayServer } : {}),
       mode: gw.mode === "audit" ? "audit" : "active",
       ...(auditPath ? { audit: new JsonlAuditLog(auditPath) } : {}),
-      protect: { configPath: path, sessionsDir, ledgerPath, ...(auditPath ? { auditPath } : {}), signingKeyPath: defaultSigningKeyPath(env) },
+      protect: { configPath: path, sessionsDir, ledgerPath, ...(auditPath ? { auditPath } : {}), signingKeyPath: defaultSigningKeyPath(env), totpPath: totpSecretPath(env) },
     });
   } catch (err) {
     return failure(input.hook_event_name, (err as Error).message);

package/src/index.ts

@@ -13,6 +13,9 @@ export * from "./ledgerCli.js";
 export * from "./auditCli.js";
 export * from "./roles.js";
 export * from "./cedar.js";
+export * from "./openfga.js";
+export * from "./totp.js";
+export * from "./totpCli.js";
 export * from "./elicitation.js";
 export * from "./receipt.js";
 export * from "./receiptCli.js";

package/src/init/suggest.ts

@@ -4,13 +4,15 @@
  * Without a preset, rules come from the MCP tool annotations. Those are the
  * server's own claims, so they only decide egress; integrity is always
  * untrusted and confidentiality private until the owner says otherwise.
+ * The draft action-metadata extension's `inputMetadata.destination`, when a
+ * tool declares one, decides egress ahead of the legacy hints.
  * Missing hints take the MCP spec defaults (readOnlyHint false, openWorldHint true).
  *
  * Merging never changes an entry that is already in the file: the owner's
  * choices win, and `init` can be re-run to pick up new tools.
  */
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import type { ToolRule } from "@adtl/labels";
+import { destinationEgress, readActionMetadata, type ToolRule } from "@adtl/labels";
 import { isMap, isScalar, type Document, type YAMLMap } from "yaml";
 import { choosePreset, PRESETS, type Preset } from "./presets.js";
 
@@ -40,6 +42,13 @@ const UNKNOWN_DEFAULTS: ToolRule = { integrity: "untrusted", confidentiality: "p
 
 /** A rule from the tool's MCP annotations alone. */
 export function ruleFromHints(annotations: Tool["annotations"]): Omit<ToolSuggestion, "name"> {
+  const meta = readActionMetadata(annotations);
+  const declared = destinationEgress(meta.destination);
+  if (declared) {
+    const extra = [meta.outcome, meta.requiresReview ? "requires review" : undefined].filter(Boolean).join(", ");
+    const why = `action-metadata: destination ${meta.destination}${extra ? `, ${extra}` : ""} (review)`;
+    return { rule: { integrity: "untrusted", confidentiality: "private", egress: declared }, why };
+  }
   const readOnly = annotations?.readOnlyHint === true;
   const openWorld = annotations?.openWorldHint !== false;
   const egress = readOnly ? (openWorld ? "external" : "none") : openWorld ? "public" : "internal";