@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/url-normalization.ts

@@ -0,0 +1,107 @@
+/**
+ * Canonical URL normalization for web tool inputs, shared by the gateway's
+ * risk classifiers and the daemon's URL safety checks.
+ *
+ * A URL a model passes to `web_fetch` / `network_request` reaches more than
+ * one consumer, and they must agree on what counts as the same target: the
+ * gateway builds the trust-rule ladder from it, and anything that later
+ * compares a URL to a saved rule has to fold the same spellings together. Two
+ * normalizations would mean two answers, so it lives here rather than in
+ * either process.
+ *
+ * Data-only in spirit: no imports, no config, no I/O.
+ */
+
+/** Whether a bare `host:port` (or `[v6]:port`) shorthand was written. */
+export function looksLikeHostPortShorthand(value: string): boolean {
+  if (/^\[[0-9a-fA-F:.%]+\]:\d+(?:[/?#]|$)/.test(value)) {
+    return true;
+  }
+  return /^[^/?#@\s:]+:\d+(?:[/?#]|$)/.test(value);
+}
+
+/** Whether the input is a path, query, or fragment rather than a URL. */
+export function looksLikePathOnlyInput(value: string): boolean {
+  return (
+    value.startsWith("/") ||
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    value.startsWith("?") ||
+    value.startsWith("#")
+  );
+}
+
+/**
+ * Strip the parts of a URL that must not affect a trust decision, and fold
+ * the encodings that would otherwise let one URL wear two spellings.
+ *
+ * Percent-escaped path segments are decoded (`/%70rivate` and `/private` are
+ * one path, so a path-scoped rule cannot be bypassed by escaping), a trailing
+ * root dot is dropped from the hostname, and fragment and userinfo are
+ * removed: the fragment never reaches the server, and credentials in the
+ * authority must never end up in a saved rule.
+ */
+export function canonicalizeWebUrl(parsed: URL): URL {
+  parsed.hash = "";
+  parsed.username = "";
+  parsed.password = "";
+
+  try {
+    parsed.pathname = decodeURI(parsed.pathname);
+  } catch {
+    // Keep the URL parser's canonical form when decoding fails.
+  }
+
+  if (parsed.hostname.endsWith(".")) {
+    parsed.hostname = parsed.hostname.replace(/\.+$/, "");
+  }
+
+  return parsed;
+}
+
+/**
+ * Parse and canonicalize a web tool's `url` input, or `null` when it is not a
+ * URL this system will fetch.
+ *
+ * Accepts `https://host/path`, `http://…`, bare `host/path`, and `host:port`
+ * shorthand. Rejects path-only input and any other scheme (`file:`, `data:`,
+ * `javascript:`), so a non-http target can never acquire a web trust rule.
+ */
+export function normalizeWebUrl(rawUrl: string): URL | null {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  if (looksLikeHostPortShorthand(trimmed)) {
+    try {
+      return canonicalizeWebUrl(new URL(`https://${trimmed}`));
+    } catch {
+      return null;
+    }
+  }
+
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      return canonicalizeWebUrl(parsed);
+    }
+    return null;
+  } catch {
+    // Not an absolute URL; fall through to the shorthand forms.
+  }
+
+  if (looksLikePathOnlyInput(trimmed)) {
+    return null;
+  }
+
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) {
+    return null;
+  }
+
+  try {
+    return canonicalizeWebUrl(new URL(`https://${trimmed}`));
+  } catch {
+    return null;
+  }
+}

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/package.json

@@ -14,6 +14,7 @@
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
     "./twilio-ingress": "./src/twilio-ingress.ts",
     "./trust-rules": "./src/trust-rules.ts",
+    "./url-normalization": "./src/url-normalization.ts",
     "./handles": "./src/handles.ts",
     "./rpc": "./src/rpc.ts",
     "./attachment-naming": "./src/attachment-naming.ts",

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/__tests__/url-normalization.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  canonicalizeWebUrl,
+  looksLikeHostPortShorthand,
+  looksLikePathOnlyInput,
+  normalizeWebUrl,
+} from "../url-normalization.js";
+
+/**
+ * These are the rules a trust rule is saved and matched under. A change here
+ * changes which saved rules still match, so each case states the target the
+ * two spellings must agree on.
+ */
+describe("normalizeWebUrl", () => {
+  test("keeps an ordinary https URL as-is", () => {
+    expect(normalizeWebUrl("https://example.com/docs/page")?.href).toBe(
+      "https://example.com/docs/page",
+    );
+  });
+
+  test("drops the fragment: it never reaches the server", () => {
+    expect(normalizeWebUrl("https://example.com/docs#section")?.href).toBe(
+      "https://example.com/docs",
+    );
+  });
+
+  test("drops userinfo so credentials cannot land in a saved rule", () => {
+    const credentialed = new URL("https://example.com/docs/page");
+    credentialed.username = "demo";
+    credentialed.password = ["c", "r", "e", "d", "1", "2", "3"].join("");
+
+    const normalized = normalizeWebUrl(credentialed.href);
+    expect(normalized?.href).toBe("https://example.com/docs/page");
+    expect(normalized?.username).toBe("");
+    expect(normalized?.password).toBe("");
+  });
+
+  test("strips a trailing root dot from the hostname", () => {
+    expect(normalizeWebUrl("https://example.com./docs/page")?.href).toBe(
+      "https://example.com/docs/page",
+    );
+  });
+
+  test("decodes escaped path segments so one path has one spelling", () => {
+    // Without this, a rule scoped to /private is bypassed by /%70rivate.
+    expect(normalizeWebUrl("https://example.com/%70rivate")?.href).toBe(
+      "https://example.com/private",
+    );
+  });
+
+  test("reads scheme-less input as https", () => {
+    expect(normalizeWebUrl("example.com/docs")?.href).toBe(
+      "https://example.com/docs",
+    );
+  });
+
+  test("reads host:port shorthand as an https origin, not a scheme", () => {
+    expect(normalizeWebUrl("example.com:8443/status")?.origin).toBe(
+      "https://example.com:8443",
+    );
+    expect(normalizeWebUrl("[2001:db8::1]:8443/status")?.origin).toBe(
+      "https://[2001:db8::1]:8443",
+    );
+  });
+
+  test("rejects path-only input rather than coercing it to a host", () => {
+    for (const input of ["/etc/passwd", "./rel", "../up", "?q=1", "#frag"]) {
+      expect(normalizeWebUrl(input)).toBeNull();
+    }
+  });
+
+  test("rejects every non-http scheme", () => {
+    for (const input of [
+      "file:///etc/passwd",
+      "data:text/html,<script>",
+      "javascript:alert(1)",
+      "ftp://example.com/f",
+    ]) {
+      expect(normalizeWebUrl(input)).toBeNull();
+    }
+  });
+
+  test("rejects empty and whitespace-only input", () => {
+    expect(normalizeWebUrl("")).toBeNull();
+    expect(normalizeWebUrl("   ")).toBeNull();
+  });
+
+  test("trims surrounding whitespace", () => {
+    expect(normalizeWebUrl("  https://example.com/a  ")?.href).toBe(
+      "https://example.com/a",
+    );
+  });
+
+  test("returns null rather than throwing on an unparseable authority", () => {
+    expect(normalizeWebUrl("https://")).toBeNull();
+  });
+});
+
+describe("canonicalizeWebUrl", () => {
+  test("keeps the parser's form when the path is not decodable, without throwing", () => {
+    // `%zz` and a truncated UTF-8 sequence are not valid escapes; the path
+    // must survive unchanged rather than the call throwing.
+    expect(canonicalizeWebUrl(new URL("https://example.com/100%zz")).href).toBe(
+      "https://example.com/100%zz",
+    );
+    expect(
+      canonicalizeWebUrl(new URL("https://example.com/%E0%A4%A")).href,
+    ).toBe("https://example.com/%E0%A4%A");
+  });
+
+  test("decodes an escaped percent, so `%25` and `%` are one path", () => {
+    expect(canonicalizeWebUrl(new URL("https://example.com/100%25")).href).toBe(
+      "https://example.com/100%",
+    );
+  });
+});
+
+describe("input shape predicates", () => {
+  test("host:port shorthand is recognized, scheme-prefixed input is not", () => {
+    expect(looksLikeHostPortShorthand("example.com:8443/x")).toBe(true);
+    expect(looksLikeHostPortShorthand("[2001:db8::1]:443")).toBe(true);
+    expect(looksLikeHostPortShorthand("https://example.com/x")).toBe(false);
+    expect(looksLikeHostPortShorthand("example.com/x")).toBe(false);
+  });
+
+  test("path-only input is recognized", () => {
+    expect(looksLikePathOnlyInput("/abs")).toBe(true);
+    expect(looksLikePathOnlyInput("./rel")).toBe(true);
+    expect(looksLikePathOnlyInput("../up")).toBe(true);
+    expect(looksLikePathOnlyInput("?q=1")).toBe(true);
+    expect(looksLikePathOnlyInput("#frag")).toBe(true);
+    expect(looksLikePathOnlyInput("example.com/x")).toBe(false);
+  });
+});

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -6,6 +6,16 @@
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
  * internal ids (`vellum` for native app conversations, `platform` for the
  * internal control plane). This is the single source of truth for that set:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
  * the assistant adopts it wholesale as its `ChannelId`, and the gateway
  * asserts its own (narrower) inbound list is a subset of it so the two sides
  * cannot silently drift.
@@ -30,6 +40,7 @@ export const CHANNEL_IDS = [
   "platform",
   "a2a",
   "discord",
+  "plugin",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/index.ts

@@ -29,3 +29,4 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";
+export * from "./url-normalization.js";

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -11,6 +11,12 @@
  *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
  *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
  *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *   - `GET  /v1/remote-web/pairing-requests`          list pending challenges
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/approve`  approve by request id
+ *       (loopback-only)
+ *   - `POST /v1/remote-web/pairing-requests/deny`     deny (delete) by request id
+ *       (loopback-only)
  *
  * These shapes mirror those handlers' request/response bodies exactly so the
  * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
@@ -68,6 +74,60 @@ export interface RemoteWebPairingVerificationResponse {
   expiresAt: string;
 }
 
+/**
+ * One pending challenge as shown on a host approval surface.
+ *
+ * The requesting device already sees the plaintext `userCode` in its own
+ * challenge response ({@link RemoteWebPairingChallengeResponse.userCode});
+ * the loopback-gated list route is the only host-side re-exposure. Displaying
+ * it there is what lets the approver match the code against the requesting
+ * device's screen: the device-flow anti-phishing binding.
+ */
+export interface RemoteWebPairingRequestSummary {
+  /** Opaque server-side id used to approve or deny this request. */
+  requestId: string;
+  /** The human-readable code the requesting device is displaying (e.g. "ABCD-EFGH"). */
+  userCode: string;
+  /** Public base URL the challenge was minted for. */
+  publicBaseUrl: string;
+  /** ISO-8601 instant the challenge was minted. */
+  requestedAt: string;
+  /** ISO-8601 instant the challenge expires. */
+  expiresAt: string;
+  /**
+   * Client IP of the mint request: the loopback/host address when minted
+   * locally, or the edge-observed client address when the mint arrived
+   * through the nginx tunnel edge (which stamps it via `proxy_set_header`,
+   * so a remote client cannot smuggle a value).
+   */
+  requesterIp: string;
+  /** User-Agent header of the mint request, or null when absent. */
+  requesterUserAgent: string | null;
+  /**
+   * Whether the mint arrived through the public tunnel edge rather than the
+   * host itself.
+   */
+  viaEdgeProxy: boolean;
+}
+
+/** `GET /v1/remote-web/pairing-requests` success response body (200). */
+export interface RemoteWebPairingRequestListResponse {
+  requests: RemoteWebPairingRequestSummary[];
+}
+
+/**
+ * Request body for the pairing-request approve and deny routes. The approve
+ * route's success body reuses {@link RemoteWebPairingVerificationResponse}.
+ */
+export interface RemoteWebPairingRequestActionRequest {
+  requestId: string;
+}
+
+/** `POST /v1/remote-web/pairing-requests/deny` success response body (200). */
+export interface RemoteWebPairingRequestDenyResponse {
+  status: "denied";
+}
+
 /** `POST /v1/remote-web/pairing-token` request body. */
 export interface RemoteWebPairingTokenRequest {
   /** The `deviceCode` from the challenge. */

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/url-normalization.ts

@@ -0,0 +1,107 @@
+/**
+ * Canonical URL normalization for web tool inputs, shared by the gateway's
+ * risk classifiers and the daemon's URL safety checks.
+ *
+ * A URL a model passes to `web_fetch` / `network_request` reaches more than
+ * one consumer, and they must agree on what counts as the same target: the
+ * gateway builds the trust-rule ladder from it, and anything that later
+ * compares a URL to a saved rule has to fold the same spellings together. Two
+ * normalizations would mean two answers, so it lives here rather than in
+ * either process.
+ *
+ * Data-only in spirit: no imports, no config, no I/O.
+ */
+
+/** Whether a bare `host:port` (or `[v6]:port`) shorthand was written. */
+export function looksLikeHostPortShorthand(value: string): boolean {
+  if (/^\[[0-9a-fA-F:.%]+\]:\d+(?:[/?#]|$)/.test(value)) {
+    return true;
+  }
+  return /^[^/?#@\s:]+:\d+(?:[/?#]|$)/.test(value);
+}
+
+/** Whether the input is a path, query, or fragment rather than a URL. */
+export function looksLikePathOnlyInput(value: string): boolean {
+  return (
+    value.startsWith("/") ||
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    value.startsWith("?") ||
+    value.startsWith("#")
+  );
+}
+
+/**
+ * Strip the parts of a URL that must not affect a trust decision, and fold
+ * the encodings that would otherwise let one URL wear two spellings.
+ *
+ * Percent-escaped path segments are decoded (`/%70rivate` and `/private` are
+ * one path, so a path-scoped rule cannot be bypassed by escaping), a trailing
+ * root dot is dropped from the hostname, and fragment and userinfo are
+ * removed: the fragment never reaches the server, and credentials in the
+ * authority must never end up in a saved rule.
+ */
+export function canonicalizeWebUrl(parsed: URL): URL {
+  parsed.hash = "";
+  parsed.username = "";
+  parsed.password = "";
+
+  try {
+    parsed.pathname = decodeURI(parsed.pathname);
+  } catch {
+    // Keep the URL parser's canonical form when decoding fails.
+  }
+
+  if (parsed.hostname.endsWith(".")) {
+    parsed.hostname = parsed.hostname.replace(/\.+$/, "");
+  }
+
+  return parsed;
+}
+
+/**
+ * Parse and canonicalize a web tool's `url` input, or `null` when it is not a
+ * URL this system will fetch.
+ *
+ * Accepts `https://host/path`, `http://…`, bare `host/path`, and `host:port`
+ * shorthand. Rejects path-only input and any other scheme (`file:`, `data:`,
+ * `javascript:`), so a non-http target can never acquire a web trust rule.
+ */
+export function normalizeWebUrl(rawUrl: string): URL | null {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  if (looksLikeHostPortShorthand(trimmed)) {
+    try {
+      return canonicalizeWebUrl(new URL(`https://${trimmed}`));
+    } catch {
+      return null;
+    }
+  }
+
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      return canonicalizeWebUrl(parsed);
+    }
+    return null;
+  } catch {
+    // Not an absolute URL; fall through to the shorthand forms.
+  }
+
+  if (looksLikePathOnlyInput(trimmed)) {
+    return null;
+  }
+
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) {
+    return null;
+  }
+
+  try {
+    return canonicalizeWebUrl(new URL(`https://${trimmed}`));
+  } catch {
+    return null;
+  }
+}

package/node_modules/@vellumai/gateway-client/src/admission-policy-contract.ts

@@ -10,6 +10,8 @@
 
 import { z } from "zod";
 
+import type { TrustClass } from "./trust-verdict-contract.js";
+
 /**
  * Per-channel inbound admission policy — ordered from most-restrictive
  * (`no_one`, hard kill switch) to most-permissive (`strangers`, admits any
@@ -101,3 +103,35 @@ export function isAdmissionPolicy(value: unknown): value is AdmissionPolicy {
     (ADMISSION_POLICY_VALUES as readonly string[]).includes(value)
   );
 }
+
+/**
+ * Trust-class ordinal compared against {@link ADMISSION_FLOOR} to make the
+ * admission decision. Higher rank = more trusted. Blocked and revoked members
+ * never reach this comparison, short-circuiting to deny on member status, so
+ * they carry no rank.
+ */
+export const TRUST_CLASS_RANK: Record<TrustClass, number> = {
+  guardian: 4,
+  trusted_contact: 3,
+  unverified_contact: 2,
+  unknown: 1,
+};
+
+/**
+ * Whether a sender of this trust class clears a channel's admission floor.
+ *
+ * The two halves of the check live together because they are meaningless
+ * apart: this compares a table keyed by {@link TrustClass} against one keyed
+ * by {@link AdmissionPolicy}, and a floor added to one without a rank in the
+ * other silently admits or denies everyone.
+ *
+ * Both enforcement points read this. The runtime's admission stage answers for
+ * every channel it receives; the gateway answers for a channel it delivers
+ * somewhere other than the runtime, where there is no later stage to ask.
+ */
+export function meetsAdmissionFloor(
+  policy: AdmissionPolicy,
+  trustClass: TrustClass,
+): boolean {
+  return TRUST_CLASS_RANK[trustClass] >= ADMISSION_FLOOR[policy];
+}

package/node_modules/@vellumai/gateway-client/src/gateway-ipc-contracts.ts

@@ -63,11 +63,16 @@ export type TrustRulesListIpcParams = z.infer<
   typeof TrustRulesListIpcParamsSchema
 >;
 
+/** The three risk levels a trust rule can set and a registry default can carry. */
+export const RISK_LEVEL_VALUES = ["low", "medium", "high"] as const;
+export type RiskLevelValue = (typeof RISK_LEVEL_VALUES)[number];
+export const RiskLevelValueSchema = z.enum(RISK_LEVEL_VALUES);
+
 export const TrustRuleSchema = z.object({
   id: z.string(),
   tool: z.string(),
   pattern: z.string(),
-  risk: z.enum(["low", "medium", "high"]),
+  risk: RiskLevelValueSchema,
   description: z.string(),
   origin: z.enum(["default", "user_defined"]),
   userModified: z.boolean(),
@@ -341,3 +346,163 @@ export const GetGuardianContactIpcResponseSchema = z.object({
 export type GetGuardianContactIpcResponse = z.infer<
   typeof GetGuardianContactIpcResponseSchema
 >;
+
+// ── classify_risk ────────────────────────────────────────────────────────────
+// Risk classification is gateway-owned; the assistant sends one request per
+// tool invocation and reads the whole answer back. The gateway validates the
+// request against `ClassifyRiskIpcParamsSchema`; the assistant validates the
+// response against `ClassifyRiskIpcResponseSchema` and fails closed on a
+// mismatch.
+
+/** A classified risk; `unknown` is the classifier's own "not in registry". */
+export const ClassifiedRiskSchema = z.enum([...RISK_LEVEL_VALUES, "unknown"]);
+export type ClassifiedRisk = z.infer<typeof ClassifiedRiskSchema>;
+
+/** How a risk was determined: a user trust rule, the registry, or neither. */
+export const RiskMatchTypeSchema = z.enum(["user_rule", "registry", "unknown"]);
+export type RiskMatchType = z.infer<typeof RiskMatchTypeSchema>;
+
+/**
+ * File classifier context the assistant pre-resolves (it owns the workspace
+ * filesystem) so the gateway can classify file tools without assistant path
+ * helpers. Directories are canonicalized (symlinks resolved) by the sender.
+ */
+export const ClassifyRiskFileContextSchema = z.object({
+  protectedDir: z.string(),
+  deprecatedDir: z.string(),
+  hooksDir: z.string(),
+  pluginsDir: z.string().optional(),
+  toolsDir: z.string().optional(),
+  routesDir: z.string().optional(),
+  workflowsDir: z.string().optional(),
+  /** Monitoring data dir: the sentinel lives here, writes are code-injection risk. */
+  monitoringDir: z.string().optional(),
+  actorTokenSigningKeyPath: z.string(),
+  skillSourceDirs: z.array(z.string()),
+});
+export type ClassifyRiskFileContext = z.infer<
+  typeof ClassifyRiskFileContextSchema
+>;
+
+/** Skill metadata the assistant pre-resolves for skill-load classification. */
+export const ClassifyRiskSkillMetadataSchema = z.object({
+  skillId: z.string(),
+  selector: z.string(),
+  versionHash: z.string(),
+  transitiveHash: z.string().optional(),
+  hasInlineExpansions: z.boolean(),
+  isDynamic: z.boolean(),
+});
+export type ClassifyRiskSkillMetadata = z.infer<
+  typeof ClassifyRiskSkillMetadataSchema
+>;
+
+export const ClassifyRiskIpcParamsSchema = z.object({
+  tool: z.string().min(1),
+  command: z.string().optional(),
+  url: z.string().optional(),
+  path: z.string().optional(),
+  /**
+   * The file tool's target path with symlinks resolved by the assistant. The
+   * gateway's security escalation prefix checks use it so a symlink cannot
+   * mask a write into a protected directory; falls back to lexical resolution
+   * of `path` when absent.
+   */
+  resolvedPath: z.string().optional(),
+  /**
+   * The sandbox file tool's working directory with symlinks resolved. Paired
+   * with `resolvedPath` for the workspace-boundary check so a symlinked
+   * workspace prefix (macOS `/var` → `/private/var`) does not read as an
+   * escape. Absent for host tools.
+   */
+  resolvedWorkingDir: z.string().optional(),
+  skill: z.string().optional(),
+  mode: z.string().optional(),
+  script: z.string().optional(),
+  workingDir: z.string().optional(),
+  allowPrivateNetwork: z.boolean().optional(),
+  networkMode: z.string().optional(),
+  isContainerized: z.boolean().optional(),
+  workspaceRoot: z.string().optional(),
+  fileContext: ClassifyRiskFileContextSchema.optional(),
+  skillMetadata: ClassifyRiskSkillMetadataSchema.optional(),
+  /**
+   * The tool's registry default risk, for tools with no dedicated classifier.
+   * The gateway answers with it (`matchType: "registry"`); absent, the tool is
+   * unknown and answers `medium`.
+   */
+  registryDefaultRisk: RiskLevelValueSchema.optional(),
+  /** Number of credential references attached to this tool invocation. */
+  credentialRefCount: z.number().int().nonnegative().optional(),
+  /**
+   * For `host_file_transfer` to_sandbox: the workspace-side destination path
+   * and the sandbox working directory it resolves against, so a transfer that
+   * lands an executable file in a code-injection sink (tools, routes, hooks,
+   * plugins, skills) escalates even though `path` carries the host-side source.
+   */
+  transferSandboxDestPath: z.string().optional(),
+  transferSandboxWorkingDir: z.string().optional(),
+  /** `transferSandboxDestPath` with symlinks resolved by the assistant. */
+  resolvedTransferDestPath: z.string().optional(),
+});
+export type ClassifyRiskIpcParams = z.infer<typeof ClassifyRiskIpcParamsSchema>;
+
+/** Regex ladder shown when the user saves a classification (display only). */
+export const RiskPatternScopeOptionSchema = z.object({
+  pattern: z.string(),
+  label: z.string(),
+});
+export type RiskPatternScopeOption = z.infer<
+  typeof RiskPatternScopeOptionSchema
+>;
+
+/** Minimatch ladder for the "always allow" prompt option (what a rule matches). */
+export const RiskAllowlistOptionSchema = z.object({
+  label: z.string(),
+  description: z.string(),
+  pattern: z.string(),
+});
+export type RiskAllowlistOption = z.infer<typeof RiskAllowlistOptionSchema>;
+
+/** Directory ladder for filesystem operations; `scope` is a path glob or `everywhere`. */
+export const RiskDirectoryScopeOptionSchema = z.object({
+  scope: z.string(),
+  label: z.string(),
+});
+export type RiskDirectoryScopeOption = z.infer<
+  typeof RiskDirectoryScopeOptionSchema
+>;
+
+export const RiskDangerousPatternSchema = z.object({
+  type: z.string(),
+  description: z.string(),
+  text: z.string(),
+});
+export type RiskDangerousPattern = z.infer<typeof RiskDangerousPatternSchema>;
+
+export const ClassifyRiskIpcResponseSchema = z.object({
+  risk: ClassifiedRiskSchema,
+  reason: z.string(),
+  matchType: RiskMatchTypeSchema,
+  scopeOptions: z.array(RiskPatternScopeOptionSchema),
+  allowlistOptions: z.array(RiskAllowlistOptionSchema).optional(),
+  actionKeys: z.array(z.string()).optional(),
+  commandCandidates: z.array(z.string()).optional(),
+  dangerousPatterns: z.array(RiskDangerousPatternSchema).optional(),
+  opaqueConstructs: z.boolean().optional(),
+  isComplexSyntax: z.boolean().optional(),
+  sandboxAutoApprove: z.boolean().optional(),
+  /**
+   * Lexically-resolved path arguments from sandbox-auto-approve-eligible bash
+   * segments. The gateway has no filesystem access; the assistant resolves
+   * these through symlinks and revokes `sandboxAutoApprove` if any escapes
+   * the workspace.
+   */
+  sandboxPathArgs: z.array(z.string()).optional(),
+  directoryScopeOptions: z.array(RiskDirectoryScopeOptionSchema).optional(),
+  /** Fully resolved filesystem path arguments, for directory-scoped rule matching. */
+  resolvedPaths: z.array(z.string()).optional(),
+});
+export type ClassifyRiskIpcResponse = z.infer<
+  typeof ClassifyRiskIpcResponseSchema
+>;