Fix: Final PR review feedback + rebase onto main

AGENTS.md

@@ -45,6 +45,10 @@ Comments should explain **why** something is done and provide non-obvious contex
 
 Whenever you introduce, remove, or significantly modify a service, module, or data flow, you MUST update `ARCHITECTURE.md` to reflect the change. The Mermaid diagrams should always accurately represent the current system architecture, including new services, IPC message types, storage locations, and data flows.
 
+## Keep AGENTS.md up to date
+
+When your PR establishes a new mandatory pattern, convention, or architectural constraint that other agents must follow, update `AGENTS.md` in the same PR. Examples: introducing a new abstraction layer that all callsites must use, adding a guard test that enforces an import rule, or changing how a subsystem handles failure modes. If the pattern is only relevant within a single file or module, a code comment is sufficient — only add to `AGENTS.md` when the rule applies project-wide.
+
 ## Slash Commands — TLDR
 
 These are the most commonly used slash commands defined in `.claude/commands/`:
@@ -135,6 +139,36 @@ Concretely:
 
 Why: the gateway is the single point of ingress, handling TLS termination, auth, rate limiting, and routing. Exposing the daemon directly bypasses these protections and breaks the deployment model.
 
+## LLM Provider Abstraction
+
+All LLM calls in production code **MUST** go through the provider abstraction layer — never import `@anthropic-ai/sdk` (or any other provider SDK) directly.
+
+- Use `getConfiguredProvider()` from `providers/provider-send-message.ts` to obtain a provider instance, then call `provider.sendMessage(...)`.
+- Use the helper utilities (`extractText`, `extractToolUse`, `userMessage`, `createTimeout`, etc.) from the same module.
+- A guard test (`no-direct-anthropic-sdk-imports.test.ts`) enforces this — any new direct SDK import in production code will fail CI.
+- The only file allowed to import `@anthropic-ai/sdk` directly is `providers/anthropic/client.ts`.
+
+### Model intents over hardcoded model IDs
+
+Do not hardcode provider-specific model names (e.g., `claude-haiku-4-5-20251001`, `gpt-4o-mini`). Instead, use `modelIntent` in the config to express **what you need** from the model:
+
+- `'latency-optimized'` — fastest response (e.g., classifiers, triage, icon generation)
+- `'quality-optimized'` — best reasoning (e.g., summaries, complex analysis)
+- `'vision-optimized'` — best vision/multimodal capabilities
+
+The `RetryProvider` resolves intents to provider-specific models automatically. An explicit `model` in config takes precedence over `modelIntent`.
+
+### Provider-agnostic language
+
+Use generic terms in comments, logs, and variable names — write "LLM" instead of "Haiku"/"Sonnet"/"Claude". The system is multi-provider; naming should reflect that.
+
+## Approval Flow Resilience
+
+- **Rich delivery failures must degrade gracefully.** If delivering a rich approval prompt (e.g., Telegram inline buttons) fails, fall back to plain text with parser-compatible instructions (e.g., `Reply "yes" to approve`) — never auto-deny.
+- **Non-rich channels** (SMS, http-api) receive plain-text approval prompts without approval metadata payloads.
+- **Race conditions:** Always check whether a decision has already been resolved before delivering the engine's optimistic reply. If `handleChannelDecision` returns `applied: false`, deliver an "already resolved" notice and return `stale_ignored`.
+- **Requester self-cancel:** A requester with a pending guardian approval must be able to cancel their own request (but not self-approve).
+
 ## Tooling Direction
 
 Do not add new tool registrations using the `class ____Tool implements Tool {` pattern.

assistant/README.md

@@ -292,13 +292,13 @@ The assistant inbox provides secure cross-user messaging, allowing external user
 
 ### Ingress Membership
 
-External users join through **invite tokens** — the owner creates an invite via the desktop UI or IPC, and the external user redeems the token by sending it as a channel message. Redemption auto-creates a **member** record with a configurable access policy:
+External users join through **invite tokens** — the owner creates an invite via the desktop UI or IPC, and the external user redeems the token by sending it as a channel message. Redemption auto-creates a **member** record with an access policy:
 
 - **`allow`** — Messages are processed normally through the agent pipeline.
 - **`deny`** — Messages are rejected with a refusal notice.
 - **`escalate`** — Messages are held for guardian (owner) approval before processing.
 
-The default policy for new members is controlled by the `inbox_default_policy` config. Members can be listed, updated, revoked, or blocked via the `ingress_member` IPC contract.
+Non-members (senders with no invite redemption) are denied by default. Members can be listed, updated, revoked, or blocked via the `ingress_member` IPC contract.
 
 ### Escalation Flow (Dual-Surface)
 

assistant/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

assistant/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -2614,6 +2614,7 @@ exports[`IPC message snapshots ServerMessage types guardian_request_thread_creat
 {
   "callSessionId": "call-001",
   "conversationId": "conv-guardian-001",
+  "questionText": "What is the gate code?",
   "requestId": "req-guardian-001",
   "title": "Guardian action request",
   "type": "guardian_request_thread_created",