AGENTS.md@gateway/src/risk git:20260818.7026d0eA

Immutable. This exact content is served forever at /api/v1/blob/1fa3c0009fb80d92.

# Risk: Agent Instructions

The gateway is the **only** place a tool invocation's risk is classified and the only place trust rules are stored, matched, and applied. `gateway/src/ipc/risk-classification-handlers.ts` (`classify_risk`) is the sole entry point; the assistant calls it exactly once per tool invocation and never classifies locally. See `command-registry/AGENTS.md` for the registry rules.

- **Trust rules live here** (`gateway/src/db/trust-rule-store.ts`, cached by `trust-rule-cache.ts`, seeded at startup by `db/seed-trust-rules.ts` and otherwise mutated only through the gateway HTTP routes, which refresh the cache in-process). A rule reaches the assistant only as the classified level plus `matchType: "user_rule"`; the assistant never sees, stores, or matches rules.
- **A tool's risk is decided here or not at all.** Tools without a dedicated classifier fall through to the `registryDefaultRisk` the assistant sends (the tool's `defaultRiskLevel`); today that fallback consults no trust rule and emits no allowlist options, so a user rule cannot cover such a tool. Fix that here when it matters, not with a classifier in the assistant.
- **What you return to the assistant is the whole answer.** Level, reason, `matchType`, allowlist / scope / directory-scope options, command candidates, sandbox flags, and the lexically-resolved path args. The assistant builds no ladder of its own, so a classifier that returns none leaves the user with no rule to save; web URLs go through `@vellumai/service-contracts/url-normalization` so a saved rule's pattern has one spelling (rule lookup itself is still raw exact-match; LUM-3337). The assistant's only adjustment is the bash sandbox symlink-escape re-check, which needs its filesystem and only ever revokes `sandboxAutoApprove`.
- **The wire shape is a shared contract**: `ClassifyRiskIpcParamsSchema` / `ClassifyRiskIpcResponseSchema` in `packages/gateway-client/src/gateway-ipc-contracts.ts`. The handler validates the request against it, the assistant validates the response against it, and both derive their types from it; do not redeclare either shape here.
- The assistant's counterpart doc is `assistant/src/permissions/AGENTS.md`; the architecture doc is `assistant/docs/architecture/security.md`.