@adtl/gateway 0.7.0 → 0.8.0

package/src/config.ts

@@ -12,6 +12,10 @@
  *       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.*"] }
@@ -162,6 +166,24 @@ export const CedarConfigSchema = z
   .strict();
 export type CedarConfig = z.infer<typeof CedarConfigSchema>;
 
+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
@@ -172,6 +194,13 @@ export const GatewayConfigSchema = z
       }),
     /** 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(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,6 +212,8 @@ 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(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. */

package/src/gateway.ts

@@ -62,7 +62,7 @@ import { authorize, type AuthorizationRequest, type Authorizer, type Denial, typ
 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.0";
 
 /** `_meta` key on gateway-generated error results describing why a call was stopped. */
 export const GATEWAY_DECISION_KEY = "adtl/gateway";
@@ -115,6 +115,8 @@ export interface AdtlGatewayOptions {
   approverRoles?: Map<string, string[]>;
   /** Also ask for approval in the MCP client, when it supports elicitation. */
   elicitApprovals?: boolean;
+  /** The (sub-)agent this gateway serves, recorded on every audit entry. */
+  agent?: { id: string; type?: string };
 }
 
 /**
@@ -174,6 +176,7 @@ 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;
   /** The server the agent is connected to, for elicitation. */
@@ -193,6 +196,7 @@ 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;
   }
@@ -450,6 +454,7 @@ export class AdtlGateway {
       this.audit?.write({
         ts: context.timestamp!,
         sessionId: this.sessionId,
+        ...this.agent,
         event,
         server: upstream,
         ...target,
@@ -501,7 +506,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 +530,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">) =>
@@ -630,7 +635,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 +670,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
@@ -33,11 +35,13 @@ 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 type { AgentLinks } from "./agentLinks.js";
 import { CLAUDE_CODE_PRESET, CLAUDE_CODE_SERVER } from "./preset.js";
 
 export interface HookInput {
@@ -64,6 +68,8 @@ 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 };
 }
@@ -172,19 +178,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 +221,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 +253,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,7 @@ import { Ledger, defaultLedgerPath } from "@adtl/ledger";
 import { parseConfigText } from "@adtl/interceptors";
 import { parse as parseYaml } from "yaml";
 import { JsonlAuditLog } from "../audit.js";
+import { FileAgentLinks } from "./agentLinks.js";
 import { failure, handleHook, type HookInput, type HookOutcome } from "./claudeCode.js";
 
 export interface RunHookOptions {
@@ -46,6 +47,7 @@ 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",

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";

package/src/invoker.ts

@@ -11,8 +11,11 @@
  * their mutations are not applied. An interceptor that fails (error or
  * timeout) blocks the message unless it declares `failOpen: true`.
  *
- * The invoker may override every interceptor's `mode`, as SEP-2624 allows
- * (e.g. audit in staging, active in production).
+ * The invoker may override execution policy, as SEP-2624 allows: every
+ * interceptor's `mode` at once (e.g. audit in staging, active in production),
+ * and per interceptor its `failOpen`, `priorityHint`, `mode`, `timeoutMs` and
+ * `hooks` (narrowed only, never widened). A global mode wins over a
+ * per-interceptor one, so `--audit` always stops nothing.
  */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
@@ -21,6 +24,7 @@ import {
   LIST_METHOD,
   type ConfirmationRequest,
   type InterceptorDefinition,
+  type InterceptorHook,
   type InterceptorResult,
   type InvocationContext,
   type MutationResult,
@@ -34,17 +38,49 @@ const AnyResult = z.object({}).passthrough();
 
 type Loose = Record<string, unknown>;
 
-/** Untyped request: interceptor methods are extension methods the SDK does not type. */
+/**
+ * Untyped request: interceptor methods are extension methods the SDK does not type.
+ * The timeout is enforced here too, so a client that ignores it can't hang a phase.
+ */
 function request(client: Client, method: string, params: unknown, timeout: number): Promise<Loose> {
   const r = client.request as unknown as (req: unknown, schema: unknown, opts: unknown) => Promise<Loose>;
-  return r.call(client, { method, params }, AnyResult, { timeout });
+  const controller = new AbortController();
+  let timer: NodeJS.Timeout | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`timed out after ${timeout} ms`));
+    }, timeout);
+  });
+  return Promise.race([r.call(client, { method, params }, AnyResult, { timeout, signal: controller.signal }), expired]).finally(() =>
+    clearTimeout(timer),
+  );
 }
 
 export type InterceptorMode = NonNullable<InterceptorDefinition["mode"]>;
 
+/** Invoker-side execution policy for one interceptor (SEP-2624 "Invoker Overrides"). */
+export interface InterceptorOverrides {
+  failOpen?: boolean;
+  /** Ignored for validators. */
+  priorityHint?: InterceptorDefinition["priorityHint"];
+  mode?: InterceptorMode;
+  timeoutMs?: number;
+  /** Must be a subset of the interceptor's declared hooks. */
+  hooks?: InterceptorHook[];
+}
+
 export interface BoundInterceptor {
   client: Client;
   definition: InterceptorDefinition;
+  /** Id of the interceptor server that advertised it, for messages. */
+  server?: string;
+  /**
+   * Whether the gateway's per-call `config` (ADTL's server, tool and
+   * annotations) is sent. Other servers' interceptors get none, so their
+   * own defaults apply. Default: true.
+   */
+  sendConfig?: boolean;
 }
 
 export interface Blocked {
@@ -68,6 +104,7 @@ export interface InterceptorRun {
   modeFrom: "override" | "default";
   failOpen: boolean;
   failOpenFrom: "override" | "default";
+  timeoutMs: number;
   /** Set when the invocation errored or timed out. */
   failed?: true;
 }
@@ -89,15 +126,70 @@ export interface InvokeOptions {
   context: InvocationContext;
 }
 
-function priority(def: InterceptorDefinition, phase: Phase): number {
-  const p = def.priorityHint;
+/** SEP-2624 `resolvePriority`: the override's hint, else the interceptor's. */
+export function resolvePriority(def: InterceptorDefinition, overrides: InterceptorOverrides | undefined, phase: Phase): number {
+  const p = overrides?.priorityHint ?? def.priorityHint;
   if (p === undefined) return 0;
   if (typeof p === "number") return p;
   return p[phase] ?? 0;
 }
 
-function hooks(def: InterceptorDefinition, event: string, phase: Phase): boolean {
-  return def.hooks.some((h) => h.phase === phase && (h.events.includes(event) || h.events.includes("*")));
+function matches(hooks: InterceptorHook[], event: string, phase: Phase): boolean {
+  return hooks.some((h) => h.phase === phase && (h.events.includes(event) || h.events.includes("*")));
+}
+
+/**
+ * Problems with `overrides` for these interceptors: an unknown name, or hooks
+ * that widen what the interceptor declares (which SEP-2624 says to reject).
+ */
+export function checkOverrides(defs: InterceptorDefinition[], overrides: Record<string, InterceptorOverrides>): string[] {
+  const problems: string[] = [];
+  for (const [name, o] of Object.entries(overrides)) {
+    const def = defs.find((d) => d.name === name);
+    if (!def) {
+      problems.push(`${name}: no such interceptor (offered: ${defs.map((d) => d.name).join(", ")})`);
+      continue;
+    }
+    for (const h of o.hooks ?? []) {
+      for (const event of h.events) {
+        const declared = def.hooks.some((d) => d.phase === h.phase && (d.events.includes("*") || (event !== "*" && d.events.includes(event))));
+        if (!declared) problems.push(`${name}: hooks may only narrow the declared hooks, and ${event} (${h.phase}) is not declared`);
+      }
+    }
+  }
+  return problems;
+}
+
+/** Interceptor names offered by more than one server: each must be invoked on its own server, so names must be unique. */
+export function duplicateInterceptors(bound: BoundInterceptor[]): string[] {
+  const servers = new Map<string, string[]>();
+  for (const b of bound) servers.set(b.definition.name, [...(servers.get(b.definition.name) ?? []), b.server ?? "?"]);
+  return [...servers].filter(([, s]) => s.length > 1).map(([name, s]) => `${name} (offered by ${s.join(", ")})`);
+}
+
+/**
+ * Mutators that would run after `name` on a phase both hook, so they see (and
+ * could change or drop) what it wrote. Used to warn when another server's
+ * mutator runs after adtl.label.
+ */
+export function mutatorsAfter(bound: BoundInterceptor[], name: string, overrides: Record<string, InterceptorOverrides> = {}): string[] {
+  const target = bound.find((b) => b.definition.name === name);
+  if (!target) return [];
+  const hooksOf = (b: BoundInterceptor) => overrides[b.definition.name]?.hooks ?? b.definition.hooks;
+  const shares = (b: BoundInterceptor, phase: Phase) =>
+    hooksOf(b).some((h) => h.phase === phase && hooksOf(target).some((t) => t.phase === phase && (h.events.includes("*") || t.events.includes("*") || h.events.some((e) => t.events.includes(e)))));
+  const after: string[] = [];
+  for (const b of bound) {
+    if (b === target || b.definition.type !== "mutation") continue;
+    const late = (["request", "response"] as const).some((phase) => {
+      if (!shares(b, phase)) return false;
+      const p = resolvePriority(b.definition, overrides[b.definition.name], phase);
+      const t = resolvePriority(target.definition, overrides[name], phase);
+      return p > t || (p === t && b.definition.name.localeCompare(name) > 0);
+    });
+    if (late) after.push(b.definition.name);
+  }
+  return after;
 }
 
 export class InterceptorInvoker {
@@ -106,13 +198,15 @@ export class InterceptorInvoker {
     private readonly timeoutMs = 5000,
     /** Overrides the mode every interceptor declares. */
     readonly modeOverride?: InterceptorMode,
+    /** Per-interceptor overrides, by name. Check them with `checkOverrides` first. */
+    private readonly overrides: Record<string, InterceptorOverrides> = {},
   ) {}
 
   /** Discover the interceptors an interceptor server offers. */
-  static async discover(client: Client): Promise<BoundInterceptor[]> {
+  static async discover(client: Client, opts: { server?: string; sendConfig?: boolean } = {}): Promise<BoundInterceptor[]> {
     const res = await request(client, LIST_METHOD, {}, 10_000);
     const defs = (res.interceptors ?? []) as InterceptorDefinition[];
-    return defs.map((definition) => ({ client, definition }));
+    return defs.map((definition) => ({ client, definition, ...opts }));
   }
 
   get definitions(): InterceptorDefinition[] {
@@ -133,34 +227,63 @@ export class InterceptorInvoker {
     return out;
   }
 
+  private override(i: BoundInterceptor): InterceptorOverrides | undefined {
+    return this.overrides[i.definition.name];
+  }
+
+  private mode(i: BoundInterceptor): InterceptorMode {
+    return this.modeOverride ?? this.override(i)?.mode ?? i.definition.mode ?? "active";
+  }
+
   private isAudit(i: BoundInterceptor): boolean {
-    return (this.modeOverride ?? i.definition.mode) === "audit";
+    return this.mode(i) === "audit";
+  }
+
+  private failOpen(i: BoundInterceptor): boolean {
+    return (this.override(i)?.failOpen ?? i.definition.failOpen) === true;
   }
 
-  /** Record that `i` runs in `phase`, with its resolved policy. The gateway has no failOpen overrides. */
+  private timeout(i: BoundInterceptor): number {
+    return this.override(i)?.timeoutMs ?? this.timeoutMs;
+  }
+
+  /** Record that `i` runs in `phase`, with its resolved policy. */
   private run(i: BoundInterceptor, phase: Phase, out: PhaseOutcome): InterceptorRun {
+    const o = this.override(i);
     const r: InterceptorRun = {
       name: i.definition.name,
       phase,
-      mode: this.modeOverride ?? i.definition.mode ?? "active",
-      modeFrom: this.modeOverride ? "override" : "default",
-      failOpen: i.definition.failOpen === true,
-      failOpenFrom: "default",
+      mode: this.mode(i),
+      modeFrom: this.modeOverride || o?.mode ? "override" : "default",
+      failOpen: this.failOpen(i),
+      failOpenFrom: o?.failOpen !== undefined ? "override" : "default",
+      timeoutMs: this.timeout(i),
     };
     out.ran.push(r);
     return r;
   }
 
   private select(type: InterceptorDefinition["type"], event: string, phase: Phase): BoundInterceptor[] {
-    return this.interceptors.filter((i) => i.definition.type === type && hooks(i.definition, event, phase));
+    return this.interceptors.filter(
+      (i) => i.definition.type === type && matches(this.override(i)?.hooks ?? i.definition.hooks, event, phase),
+    );
   }
 
   private async invoke(i: BoundInterceptor, phase: Phase, opts: InvokeOptions, payload: unknown): Promise<InterceptorResult> {
+    const timeoutMs = this.timeout(i);
     const res = await request(
       i.client,
       INVOKE_METHOD,
-      { name: i.definition.name, event: opts.event, phase, payload, config: opts.config, timeoutMs: this.timeoutMs, context: opts.context },
-      this.timeoutMs,
+      {
+        name: i.definition.name,
+        event: opts.event,
+        phase,
+        payload,
+        ...(i.sendConfig === false ? {} : { config: opts.config }),
+        timeoutMs,
+        context: opts.context,
+      },
+      timeoutMs,
     );
     return res as unknown as InterceptorResult;
   }
@@ -168,7 +291,7 @@ export class InterceptorInvoker {
   /** Handle an interceptor failure. Returns false if the phase must stop. */
   private failed(i: BoundInterceptor, err: unknown, out: PhaseOutcome): boolean {
     const msg = `${i.definition.name} failed: ${err instanceof Error ? err.message : String(err)}`;
-    if (this.isAudit(i) || i.definition.failOpen === true) {
+    if (this.isAudit(i) || this.failOpen(i)) {
       out.warnings.push(msg);
       return true;
     }
@@ -179,7 +302,9 @@ export class InterceptorInvoker {
   /** Sequential mutations, atomic: on failure the original payload is kept. */
   private async mutate(phase: Phase, opts: InvokeOptions, out: PhaseOutcome): Promise<boolean> {
     const selected = this.select("mutation", opts.event, phase).sort(
-      (a, b) => priority(a.definition, phase) - priority(b.definition, phase) || a.definition.name.localeCompare(b.definition.name),
+      (a, b) =>
+        resolvePriority(a.definition, this.override(a), phase) - resolvePriority(b.definition, this.override(b), phase) ||
+        a.definition.name.localeCompare(b.definition.name),
     );
     let payload = out.payload;
     for (const i of selected) {