@agent-native/core 0.165.4 → 0.167.1

package/corpus/templates/forms/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/corpus/templates/forms/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/corpus/templates/macros/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/corpus/templates/macros/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/corpus/templates/macros/app/components/layout/AppLayout.tsx

@@ -27,7 +27,6 @@ import {
 import { useState, useEffect } from "react";
 import { Link, useLocation, useNavigate } from "react-router";
 
-import { Button } from "@/components/ui/button";
 import { Sheet, SheetContent, SheetTitle } from "@/components/ui/sheet";
 import {
   Tooltip,

package/corpus/templates/mail/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/corpus/templates/mail/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/corpus/templates/mail/app/components/email/EmailList.tsx

@@ -50,7 +50,6 @@ import {
   useLabels,
   useMoveEmail,
   unsuppressThread,
-  type BulkEmailTarget,
 } from "@/hooks/use-emails";
 import { useKeyboardShortcuts } from "@/hooks/use-keyboard-shortcuts";
 import {

package/corpus/templates/mail/app/components/layout/AppLayout.tsx

@@ -202,7 +202,7 @@ const collapsibleViews = [
 
 export function AppLayout({ children }: AppLayoutProps) {
   const location = useLocation();
-  const isMobile = useIsMobile();
+
   const t = useT();
   if (BARE_ROUTES.has(location.pathname)) {
     return <>{children}</>;
@@ -245,7 +245,7 @@ function AppLayoutInner({ children }: AppLayoutProps) {
     targets: SnoozeTarget[];
   } | null>(null);
   const [searchFocused, setSearchFocused] = useState(false);
-  const [searchQuery, setSearchQuery] = useState("");
+  const [, setSearchQuery] = useState("");
   const navigate = useNavigate();
   const location = useLocation();
   // Parse view and threadId from pathname since AppLayout is outside <Routes>

package/corpus/templates/mail/shared/markdown.ts

@@ -160,6 +160,9 @@ export function renderInlineMarkdown(markdown: string): string {
 
 export function extractMarkdownUrls(markdown: string): string[] {
   const urls = new Set<string>();
+  // Each pass rewrites what it matched so a later pattern cannot rematch it;
+  // only add() escapes, so the final string is deliberately never read.
+  // oxlint-disable-next-line no-unused-vars
   let text = decodeCommonHtmlEntities(normalizeMarkdownHardBreaks(markdown));
 
   const add = (rawUrl: string) => {

package/corpus/templates/plan/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/corpus/templates/plan/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/corpus/templates/slides/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/corpus/templates/slides/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/corpus/templates/slides/actions/add-slide.ts

@@ -6,7 +6,6 @@ import {
   mergeCreativeContextReuseLabels,
   recordGenerationCreativeContext,
   replaceCreativeContextElementProvenance,
-  validateCreativeContextReuseLabels,
   validateGenerationCreativeContext,
 } from "@agent-native/creative-context/server";
 import type { CreativeContextReuseLabel } from "@agent-native/creative-context/types";

package/corpus/templates/slides/actions/list-decks.ts

@@ -2,7 +2,7 @@ import { defineAction } from "@agent-native/core";
 import { buildDeepLink } from "@agent-native/core/server";
 import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { accessFilter } from "@agent-native/core/sharing";
-import { and, desc, eq, sql } from "drizzle-orm";
+import { and, desc, sql } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";

package/corpus/templates/slides/app/components/editor/EditorSidebar.tsx

@@ -1,7 +1,4 @@
-import {
-  agentNativePath,
-  appBasePath,
-} from "@agent-native/core/client/api-path";
+import { agentNativePath } from "@agent-native/core/client/api-path";
 import type {
   AttributedRecentEdit,
   CollabUser,

package/corpus/templates/slides/app/components/editor/SlideContextToolbar.tsx

@@ -18,7 +18,6 @@ import {
   IconArrowAutofitWidth,
   IconBorderRadius,
   IconBorderStyle,
-  IconBoxPadding,
   IconDots,
   IconGridDots,
   IconItalic,

package/corpus/templates/slides/app/components/editor/SlideEditor.tsx

@@ -1280,7 +1280,7 @@ export default function SlideEditor({
     });
   }, [overflowContentHash, overflowWarningStateKey]);
   const dims = getAspectRatioDims(aspectRatio);
-  const [fitCanvasZoom, setFitCanvasZoom] = useState(100);
+  const [, setFitCanvasZoom] = useState(100);
   const userSetCanvasZoomRef = useRef(false);
   const canvasWidth = Math.round(dims.width * (canvasZoom / 100));
   const canvasTrackRef = useRef<HTMLDivElement>(null);

package/corpus/templates/slides/app/pages/DeckEditor.tsx

@@ -1,8 +1,5 @@
 import { useGuidedQuestionFlow } from "@agent-native/core/client/agent-chat";
-import {
-  agentNativePath,
-  appBasePath,
-} from "@agent-native/core/client/api-path";
+import { appBasePath } from "@agent-native/core/client/api-path";
 import {
   useCollaborativeDoc,
   emailToColor,
@@ -61,7 +58,6 @@ import {
   AlertDialogHeader,
   AlertDialogTitle,
 } from "@/components/ui/alert-dialog";
-import { Button } from "@/components/ui/button";
 import {
   clearSlideEditingActive,
   deckIdFromPathname,
@@ -1374,7 +1370,6 @@ export default function DeckEditor() {
     agentActive: deckAgentActive,
     agentSlideId,
     recentEdits: deckRecentEdits,
-    awareness: deckPresenceAwareness,
   } = useDeckPresence({
     deckId: deck ? (id ?? null) : null,
     activeSlideId: activeSlideId,

package/corpus/templates/tasks/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/corpus/templates/tasks/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/corpus/templates/tasks/app/components/layout/Layout.tsx

@@ -7,7 +7,6 @@ import { IconMenu2 } from "@tabler/icons-react";
 import { useState, useEffect } from "react";
 import { useLocation } from "react-router";
 
-import { Button } from "@/components/ui/button";
 import {
   Sheet,
   SheetContent,

package/corpus/templates/tasks/app/hooks/use-visible-task-fields.ts

@@ -12,10 +12,7 @@ import { useEffect, useRef } from "react";
 import type { FieldDefinition } from "@/hooks/use-custom-fields";
 import { useCustomFields } from "@/hooks/use-custom-fields";
 
-import {
-  invalidateVisibleTaskFields,
-  LIST_VISIBLE_TASK_FIELDS_QUERY_KEY,
-} from "./cache";
+import { invalidateVisibleTaskFields } from "./cache";
 
 export { DEFAULT_TASK_CARD_FIELD_NAMES, TASK_CARD_FIELD_LIMIT };
 

package/corpus/templates/tasks/server/custom-fields/store.ts

@@ -20,12 +20,7 @@ import {
   parseField,
   parseFieldValueShape,
 } from "./parse.js";
-import type {
-  FieldConfigInput,
-  FieldDefinition,
-  FieldType,
-  FieldValue,
-} from "./types.js";
+import type { FieldDefinition, FieldType, FieldValue } from "./types.js";
 import { validateFieldConfig, validateFieldTitle } from "./validate.js";
 import {
   deleteCustomFieldValues,

package/corpus/templates/tasks/shared/list-screen-snapshot.ts

@@ -1,4 +1,4 @@
-export type AgentListSnapshot<TSummary> = {
+export type AgentListSnapshot = {
   totalCount: number;
   truncated: boolean;
 };
@@ -9,7 +9,7 @@ export function buildAgentListSnapshot<TItem, TSummary>(
   toSummary: (item: TItem) => TSummary,
 ): {
   snapshot: TItem[];
-  list: AgentListSnapshot<TSummary> & { items: TSummary[] };
+  list: AgentListSnapshot & { items: TSummary[] };
 } {
   const snapshot = items.slice(0, cap);
   return {

package/dist/agent/engine/registry.js

@@ -552,26 +552,36 @@ async function resolveProviderBaseUrl(envVar) {
         })
         : undefined;
 }
+/**
+ * `null` means no custody — fall through to keys. Must mirror
+ * `BuilderGatewayEngine.stream`'s auth choice exactly: a preflight stricter
+ * than the engine rejects turns the engine would have served.
+ */
+async function builderOAuthLaneUsable(identity) {
+    const ownerEmail = identity?.userEmail?.trim().toLowerCase() || getRequestUserEmail();
+    if (!ownerEmail || !(await hasBuilderOAuthSession(ownerEmail)))
+        return null;
+    try {
+        return Boolean(await resolveBuilderOAuthRequestAccess({
+            ownerEmail,
+            requiredScope: BUILDER_OAUTH_SCOPE,
+        }));
+    }
+    catch {
+        // coercion-ok: custody present but unusable is "not usable", not absent;
+        // reconnect UX is owned by /builder/status, not this boolean probe.
+        return false;
+    }
+}
 /**
  * A Builder connection we could not read is not a missing connection. Throwing
  * keeps that distinction instead of reporting "connect a provider" to a user
  * whose org-shared keys exist but were unreadable.
  */
 async function hasUsableBuilderConnection(identity) {
-    const ownerEmail = identity?.userEmail?.trim().toLowerCase() || getRequestUserEmail();
-    if (ownerEmail && (await hasBuilderOAuthSession(ownerEmail))) {
-        try {
-            return Boolean(await resolveBuilderOAuthRequestAccess({
-                ownerEmail,
-                requiredScope: BUILDER_OAUTH_SCOPE,
-            }));
-        }
-        catch {
-            // coercion-ok: custody present but unusable is "not usable", not absent;
-            // reconnect UX is owned by /builder/status, not this boolean probe.
-            return false;
-        }
-    }
+    const oauthLane = await builderOAuthLaneUsable(identity);
+    if (oauthLane !== null)
+        return oauthLane;
     const creds = await resolveBuilderCredentialsDetailed(identity);
     assertCredentialStoreReadable(creds);
     return Boolean(creds.privateKey && creds.publicKey);
@@ -581,6 +591,9 @@ async function hasUsableBuilderConnection(identity) {
  * "did this user connect Builder" and is false on every credits-only site.
  */
 async function canRunBuilderEngine(identity) {
+    const oauthLane = await builderOAuthLaneUsable(identity);
+    if (oauthLane !== null)
+        return oauthLane;
     const creds = await resolveBuilderGatewayCredentialsDetailed(identity);
     assertCredentialStoreReadable(creds);
     return Boolean(creds.privateKey && creds.publicKey);

package/dist/agent/index.d.ts

@@ -1,4 +1,4 @@
-export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type AgentActionSurfaceDetails, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "./production-agent.js";
+export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type DefaultAgentActionSurface, type AgentActionSurfaceResolution, type AgentActionSurfaceDetails, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "./production-agent.js";
 export { type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, } from "./types.js";
 export { TripWire, type Processor, type ProcessorState, type ProcessorAbort, type ProcessOutputStreamArgs, type ProcessOutputStepArgs, type ProcessOutputResultArgs, } from "./processors.js";
 export { DEFAULT_MODEL } from "./default-model.js";

package/dist/agent/production-agent.d.ts

@@ -259,6 +259,14 @@ export type AgentExecutionMode = "act" | "plan";
 export interface AgentActionSurface {
     allowedActionNames: readonly string[];
 }
+export interface DefaultAgentActionSurface {
+    mode: "default";
+}
+export type AgentActionSurfaceResolution = AgentActionSurface | DefaultAgentActionSurface;
+type NormalizedAgentActionSurface = DefaultAgentActionSurface | {
+    mode: "allowlist";
+    allowedActionNames: string[];
+};
 export interface AgentActionSurfaceDetails {
     event: any;
     ownerEmail: string | null;
@@ -271,10 +279,14 @@ export interface AgentActionSurfaceDetails {
 /** Read a persisted allowlist while preserving legacy absence and failing
  * closed when the field is present but malformed. */
 export declare function readPersistedAllowedActionNames(value: unknown): string[] | undefined;
-export interface PersistedActionSurface {
+export declare function normalizeAgentActionSurfaceResolution(value: unknown): NormalizedAgentActionSurface;
+export type PersistedActionSurface = {
     orgId: string | null;
     allowedActionNames: string[];
-}
+} | {
+    orgId: string | null;
+    mode: "default";
+};
 /** Read a nested persisted action surface. An absent envelope is legacy;
  * a present but invalid envelope is an explicit org-less, empty surface. */
 export declare function readPersistedActionSurface(value: unknown, propertyName: string): PersistedActionSurface | undefined;
@@ -342,11 +354,12 @@ export interface ProductionAgentOptions {
     }>;
     /**
      * Resolve the exact action registry exposed to one interactive agent-chat
-     * request. Returned names are a hard allowlist: omitted actions are absent
-     * from both the provider schemas and the searchable registry. When set, all
-     * allowed actions are loaded directly on the first model request.
+     * request. Return an allowlist to remove omitted actions from both provider
+     * schemas and the searchable registry, or `{ mode: "default" }` to preserve
+     * the normal initial-tool and discovery behavior for that request. Every
+     * allowlisted action is loaded directly on the first model request.
      */
-    resolveActionSurface?: (details: AgentActionSurfaceDetails) => AgentActionSurface | Promise<AgentActionSurface>;
+    resolveActionSurface?: (details: AgentActionSurfaceDetails) => AgentActionSurfaceResolution | Promise<AgentActionSurfaceResolution>;
     /** Optional per-app agent run chunk budget in milliseconds. Defaults to
      *  AGENT_RUN_SOFT_TIMEOUT_MS when set, otherwise no framework-imposed
      *  timeout. When reached, the client receives an internal auto-continuation

package/dist/agent/production-agent.js

@@ -411,13 +411,32 @@ export function readPersistedAllowedActionNames(value) {
     }
     return [...new Set(names)];
 }
+export function normalizeAgentActionSurfaceResolution(value) {
+    if (hasOwn(value, "mode")) {
+        if (value.mode === "default" && !hasOwn(value, "allowedActionNames")) {
+            return { mode: "default" };
+        }
+        throw new Error("resolveActionSurface returned an invalid default surface");
+    }
+    if (!hasOwn(value, "allowedActionNames")) {
+        throw new Error("resolveActionSurface returned an invalid action surface");
+    }
+    const allowedActionNames = value.allowedActionNames;
+    if (!Array.isArray(allowedActionNames) ||
+        !allowedActionNames.every((name) => typeof name === "string")) {
+        throw new Error("resolveActionSurface returned an invalid action surface");
+    }
+    return {
+        mode: "allowlist",
+        allowedActionNames: [...new Set(allowedActionNames)],
+    };
+}
 /** Read a nested persisted action surface. An absent envelope is legacy;
  * a present but invalid envelope is an explicit org-less, empty surface. */
 export function readPersistedActionSurface(value, propertyName) {
     if (!hasOwn(value, propertyName))
         return undefined;
     const surface = value[propertyName];
-    const allowedActionNames = readPersistedAllowedActionNames(surface) ?? [];
     if (!hasOwn(surface, "orgId")) {
         return { orgId: null, allowedActionNames: [] };
     }
@@ -426,6 +445,13 @@ export function readPersistedActionSurface(value, propertyName) {
         (typeof orgId !== "string" || orgId.trim().length === 0)) {
         return { orgId: null, allowedActionNames: [] };
     }
+    if (hasOwn(surface, "mode")) {
+        if (surface.mode === "default" && !hasOwn(surface, "allowedActionNames")) {
+            return { orgId, mode: "default" };
+        }
+        return { orgId: null, allowedActionNames: [] };
+    }
+    const allowedActionNames = readPersistedAllowedActionNames(surface) ?? [];
     return { orgId, allowedActionNames };
 }
 export function filterActionsByAllowedNames(actions, allowedActionNames) {
@@ -6560,6 +6586,7 @@ export function createProductionAgentHandler(options) {
             availableRequestActions = filterActionsByAllowedNames(availableRequestActions, filterHostedHarnessToolNames(Object.keys(availableRequestActions)));
         }
         let surfacedRequestActions = availableRequestActions;
+        let useDefaultRequestActionSurface = !options.resolveActionSurface;
         if (options.resolveActionSurface) {
             const persistedSurface = isBackgroundWorker
                 ? readPersistedActionSurface(body, "__resolvedActionSurface")
@@ -6575,19 +6602,33 @@ export function createProductionAgentHandler(options) {
                     internalContinuation: Boolean(internalContinuation),
                     availableActionNames: Object.keys(availableRequestActions),
                 });
-            surfacedRequestActions = filterActionsByAllowedNames(availableRequestActions, surface.allowedActionNames);
-            if (requestedHostedHarness) {
-                surfacedRequestActions = filterActionsByAllowedNames(surfacedRequestActions, filterHostedHarnessToolNames(Object.keys(surfacedRequestActions)));
-            }
-            const allowedNames = Object.keys(surfacedRequestActions);
+            const normalizedSurface = normalizeAgentActionSurfaceResolution(surface);
             const runCtx = ensureRequestRunContext();
-            if (runCtx)
-                runCtx.allowedActionNames = allowedNames;
-            if (!isBackgroundWorker) {
-                body.__resolvedActionSurface = {
-                    orgId: getRequestOrgId() ?? null,
-                    allowedActionNames: allowedNames,
-                };
+            if (normalizedSurface.mode === "default") {
+                useDefaultRequestActionSurface = true;
+                if (runCtx)
+                    delete runCtx.allowedActionNames;
+                if (!isBackgroundWorker) {
+                    body.__resolvedActionSurface = {
+                        orgId: getRequestOrgId() ?? null,
+                        mode: "default",
+                    };
+                }
+            }
+            else {
+                surfacedRequestActions = filterActionsByAllowedNames(availableRequestActions, normalizedSurface.allowedActionNames);
+                if (requestedHostedHarness) {
+                    surfacedRequestActions = filterActionsByAllowedNames(surfacedRequestActions, filterHostedHarnessToolNames(Object.keys(surfacedRequestActions)));
+                }
+                const allowedNames = Object.keys(surfacedRequestActions);
+                if (runCtx)
+                    runCtx.allowedActionNames = allowedNames;
+                if (!isBackgroundWorker) {
+                    body.__resolvedActionSurface = {
+                        orgId: getRequestOrgId() ?? null,
+                        allowedActionNames: allowedNames,
+                    };
+                }
             }
         }
         // DIAGNOSTIC-ONLY: owner/request context prep (resolveAgentOwnerEmail +
@@ -7075,9 +7116,9 @@ export function createProductionAgentHandler(options) {
             ? createPlanModeActionRegistry(surfacedRequestActions)
             : surfacedRequestActions;
         const availableRequestTools = getEngineTools(requestActions);
-        const initialRequestTools = options.resolveActionSurface
-            ? availableRequestTools
-            : filterInitialEngineTools(availableRequestTools, options.initialToolNames);
+        const initialRequestTools = useDefaultRequestActionSurface
+            ? filterInitialEngineTools(availableRequestTools, options.initialToolNames)
+            : availableRequestTools;
         const requestTools = requestMode === "plan"
             ? preloadPlanModeEngineTools({
                 request: requestMessage,

package/dist/agent/types.d.ts

@@ -208,6 +208,9 @@ export interface AgentChatRequest {
     __resolvedActionSurface?: {
         orgId: string | null;
         allowedActionNames: string[];
+    } | {
+        orgId: string | null;
+        mode: "default";
     };
     /**
      * Stable identity for the logical assistant turn this request belongs to.