@adtl/gateway 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adtl/gateway",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Experimental: MCP gateway that labels every tool result and blocks risky tool calls using ADTL trust labels",
   "keywords": [
     "mcp",
@@ -47,18 +47,29 @@
     "url": "https://github.com/probita-ai/adtl/issues"
   },
   "dependencies": {
-    "@adtl/interceptors": "0.6.0",
-    "@adtl/labels": "0.6.0",
-    "@adtl/ledger": "0.6.0",
+    "@adtl/interceptors": "0.8.0",
+    "@adtl/labels": "0.8.0",
+    "@adtl/ledger": "0.8.0",
     "@modelcontextprotocol/sdk": "1.31.0",
     "nodemailer": "10.0.12",
     "yaml": "2.9.1",
     "zod": "3.25.76"
   },
+  "peerDependencies": {
+    "@cedar-policy/cedar-wasm": "^4.13.0"
+  },
+  "peerDependenciesMeta": {
+    "@cedar-policy/cedar-wasm": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22.13"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@cedar-policy/cedar-wasm": "4.13.0"
   }
 }

package/src/audit.ts

@@ -33,7 +33,7 @@ export interface AuditEntry {
   outcome: "forwarded" | "blocked" | "asked" | "upstream_error";
   /** Present when the entry was written by the Claude Code hook rather than the gateway. */
   via?: "claude-code-hook";
-  /** Present when a Claude Code subagent made the call: its id and type (e.g. "Explore"). */
+  /** Present when a sub-agent made the call: its id and type (e.g. "Explore"), from Claude Code or `ADTL_AGENT_ID`. */
   agent?: { id: string; type?: string };
   /** The policy's decision. In audit mode a call can be forwarded with decision "ask" or "block". */
   decision?: string;
@@ -51,6 +51,8 @@ export interface AuditEntry {
   ledger?: unknown;
   /** Present when the result carried record label stamps: how many, and which sessions wrote them. */
   records?: unknown;
+  /** Present when the ledger knew record ids in the result (tool rule `recordIds`): how many, and which sessions wrote them. */
+  recordIds?: unknown;
   sessionLabel?: unknown;
   /** Every interceptor invocation for this call, with its resolved mode and failOpen and where each came from (SEP-2624). */
   interceptors?: InterceptorRun[];

package/src/cedar.ts

@@ -0,0 +1,140 @@
+/**
+ * Attribute-based authorization with Cedar (`gateway.cedar`):
+ *
+ *   cedar:
+ *     policies: ./adtl.cedar         # Cedar policies, relative to adtl.yaml
+ *     entities: ./entities.json      # optional: Cedar entities (groups, attributes)
+ *     timeZone: Europe/Berlin        # optional: for context.time (default: the gateway's)
+ *
+ * Every call becomes a Cedar request:
+ *
+ *   principal  User::"alice", Service::"ci", or Anonymous::"anonymous" without an id
+ *   action     Action::"tools/call", Action::"resources/read" or Action::"prompts/get"
+ *   resource   Tool::"github.add_issue_comment", Prompt::"github.triage" or Resource::"<uri>"
+ *   context    { server, principalId, listing, time: { hour, minute, weekday }, arguments }
+ *
+ * Cedar denies unless a policy permits, and a `forbid` wins over any permit.
+ * Tool lists are filtered with `listing: true` and no `arguments`, so a policy
+ * on arguments should start with `context.listing ||`.
+ *
+ * Needs the optional dependency @cedar-policy/cedar-wasm, loaded only when
+ * `gateway.cedar` is set.
+ */
+import { readFileSync } from "node:fs";
+import type { AuthorizationDecision, AuthorizationRequest, Authorizer } from "./authorizer.js";
+import type { CedarConfig } from "./config.js";
+
+type CedarValue = boolean | number | string | CedarValue[] | { [key: string]: CedarValue };
+
+/** The parts of @cedar-policy/cedar-wasm used here. */
+interface CedarWasm {
+  isAuthorized(call: unknown): CedarAnswer;
+  checkParsePolicySet(policies: unknown): { type: "success" } | { type: "failure"; errors: { message: string }[] };
+  checkParseEntities(call: unknown): { type: "success" } | { type: "failure"; errors: { message: string }[] };
+}
+type CedarAnswer =
+  | { type: "failure"; errors: { message: string }[] }
+  | { type: "success"; response: { decision: "allow" | "deny"; diagnostics: { reason: string[]; errors: { policyId: string; error: { message: string } }[] } } };
+
+export class CedarAuthorizer implements Authorizer {
+  readonly name = "cedar";
+
+  private constructor(
+    private readonly cedar: CedarWasm,
+    private readonly policies: string,
+    private readonly entities: unknown[],
+    private readonly timeZone: string | undefined,
+  ) {}
+
+  /** Load the Cedar engine and the policy files. Throws on a missing package or files that don't parse. */
+  static async load(cfg: CedarConfig, resolvePath: (p: string) => string): Promise<CedarAuthorizer> {
+    let cedar: CedarWasm;
+    try {
+      cedar = (await import("@cedar-policy/cedar-wasm/nodejs")) as unknown as CedarWasm;
+    } catch {
+      throw new Error("gateway.cedar needs the Cedar engine: npm install @cedar-policy/cedar-wasm");
+    }
+    const policies = readFileSync(resolvePath(cfg.policies), "utf8");
+    const parsed = cedar.checkParsePolicySet({ staticPolicies: policies });
+    if (parsed.type === "failure") throw new Error(`gateway.cedar.policies: ${parsed.errors.map((e) => e.message).join("; ")}`);
+
+    let entities: unknown[] = [];
+    if (cfg.entities) {
+      const json: unknown = JSON.parse(readFileSync(resolvePath(cfg.entities), "utf8"));
+      if (!Array.isArray(json)) throw new Error("gateway.cedar.entities: expected a JSON array of Cedar entities");
+      const ok = cedar.checkParseEntities({ entities: json });
+      if (ok.type === "failure") throw new Error(`gateway.cedar.entities: ${ok.errors.map((e) => e.message).join("; ")}`);
+      entities = json;
+    }
+    return new CedarAuthorizer(cedar, policies, entities, cfg.timeZone);
+  }
+
+  check(req: AuthorizationRequest): AuthorizationDecision {
+    const { principal } = req;
+    const [type, id] =
+      req.event === "tools/call"
+        ? (["Tool", `${req.server}.${req.tool}`] as const)
+        : req.event === "prompts/get"
+          ? (["Prompt", `${req.server}.${req.prompt}`] as const)
+          : (["Resource", req.resource ?? ""] as const);
+    const context: Record<string, CedarValue> = {
+      server: req.server,
+      listing: req.arguments === undefined,
+      time: clock(new Date(), this.timeZone),
+      ...(principal.id !== undefined ? { principalId: principal.id } : {}),
+      ...(req.arguments !== undefined ? { arguments: toCedar(req.arguments) ?? {} } : {}),
+    };
+    const answer = this.cedar.isAuthorized({
+      principal:
+        principal.id === undefined
+          ? { type: "Anonymous", id: "anonymous" }
+          : { type: principal.type === "service" ? "Service" : "User", id: principal.id },
+      action: { type: "Action", id: req.event },
+      resource: { type, id },
+      context,
+      policies: { staticPolicies: this.policies },
+      entities: this.entities,
+    });
+    if (answer.type === "failure") throw new Error(answer.errors.map((e) => e.message).join("; "));
+    const { decision, diagnostics } = answer.response;
+    if (decision === "allow") return { allow: true };
+    const who = principal.id ?? "an anonymous caller";
+    const what = `the ${type.toLowerCase()} ${id}`;
+    return {
+      allow: false,
+      reason: diagnostics.reason.length
+        ? `Cedar policy ${diagnostics.reason.join(", ")} forbids ${who} to use ${what}`
+        : `No Cedar policy permits ${who} to use ${what}`,
+    };
+  }
+}
+
+/** Hour, minute and weekday ("Mon") in `timeZone`, for working-hours rules. */
+export function clock(now: Date, timeZone: string | undefined): Record<string, CedarValue> {
+  const parts = new Intl.DateTimeFormat("en-US", { timeZone, hourCycle: "h23", hour: "numeric", minute: "numeric", weekday: "short" }).formatToParts(now);
+  const part = (t: string) => parts.find((p) => p.type === t)?.value ?? "";
+  return { hour: Number(part("hour")), minute: Number(part("minute")), weekday: part("weekday") };
+}
+
+/**
+ * Tool arguments as Cedar context values. Cedar has no null or fractions, so
+ * nulls are left out and fractions become strings. An object with `__entity`
+ * or `__extn` would be read as an entity or extension value, so the agent
+ * could name any entity; it is passed as a JSON string instead.
+ */
+export function toCedar(v: unknown): CedarValue | undefined {
+  if (v === null || v === undefined) return undefined;
+  if (typeof v === "boolean" || typeof v === "string") return v;
+  if (typeof v === "number") return Number.isSafeInteger(v) ? v : String(v);
+  if (Array.isArray(v)) return v.map(toCedar).filter((x): x is CedarValue => x !== undefined);
+  if (typeof v === "object") {
+    if ("__entity" in v || "__extn" in v) return JSON.stringify(v);
+    const out: Record<string, CedarValue> = {};
+    for (const [k, x] of Object.entries(v)) {
+      const c = toCedar(x);
+      if (c !== undefined) out[k] = c;
+    }
+    return out;
+  }
+  return String(v);
+}

package/src/config.ts

@@ -12,10 +12,15 @@
  *       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)
  *     approvals:                         # optional: make "ask" really ask
  *       timeoutSeconds: 50
  *       ntfy: { topic: "${ADTL_NTFY_TOPIC}" }
@@ -138,6 +143,47 @@ export const RoleSchema = z
   });
 export type RoleConfig = z.infer<typeof RoleSchema>;
 
+export const CedarConfigSchema = z
+  .object({
+    /** Cedar policy file. Relative paths are resolved against the config file's directory. */
+    policies: z.string().min(1),
+    /** Optional Cedar entities JSON file: groups (`parents`) and attributes. */
+    entities: z.string().min(1).optional(),
+    /** IANA time zone for `context.time`, e.g. "Europe/Berlin". Default: the gateway's. */
+    timeZone: z
+      .string()
+      .min(1)
+      .refine((tz) => {
+        try {
+          new Intl.DateTimeFormat("en-US", { timeZone: tz });
+          return true;
+        } catch {
+          return false;
+        }
+      }, "Unknown time zone")
+      .optional(),
+  })
+  .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
@@ -148,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(),
     /**
@@ -159,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. */
@@ -166,6 +221,8 @@ export const GatewayConfigSchema = z
       .record(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(),
   })
   .strict();
 export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;

package/src/gateway.ts

@@ -21,9 +21,9 @@
  * unanswered or undeliverable calls are stopped. Without an approval channel,
  * "ask" blocks.
  *
- * An optional Authorizer decides first whether the caller may use the tool,
- * resource or prompt at all; a denial stops the call before the policy runs.
- * The lists the agent sees leave out what the authorizer would deny, so the
+ * Optional Authorizers decide first whether the caller may use the tool,
+ * resource or prompt at all; any denial stops the call before the policy runs.
+ * The lists the agent sees leave out what an authorizer would deny, so the
  * agent doesn't try it; hiding is a convenience, and every call is still checked.
  *
  * In audit mode (the invoker runs every interceptor with `mode: "audit"`)
@@ -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.6.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";
@@ -107,14 +107,16 @@ export interface AdtlGatewayOptions {
   logger?: GatewayLogger;
   /** Asks humans about "ask" decisions and sends notices. */
   approvals?: ApprovalBroker;
-  /** Decides whether the caller may use a tool, resource or prompt at all, before the policy. */
-  authorizer?: Authorizer;
+  /** Decides whether the caller may use a tool, resource or prompt at all, before the policy. Several must all allow. */
+  authorizer?: Authorizer | Authorizer[];
   /** The caller, passed to the authorizer and the interceptors. Default: anonymous. */
   principal?: Principal;
   /** Members of each role that policy rules name as `approvers:`. */
   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 };
 }
 
 /**
@@ -172,8 +174,9 @@ export class AdtlGateway {
   private readonly audit: AuditSink | undefined;
   private readonly log: GatewayLogger;
   private readonly approvals: ApprovalBroker | undefined;
-  private readonly authorizer: Authorizer | 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. */
@@ -191,15 +194,20 @@ export class AdtlGateway {
     this.audit = opts.audit;
     this.log = opts.logger ?? stderrLogger;
     this.approvals = opts.approvals;
-    this.authorizer = opts.authorizer;
+    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;
   }
 
-  /** Ask the authorizer, if any. Returns the denial; in audit mode the caller logs it and carries on. */
+  /** Ask each authorizer in turn. Returns the first denial; in audit mode the caller logs it and carries on. */
   private async authorize(request: Omit<AuthorizationRequest, "principal">): Promise<Denial | undefined> {
-    return this.authorizer ? authorize(this.authorizer, { principal: this.principal, ...request }) : undefined;
+    for (const a of this.authorizers) {
+      const denied = await authorize(a, { principal: this.principal, ...request });
+      if (denied) return denied;
+    }
+    return undefined;
   }
 
   /** The downstream MCP server the agent connects to. */
@@ -299,7 +307,7 @@ export class AdtlGateway {
    * call: routes are kept, and a call to a hidden item is still authorized.
    */
   private async hideDenied<T>(items: T[], request: (item: T) => Omit<AuthorizationRequest, "principal"> | undefined): Promise<T[]> {
-    if (!this.authorizer || this.invoker.modeOverride === "audit") return items;
+    if (!this.authorizers.length || this.invoker.modeOverride === "audit") return items;
     const shown = await Promise.all(
       items.map(async (item) => {
         const r = request(item);
@@ -446,6 +454,7 @@ export class AdtlGateway {
       this.audit?.write({
         ts: context.timestamp!,
         sessionId: this.sessionId,
+        ...this.agent,
         event,
         server: upstream,
         ...target,
@@ -497,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;
   }
 
@@ -521,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">) =>
@@ -626,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 });
@@ -659,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/index.ts

@@ -12,6 +12,7 @@ export * from "./hooks/index.js";
 export * from "./ledgerCli.js";
 export * from "./auditCli.js";
 export * from "./roles.js";
+export * from "./cedar.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";