@vellumai/assistant 0.6.5 → 0.6.6

package/AGENTS.md

@@ -14,7 +14,15 @@ When you introduce a new env var that the assistant process needs to read at run
 
 ## Daemon startup philosophy
 
-The daemon must **never** block startup under *any circumstance*. All possible errors should be logged so that the assistant can recover from it's corrupted state after the fact.
+The daemon must **never** block startup under _any circumstance_. All possible errors should be logged so that the assistant can recover from it's corrupted state after the fact.
+
+## Post-execution hooks
+
+Tool post-execution hooks (`src/daemon/tool-side-effects.ts`) run after a tool executor returns. They are an **observation-and-notification layer** only: refresh client-side state, broadcast events, kick off orthogonal background work (e.g. icon generation). Hooks must not re-do work the executor already performed, and must not attempt recovery when the executor failed — failures surface in the tool result for the LLM to act on.
+
+Do not coordinate hook behaviour by re-parsing the tool's JSON response to infer what the executor did (e.g. "if field X is missing, retry step Y"). That couples the LLM-facing response shape to internal daemon logic and breaks silently when the response shape evolves. Keep the hook's logic independent of the result payload, or if the hook genuinely needs executor-internal state, pass it through a typed side channel — never through a JSON round-trip.
+
+Shared mutable resources written by more than one caller (e.g. `dist/` directories produced by `compileApp()`) must be serialised per-resource so concurrent callers cannot race on `rm -rf` + write sequences.
 
 ## Code comments
 

package/ARCHITECTURE.md

@@ -1045,13 +1045,11 @@ When all four reducer tiers are exhausted and the provider still rejects, the ov
 
 | Session Type    | Config Policy           | Action                                                                                                      |
 | --------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Interactive     | `"summarize"` (default) | `request_user_approval` — prompt the user via `PermissionPrompter` before compressing the latest turn       |
+| Interactive     | `"summarize"` (default) | `auto_compress_latest_turn` — compress without asking                                                       |
 | Non-interactive | `"truncate"` (default)  | `auto_compress_latest_turn` — compress without asking                                                       |
 | Any             | `"drop"`                | `fail_gracefully` — fall through to the final context-overflow fallback, which emits a `conversation_error` |
 
-**Approval gate:** For interactive sessions, the pipeline uses `requestCompressionApproval()` in `context-overflow-approval.ts`, which presents a confirmation prompt through the existing `PermissionPrompter` flow (`POST /v1/confirm`). The prompt uses a reserved pseudo tool name (`context_overflow_compression`) so the UI can display a meaningful label. The decision is one-shot per overflow (no "always allow" option).
-
-**Deny handling:** If the user declines compression, the session emits a graceful assistant explanation message ("The conversation has grown too long...") instead of a `conversation_error`. The deny message is persisted to conversation history and delivered via `assistant_text_delta` events, so the user sees a normal chat bubble rather than an error toast. The turn ends cleanly without triggering the error classification pipeline.
+When standard compaction has been exhausted and the provider still reports a context overflow, the recovery pipeline forces an emergency compaction of the latest turn with aggressive settings (`force: true`, `minKeepRecentUserTurns: 0`). The user is not prompted — compaction is always automatic. Users who want to opt out entirely can set `contextWindow.overflowRecovery.interactiveLatestTurnCompression` to `"drop"`, which short-circuits to a graceful failure instead.
 
 ### Config
 
@@ -1067,13 +1065,12 @@ All overflow recovery settings live under `contextWindow.overflowRecovery` in th
 
 ### Key Source Files
 
-| File                                      | Purpose                                                                          |
-| ----------------------------------------- | -------------------------------------------------------------------------------- |
-| `src/daemon/context-overflow-reducer.ts`  | Tiered reducer: four-tier pipeline with idempotent steps and cumulative state    |
-| `src/daemon/context-overflow-policy.ts`   | Overflow policy resolver: maps config + interactivity to concrete action         |
-| `src/daemon/context-overflow-approval.ts` | Approval gate: prompts user for latest-turn compression via `PermissionPrompter` |
-| `src/daemon/conversation-agent-loop.ts`   | Integration: preflight budget check, convergence loop, approval/deny flow        |
-| `src/config/core-schema.ts`               | `ContextOverflowRecoveryConfigSchema` with defaults and validation               |
+| File                                     | Purpose                                                                       |
+| ---------------------------------------- | ----------------------------------------------------------------------------- |
+| `src/daemon/context-overflow-reducer.ts` | Tiered reducer: four-tier pipeline with idempotent steps and cumulative state |
+| `src/daemon/context-overflow-policy.ts`  | Overflow policy resolver: maps config + interactivity to concrete action      |
+| `src/daemon/conversation-agent-loop.ts`  | Integration: preflight budget check, convergence loop, emergency compaction   |
+| `src/config/core-schema.ts`              | `ContextOverflowRecoveryConfigSchema` with defaults and validation            |
 
 ---
 
@@ -1562,13 +1559,14 @@ graph TB
 
     FIND_RULE -->|"Deny rule"| DENY["decision: deny<br/>Blocked by rule"]
     FIND_RULE -->|"Ask rule"| PROMPT_ASK["decision: prompt<br/>Always ask user"]
-    FIND_RULE -->|"Allow rule"| RISK_CHECK{"Risk level?"}
-    FIND_RULE -->|"No match"| NO_MATCH{"Fallback logic"}
+    FIND_RULE -->|"Allow rule / No match"| SANDBOX_CHECK{"sandboxAutoApprove?<br/>(bash + allowlisted +<br/>containerized)"}
+
+    SANDBOX_CHECK -->|"yes"| AUTO_SANDBOX["decision: allow<br/>Sandbox auto-approve"]
+    SANDBOX_CHECK -->|"no, has Allow rule"| RISK_CHECK{"Risk level?"}
+    SANDBOX_CHECK -->|"no, no match"| NO_MATCH{"Fallback logic"}
 
     RISK_CHECK -->|"Low / Medium"| AUTO_ALLOW["decision: allow<br/>Auto-allowed by rule"]
-    RISK_CHECK -->|"High"| HIGH_CHECK{"shouldAutoAllowHighRisk()<br/>(containerized bash?)"}
-    HIGH_CHECK -->|"yes"| AUTO_ALLOW
-    HIGH_CHECK -->|"no"| RISK_THRESHOLD{"Risk-based<br/>threshold fallback"}
+    RISK_CHECK -->|"High"| RISK_THRESHOLD{"Risk-based<br/>threshold fallback"}
 
     NO_MATCH -->|"tool.origin === 'skill'"| PROMPT_SKILL["decision: prompt<br/>Skill tools always ask"]
     NO_MATCH -->|"strict mode"| PROMPT_STRICT["decision: prompt<br/>No implicit auto-allow"]
@@ -1711,7 +1709,7 @@ When a permission prompt is sent to the client (via `confirmation_request` SSE e
 | `allowlistOptions` | Suggested patterns for "always allow" rules         |
 | `scopeOptions`     | Suggested scopes for rule persistence               |
 
-The user can respond with: `allow` (one-time), `always_allow` (create allow rule), `deny` (one-time), or `always_deny` (create deny rule). High-risk operations with an allow rule in containerized environments are auto-allowed at runtime by `DefaultApprovalPolicy.shouldAutoAllowHighRisk()` without requiring persisted state. All other risk-based decisions use the `autoApproveUpTo` threshold (default: `"low"`) -- tools at or below the threshold are auto-allowed, those above are prompted.
+The user can respond with: `allow` (one-time), `always_allow` (create allow rule), `deny` (one-time), or `always_deny` (create deny rule). In containerized environments, commands tagged with `sandboxAutoApprove` in their risk spec are auto-allowed via the approval policy's sandbox auto-approve check; non-allowlisted commands (network tools, runtimes, package managers) use the user's `autoApproveUpTo` threshold. All other risk-based decisions use the `autoApproveUpTo` threshold (default: `"low"`) -- tools at or below the threshold are auto-allowed, those above are prompted.
 
 ### Canonical Paths
 

package/Dockerfile

@@ -36,9 +36,6 @@ RUN set -eu; for pkg in /app/skills/*/package.json; do \
       (cd "$dir" && (bun install --frozen-lockfile 2>/dev/null || bun install)); \
     done
 
-# Copy source
-COPY assistant ./assistant
-
 # Final stage
 FROM debian:trixie-slim@sha256:4ffb3a1511099754cddc70eb1b12e50ffdb67619aa0ab6c13fcd800a78ef7c7a AS runner
 
@@ -133,8 +130,13 @@ EXPOSE 3001
 ENV RUNTIME_HTTP_PORT=3001
 ENV IS_CONTAINERIZED=true
 
-# Copy from builder
+# Copy installed deps + shared packages + bundled skills from builder.
+# Skills stay in the builder copy because they require per-skill `bun install` runs.
 COPY --from=builder /app /app
+
+# Copy source separately to avoid invalidating builder layer.
+COPY assistant ./
+
 RUN chmod +x /app/assistant/docker-entrypoint.sh
 
 # Run the daemon + http server

package/__tests__/permissions/gateway-threshold-reader.test.ts

@@ -0,0 +1,283 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+// ── Mocks ────────────────────────────────────────────────────────────────────
+
+let mockFeatureFlagEnabled = true;
+
+mock.module("../../src/config/assistant-feature-flags.js", () => ({
+  isAssistantFeatureFlagEnabled: (_key: string, _config: unknown) =>
+    mockFeatureFlagEnabled,
+}));
+
+mock.module("../../src/config/loader.js", () => ({
+  getConfig: () => ({}),
+}));
+
+// Track gatewayGet calls for assertion
+const gatewayGetCalls: string[] = [];
+let gatewayGetHandler: (path: string) => unknown = () => ({});
+
+mock.module("../../src/runtime/gateway-internal-client.js", () => ({
+  GatewayRequestError: class GatewayRequestError extends Error {
+    statusCode: number;
+    gatewayError: string | undefined;
+    constructor(message: string, statusCode: number, gatewayError?: string) {
+      super(message);
+      this.name = "GatewayRequestError";
+      this.statusCode = statusCode;
+      this.gatewayError = gatewayError;
+    }
+  },
+  gatewayGet: async <T>(path: string): Promise<T> => {
+    gatewayGetCalls.push(path);
+    return gatewayGetHandler(path) as T;
+  },
+}));
+
+// Suppress logger output in tests
+mock.module("../../src/util/logger.js", () => ({
+  getLogger: () => ({
+    warn: () => {},
+    info: () => {},
+    error: () => {},
+    debug: () => {},
+  }),
+}));
+
+import {
+  _clearGlobalCacheForTesting,
+  getAutoApproveThreshold,
+} from "../../src/permissions/gateway-threshold-reader.js";
+// Import GatewayRequestError from the mock so we can throw instances of it
+const { GatewayRequestError } =
+  await import("../../src/runtime/gateway-internal-client.js");
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function resetMocks(): void {
+  mockFeatureFlagEnabled = true;
+  gatewayGetCalls.length = 0;
+  gatewayGetHandler = () => ({});
+  _clearGlobalCacheForTesting();
+}
+
+afterEach(resetMocks);
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("getAutoApproveThreshold", () => {
+  test("returns undefined when feature flag is off", async () => {
+    mockFeatureFlagEnabled = false;
+    const result = await getAutoApproveThreshold("conv-123", "conversation");
+    expect(result).toBeUndefined();
+    // Should not make any gateway calls
+    expect(gatewayGetCalls).toHaveLength(0);
+  });
+
+  test("returns global defaults when gateway returns them", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "medium",
+          background: "low",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // conversation maps to interactive
+    expect(await getAutoApproveThreshold(undefined, "conversation")).toBe(
+      "medium",
+    );
+
+    _clearGlobalCacheForTesting();
+
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe("low");
+
+    _clearGlobalCacheForTesting();
+
+    expect(await getAutoApproveThreshold(undefined, "headless")).toBe("none");
+  });
+
+  test("returns conversation override when it exists", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds/conversations/conv-xyz") {
+        return { threshold: "medium" };
+      }
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    const result = await getAutoApproveThreshold("conv-xyz", "conversation");
+    expect(result).toBe("medium");
+    // Should have called the conversation endpoint, not the global one
+    expect(gatewayGetCalls).toEqual([
+      "/v1/permissions/thresholds/conversations/conv-xyz",
+    ]);
+  });
+
+  test("falls back to global when conversation override returns 404", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path.startsWith("/v1/permissions/thresholds/conversations/")) {
+        throw new GatewayRequestError("Not found", 404, "Not found");
+      }
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    const result = await getAutoApproveThreshold("conv-123", "conversation");
+    expect(result).toBe("low");
+    // Should have called both endpoints
+    expect(gatewayGetCalls).toEqual([
+      "/v1/permissions/thresholds/conversations/conv-123",
+      "/v1/permissions/thresholds",
+    ]);
+  });
+
+  test("falls back to hardcoded defaults on gateway error", async () => {
+    gatewayGetHandler = () => {
+      throw new Error("Connection refused");
+    };
+
+    // conversation → "low"
+    expect(await getAutoApproveThreshold(undefined, "conversation")).toBe(
+      "low",
+    );
+
+    _clearGlobalCacheForTesting();
+
+    // background → "medium"
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe(
+      "medium",
+    );
+
+    _clearGlobalCacheForTesting();
+
+    // headless → "none"
+    expect(await getAutoApproveThreshold(undefined, "headless")).toBe("none");
+  });
+
+  test("falls back to hardcoded defaults on non-404 conversation error", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path.startsWith("/v1/permissions/thresholds/conversations/")) {
+        throw new GatewayRequestError("Internal error", 500, "Server error");
+      }
+      // Should not reach global endpoint
+      return {
+        interactive: "medium",
+        background: "medium",
+        headless: "medium",
+      };
+    };
+
+    const result = await getAutoApproveThreshold("conv-123", "conversation");
+    // Should fall back to hardcoded default for conversation, not global endpoint
+    expect(result).toBe("low");
+    // Should have only called the conversation endpoint
+    expect(gatewayGetCalls).toEqual([
+      "/v1/permissions/thresholds/conversations/conv-123",
+    ]);
+  });
+
+  test("caching: second call within 30s does not re-fetch global", async () => {
+    let fetchCount = 0;
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        fetchCount++;
+        return {
+          interactive: "medium",
+          background: "low",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // First call — should fetch
+    const first = await getAutoApproveThreshold(undefined, "conversation");
+    expect(first).toBe("medium");
+    expect(fetchCount).toBe(1);
+
+    // Second call — should use cache
+    const second = await getAutoApproveThreshold(undefined, "background");
+    expect(second).toBe("low");
+    expect(fetchCount).toBe(1); // Still 1, cache hit
+
+    // Third call — still cached
+    const third = await getAutoApproveThreshold(undefined, "headless");
+    expect(third).toBe("none");
+    expect(fetchCount).toBe(1); // Still 1
+
+    // After clearing cache, should re-fetch
+    _clearGlobalCacheForTesting();
+    const fourth = await getAutoApproveThreshold(undefined, "conversation");
+    expect(fourth).toBe("medium");
+    expect(fetchCount).toBe(2); // Incremented
+  });
+
+  test("defaults executionContext to conversation when omitted", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "medium",
+          background: "low",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // executionContext omitted — should default to "conversation" → interactive
+    const result = await getAutoApproveThreshold(undefined, undefined);
+    expect(result).toBe("medium");
+  });
+
+  test("skips conversation override when no conversationId", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    const result = await getAutoApproveThreshold(undefined, "conversation");
+    expect(result).toBe("low");
+    // Should only call global endpoint, not conversation
+    expect(gatewayGetCalls).toEqual(["/v1/permissions/thresholds"]);
+  });
+
+  test("skips conversation override for non-conversation contexts", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // Even with a conversationId, background context should not check conversation override
+    const result = await getAutoApproveThreshold("conv-123", "background");
+    expect(result).toBe("medium");
+    expect(gatewayGetCalls).toEqual(["/v1/permissions/thresholds"]);
+  });
+});

package/docs/architecture/integrations.md

@@ -149,7 +149,7 @@ sequenceDiagram
 | Decision                                   | Rationale                                                                                                                                                                                                                                                                                         |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | PKCE by default, optional client_secret    | Desktop apps prefer PKCE; some providers (Slack) require a secret, which is stored in the credential store (`oauth_app/{id}/client_secret`) for autonomous refresh                                                                                                                                |
-| Shared connect orchestrator                | All OAuth providers route through `orchestrateOAuthConnect()`, which resolves profiles, enforces scope policy, runs the flow, stores tokens, and verifies identity. Adding a provider is a declarative profile entry, not new orchestration code                                                  |
+| Shared connect orchestrator                | All OAuth providers route through `orchestrateOAuthConnect()`, which resolves profiles, resolves scopes, runs the flow, stores tokens, and verifies identity. Adding a provider is a declarative profile entry, not new orchestration code                                                        |
 | Canonical credential naming                | All reads and writes use `client_id`/`client_secret` as canonical field names                                                                                                                                                                                                                     |
 | Caller-driven callback transport           | Transport (`loopback` or `gateway`) is chosen per-flow via the `callbackTransport` option on the connect API, defaulting to loopback. Desktop clients use loopback (no tunnel needed); web clients can pass `callback_transport: "gateway"`. Provider configuration no longer dictates transport. |
 | Unified `MessagingProvider` interface      | All platforms implement the same contract; generic tools work immediately for new providers                                                                                                                                                                                                       |
@@ -161,34 +161,33 @@ sequenceDiagram
 
 ### Source Files
 
-| File                                             | Role                                                                                               |
-| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| `assistant/src/security/oauth2.ts`               | OAuth2 flow: PKCE or client_secret, Bun.serve callback, token exchange                             |
-| `assistant/src/security/token-manager.ts`        | `withValidToken()` — auto-refresh, 401 retry, expiry buffer                                        |
-| `assistant/src/messaging/provider.ts`            | `MessagingProvider` interface                                                                      |
-| `assistant/src/messaging/provider-types.ts`      | Platform-agnostic types (Conversation, Message, SearchResult)                                      |
-| `assistant/src/messaging/registry.ts`            | Provider registry: register, lookup, list connected                                                |
-| `assistant/src/messaging/style-analyzer.ts`      | Writing style extraction from message corpus                                                       |
-| `assistant/src/messaging/draft-store.ts`         | Local draft storage (platform/id JSON files)                                                       |
-| `assistant/src/messaging/providers/slack/`       | Slack adapter, client, types                                                                       |
-| `assistant/src/messaging/providers/gmail/`       | Gmail adapter, client, types                                                                       |
-| `assistant/src/config/bundled-skills/messaging/` | Core messaging skill (send, read, search, reply across platforms)                                  |
-| `assistant/src/config/bundled-skills/sequences/` | Email sequence management skill (drip campaigns, enrollment, analytics)                            |
-| `assistant/src/watcher/providers/gmail.ts`       | Gmail watcher using History API                                                                    |
-| `assistant/src/watcher/providers/github.ts`      | GitHub watcher for PRs, issues, review requests, and mentions                                      |
-| `assistant/src/watcher/providers/linear.ts`      | Linear watcher for assigned issues, status changes, and @mentions                                  |
-| `assistant/src/oauth/seed-providers.ts`          | Provider seed data: injection templates, identity config, setup metadata (seeded to DB on startup) |
-| `assistant/src/oauth/connect-orchestrator.ts`    | Shared OAuth connect orchestrator: profile resolution, scope policy, flow execution, token storage |
-| `assistant/src/oauth/scope-policy.ts`            | Deterministic scope resolution and policy enforcement                                              |
-| `assistant/src/oauth/connect-types.ts`           | Shared types: `OAuthScopePolicy`, `OAuthConnectResult`                                             |
-| `assistant/src/oauth/token-persistence.ts`       | Token storage helper: persists tokens, metadata, and runs post-connect hooks                       |
-| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic OAuth connect handler (`oauth_connect_start` / `oauth_connect_result`)                     |
+| File                                             | Role                                                                                                   |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `assistant/src/security/oauth2.ts`               | OAuth2 flow: PKCE or client_secret, Bun.serve callback, token exchange                                 |
+| `assistant/src/security/token-manager.ts`        | `withValidToken()` — auto-refresh, 401 retry, expiry buffer                                            |
+| `assistant/src/messaging/provider.ts`            | `MessagingProvider` interface                                                                          |
+| `assistant/src/messaging/provider-types.ts`      | Platform-agnostic types (Conversation, Message, SearchResult)                                          |
+| `assistant/src/messaging/registry.ts`            | Provider registry: register, lookup, list connected                                                    |
+| `assistant/src/messaging/style-analyzer.ts`      | Writing style extraction from message corpus                                                           |
+| `assistant/src/messaging/draft-store.ts`         | Local draft storage (platform/id JSON files)                                                           |
+| `assistant/src/messaging/providers/slack/`       | Slack adapter, client, types                                                                           |
+| `assistant/src/messaging/providers/gmail/`       | Gmail adapter, client, types                                                                           |
+| `assistant/src/config/bundled-skills/messaging/` | Core messaging skill (send, read, search, reply across platforms)                                      |
+| `assistant/src/config/bundled-skills/sequences/` | Email sequence management skill (drip campaigns, enrollment, analytics)                                |
+| `assistant/src/watcher/providers/gmail.ts`       | Gmail watcher using History API                                                                        |
+| `assistant/src/watcher/providers/github.ts`      | GitHub watcher for PRs, issues, review requests, and mentions                                          |
+| `assistant/src/watcher/providers/linear.ts`      | Linear watcher for assigned issues, status changes, and @mentions                                      |
+| `assistant/src/oauth/seed-providers.ts`          | Provider seed data: injection templates, identity config, setup metadata (seeded to DB on startup)     |
+| `assistant/src/oauth/connect-orchestrator.ts`    | Shared OAuth connect orchestrator: profile resolution, scope resolution, flow execution, token storage |
+| `assistant/src/oauth/connect-types.ts`           | Shared types: `AvailableScopes`, `OAuthConnectResult`                                                  |
+| `assistant/src/oauth/token-persistence.ts`       | Token storage helper: persists tokens, metadata, and runs post-connect hooks                           |
+| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic OAuth connect handler (`oauth_connect_start` / `oauth_connect_result`)                         |
 
 ---
 
 ## OAuth Extensibility — DB-Driven Provider Config, Scope Policy, and Connect Orchestrator
 
-The OAuth extensibility layer makes adding a new OAuth provider a fully declarative operation. All provider configuration — protocol fields (auth URLs, token URLs, scopes, scope policy), behavioral fields (identity verification, injection templates, setup metadata), and display metadata — is stored in the `oauth_providers` SQLite table and seeded on startup via `seed-providers.ts`. The shared **connect orchestrator** handles the full flow from provider resolution through token storage.
+The OAuth extensibility layer makes adding a new OAuth provider a fully declarative operation. All provider configuration — protocol fields (auth URLs, token URLs, scopes), behavioral fields (identity verification, injection templates, setup metadata), and display metadata — is stored in the `oauth_providers` SQLite table and seeded on startup via `seed-providers.ts`. The shared **connect orchestrator** handles the full flow from provider resolution through token storage.
 
 ### Provider Configuration (DB-Driven)
 
@@ -199,24 +198,19 @@ Each provider row includes:
 | Column group              | Fields                                                                                                                           | Purpose                                                                                |
 | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | **Protocol**              | `authUrl`, `tokenUrl`, `tokenEndpointAuthMethod`, `extraParams`, `loopbackPort`                                                  | OAuth2 flow parameters                                                                 |
-| **Scopes**                | `defaultScopes`, `scopePolicy`                                                                                                   | Deterministic scope resolution (user-customizable, preserved across seed restarts)     |
+| **Scopes**                | `defaultScopes`, `availableScopes`                                                                                               | Default scopes for connect flow; informational available scopes for assistant context  |
 | **Identity verification** | `identityUrl`, `identityMethod`, `identityHeaders`, `identityBody`, `identityResponsePaths`, `identityFormat`, `identityOkField` | Data-driven identity verifier fetches human-readable account info after token exchange |
 | **Injection templates**   | `injectionTemplates`                                                                                                             | Auto-applied credential injection rules for the script proxy                           |
 | **Setup metadata**        | `displayName`, `description`, `dashboardUrl`, `appType`, `setupNotes`, `requiresClientSecret`                                    | Metadata for the generic OAuth setup skill                                             |
 | **Ping config**           | `pingUrl`, `pingMethod`, `pingHeaders`, `pingBody`                                                                               | Health-check endpoint for `assistant oauth ping`                                       |
 
-### Scope Policy Engine
+### Scope Resolution
 
-`assistant/src/oauth/scope-policy.ts` exports `resolveScopes(profile, requestedScopes)`, which deterministically computes the final scope set:
+Scope resolution is simple — no validation layer:
 
-1. No requested scopes → returns `defaultScopes`.
-2. Requested scopes provided → starts with defaults, then validates each additional scope:
-   - Rejected if in `forbiddenScopes`.
-   - Rejected if `allowAdditionalScopes` is `false`.
-   - Rejected if not in `allowedOptionalScopes`.
-   - Accepted otherwise, added to the union.
-
-Returns `{ ok: true, scopes }` or `{ ok: false, error, allowedScopes }`.
+1. No requested scopes → uses `defaultScopes`.
+2. Requested scopes provided → uses the requested scopes directly (no validation — the OAuth provider rejects invalid scopes).
+3. `availableScopes` is informational context surfaced via CLI for the assistant to consult.
 
 ### Connect Orchestrator
 
@@ -224,7 +218,7 @@ Returns `{ ok: true, scopes }` or `{ ok: false, error, allowedScopes }`.
 
 1. **Receive canonical provider name** — the orchestrator receives the canonical provider name directly (e.g. `google`, `slack`).
 2. **Load provider row** — reads all config from the `oauth_providers` DB table.
-3. **Compute scopes** — `resolveScopes()` with scope policy enforcement.
+3. **Compute scopes** — uses requested scopes directly, or falls back to `defaultScopes`.
 4. **Build OAuth config** — assemble protocol-level config from the DB provider row.
 5. **Run flow** — interactive (opens browser, blocks until completion) or deferred (returns auth URL for the caller to deliver).
 6. **Verify identity** — runs the generic data-driven identity verifier using the provider row's identity columns.
@@ -246,7 +240,7 @@ This replaces provider-specific handlers — any provider in the registry can be
 ### Adding a New OAuth Provider
 
 1. **Add seed data** to `PROVIDER_SEED_DATA` in `assistant/src/oauth/seed-providers.ts`:
-   - Set protocol fields: `authUrl`, `tokenUrl`, `defaultScopes`, `scopePolicy`, `loopbackPort`.
+   - Set protocol fields: `authUrl`, `tokenUrl`, `defaultScopes`, `availableScopes`, `loopbackPort`.
    - Set identity verification: `identityUrl`, `identityMethod`, `identityHeaders`, `identityResponsePaths`, `identityFormat`.
    - Set injection templates: `injectionTemplates` for providers whose tokens should be auto-injected by the script proxy.
    - Set setup metadata: `displayName`, `dashboardUrl`, `appType` enable the generic OAuth setup skill to guide users through app creation.
@@ -259,9 +253,8 @@ This replaces provider-specific handlers — any provider in the registry can be
 | File                                             | Role                                                                        |
 | ------------------------------------------------ | --------------------------------------------------------------------------- |
 | `assistant/src/oauth/seed-providers.ts`          | Provider seed data and startup seeding                                      |
-| `assistant/src/oauth/scope-policy.ts`            | Scope resolution and policy enforcement (pure, no I/O)                      |
 | `assistant/src/oauth/connect-orchestrator.ts`    | Shared connect orchestrator (profile → scopes → flow → tokens)              |
-| `assistant/src/oauth/connect-types.ts`           | Shared types (`OAuthScopePolicy`, `OAuthConnectResult`)                     |
+| `assistant/src/oauth/connect-types.ts`           | Shared types (`AvailableScopes`, `OAuthConnectResult`)                      |
 | `assistant/src/oauth/token-persistence.ts`       | Token storage: credential store writes, metadata upsert, post-connect hooks |
 | `assistant/src/oauth/identity-verifier.ts`       | Generic data-driven identity verifier (reads config from provider DB row)   |
 | `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` handler              |