@stigmer/react 3.12.0 → 3.12.2

package/src/session/__tests__/useSessionPageFlow.runConfig.test.tsx

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// ---------------------------------------------------------------------------
+// Owner-pinned run config for useSessionPageFlow (stigmer/stigmer#664).
+//
+// A platform-billed embedder pins the model/tier once and every follow-up
+// carries it — winning over the composer's selection, the persisted
+// Console preference, and the last execution's model — including retries,
+// which re-enter the same submit path. Guests never carry a pin: their
+// execution config is owned by the server-side share policy.
+// ---------------------------------------------------------------------------
+
+const mockSendFollowUp = vi.fn();
+
+const mockConv = {
+  session: { spec: { agentInstanceId: "inst_bound" } },
+  isLoading: false,
+  completedExecutions: [] as unknown[],
+  activeStreamExecution: null,
+  workspaceEntries: [] as unknown[],
+  submitApproval: vi.fn(),
+  sendFollowUp: mockSendFollowUp,
+};
+vi.mock("../useSessionConversation", () => ({
+  useSessionConversation: () => mockConv,
+}));
+
+vi.mock("../../hooks", () => ({
+  useStigmer: () => ({ agent: { getByReference: vi.fn() } }),
+}));
+
+vi.mock("../../agent", () => ({
+  useDefaultAgent: () => ({ agent: null, isLoading: false, error: null }),
+}));
+
+const mockWorkspace = {
+  entries: [],
+  hasEntries: false,
+  toInput: vi.fn().mockReturnValue([]),
+  addGitRepo: vi.fn(),
+  addLocalPath: vi.fn(),
+  removeEntry: vi.fn(),
+  clear: vi.fn(),
+};
+vi.mock("../../workspace", () => ({
+  useWorkspaceEntries: () => mockWorkspace,
+}));
+
+vi.mock("../../execution/useSessionVariables", () => ({
+  useSessionVariables: () => ({ variables: [], isEmpty: true, clear: vi.fn() }),
+}));
+
+// Honors `enabled` like the real hook (contract pinned by its own tests).
+vi.mock("../usePersistedModel", () => ({
+  usePersistedModel: (opts?: { enabled?: boolean }) =>
+    (opts?.enabled === false
+      ? ([undefined, vi.fn()] as const)
+      : (["persisted-model", vi.fn()] as const)),
+}));
+
+vi.mock("../useAgentRefFromSession", () => ({
+  useAgentRefFromSession: () => ({ agentRef: null }),
+}));
+
+import { useSessionPageFlow } from "../useSessionPageFlow";
+
+const OPTS = { sessionId: "ses_1", org: "acme" };
+const PIN = { modelName: "pinned-model", serviceTier: "fast" } as const;
+
+describe("useSessionPageFlow — owner-pinned runConfig (#664)", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("stamps the pinned model and fast tier on a composer follow-up, over the composer's own selection", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, runConfig: PIN }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", "user-picked-model", {
+        serviceTier: undefined,
+      });
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("pinned-model");
+    expect(options.serviceTier).toBe("fast");
+  });
+
+  it("stamps the pin on a bare re-submit (the execution-retry path passes no composer args)", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, runConfig: PIN }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("retry me");
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("pinned-model");
+    expect(options.serviceTier).toBe("fast");
+  });
+
+  it("a model-only pin suppresses a composer-armed fast tier (the pin owns the whole run config)", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, runConfig: { modelName: "pinned-model" } }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", undefined, {
+        serviceTier: "fast",
+      });
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("pinned-model");
+    expect(options.serviceTier).toBeUndefined();
+  });
+
+  it("keeps the unpinned behavior byte-identical when no runConfig is given", async () => {
+    const { result } = renderHook(() => useSessionPageFlow(OPTS));
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", "user-picked-model", {
+        serviceTier: "fast",
+      });
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("user-picked-model");
+    expect(options.serviceTier).toBe("fast");
+  });
+
+  it("ignores the pin entirely for guests — their no-modelName invariant survives a misconfigured embed", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, audience: "guest", runConfig: PIN }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up");
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBeUndefined();
+    expect(options.serviceTier).toBeUndefined();
+  });
+
+  it("throws at render for the statically-wrong pin (fast tier, no model)", () => {
+    expect(() =>
+      renderHook(() =>
+        useSessionPageFlow({ ...OPTS, runConfig: { serviceTier: "fast" } }),
+      ),
+    ).toThrowError(/serviceTier "fast" requires modelName/);
+  });
+});

package/src/session/__tests__/useSessionPanel.test.ts

@@ -278,6 +278,120 @@ describe("useSessionPanel — artifact document tabs", () => {
   });
 });
 
+describe("useSessionPanel — observed open state (uncontrolled + onOpenChange)", () => {
+  // The panel opens ITSELF (file/artifact/plan opens, plan auto-open), so —
+  // unlike useDetailTabs' user-driven-only tabs — onOpenChange fires in BOTH
+  // modes: passing only the callback observes the panel without controlling
+  // it (the issue-#300 docking-host case).
+  it("reports the chip toggle without taking control", () => {
+    const seen: boolean[] = [];
+    const { result } = renderPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openPanel());
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(result.current.isOpen).toBe(false);
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("reports internal open intents (openFile), once per actual transition", () => {
+    const seen: boolean[] = [];
+    const { result } = renderPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openFile("e1", "a.ts"));
+    // Already open — a second open intent is not a transition.
+    act(() => result.current.openFile("e1", "b.ts"));
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+  });
+
+  it("reports the plan auto-open — the beat a docking host makes room for", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { rerender } = renderPanel({ onOpenChange });
+    rerender({ phase: null, hasChanges: false, planKey: "e1:streaming", onOpenChange });
+    expect(seen).toEqual([true]);
+  });
+
+  it("starts open when defaultOpen is set, without a spurious notification", () => {
+    const seen: boolean[] = [];
+    const { result } = renderPanel({
+      defaultOpen: true,
+      onOpenChange: (o) => seen.push(o),
+    });
+    expect(result.current.isOpen).toBe(true);
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("useSessionPanel — controlled open state", () => {
+  it("follows the host's open value and ignores defaultOpen", () => {
+    const { result, rerender } = renderPanel({ open: false, defaultOpen: true });
+    expect(result.current.isOpen).toBe(false);
+    rerender({ phase: null, hasChanges: false, open: true, defaultOpen: true });
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("surfaces intents through onOpenChange without flipping state itself", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result, rerender } = renderPanel({ open: false, onOpenChange });
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // The host grants the request.
+    rerender({ phase: null, hasChanges: false, open: true, onOpenChange });
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(seen).toEqual([true, false]);
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("re-fires a declined request (once per request, not per transition)", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result } = renderPanel({ open: false, onOpenChange });
+    act(() => result.current.openFile("e1", "a.ts"));
+    // The host declined (open stayed false) — a later intent must re-fire,
+    // not be swallowed by a stale "already requested" memory.
+    act(() => result.current.openFile("e1", "b.ts"));
+    expect(seen).toEqual([true, true]);
+  });
+
+  it("plan auto-open is reported, not applied — but the tab is pinned and ready", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result, rerender } = renderPanel({ open: false, onOpenChange });
+    rerender({
+      phase: null,
+      hasChanges: false,
+      planKey: "e1:hash-a",
+      open: false,
+      onOpenChange,
+    });
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // View state stays SDK-owned: the plan tab is pinned regardless, so the
+    // moment the host opens the panel the plan is what greets the user.
+    expect(result.current.editorsStore.getSnapshot().editors).toEqual([
+      { entryId: PLAN_DOCUMENT_ENTRY_ID, path: PLAN_DOCUMENT_PATH, preview: false },
+    ]);
+  });
+
+  it("auto-surfaces Changes against the HOST's open state, not the internal one", () => {
+    // The first-write-back trigger reads the effective open value: a
+    // controlled-open panel (whose internal state was never touched) must
+    // still surface Changes…
+    const { result, rerender } = renderPanel({ open: true });
+    rerender({ phase: null, hasChanges: true, open: true });
+    expect(result.current.view).toBe("changes");
+  });
+
+  it("…and a controlled-closed panel must not", () => {
+    const { result, rerender } = renderPanel({ open: false });
+    rerender({ phase: null, hasChanges: true, open: false });
+    expect(result.current.view).toBe("files");
+  });
+});
+
 describe("useSessionPanel — defaultView (home view)", () => {
   it("seeds the view to the provided defaultView (launcher homes on Config)", () => {
     const { result } = renderPanel({ defaultView: "configure" });

package/src/session/audience.ts

@@ -45,3 +45,21 @@
  * presentation means without breaking embedders.
  */
 export type SessionAudience = "integrator" | "endUser" | "guest" | "observer";
+
+/**
+ * Whether the session organisms offer the session panel surface.
+ *
+ * - `"auto"` (default) — the panel and its toggle chip are available
+ *   whenever the audience allows them (every audience except `"guest"`).
+ * - `"none"` — the panel and chip are absent entirely: plan-mode
+ *   auto-open is suppressed and transcript file paths keep their default
+ *   copy behavior. For hosts whose surrounding surface already renders
+ *   the workspace — the composer keeps every capability the audience
+ *   allows, which is what separates this from `audience="guest"`.
+ *
+ * Orthogonal to {@link SessionAudience} on purpose: audience is who is
+ * looking, panel mode is what the host's geometry has room for. A union
+ * (not a boolean) so a future mode — e.g. a host-rendered panel fed by
+ * the SDK's controller — extends the vocabulary instead of breaking it.
+ */
+export type SessionPanelMode = "auto" | "none";

package/src/session/index.ts

@@ -2,7 +2,8 @@ export { toProtoExecutionTarget, fromProtoExecutionTarget } from "./execution-ta
 export type { ExecutionTargetOption } from "./execution-target.js";
 
 export type { RuntimeEnvProvider } from "./runtime-env.js";
-export type { SessionAudience } from "./audience.js";
+export type { SessionAudience, SessionPanelMode } from "./audience.js";
+export type { SessionRunConfig } from "./run-config.js";
 export {
   CHANNEL_SESSION_LABELS,
   isChannelOriginSession,

package/src/session/run-config.ts

@@ -0,0 +1,59 @@
+import type { ServiceTierOption } from "../models/service-tier.js";
+
+/**
+ * Owner-pinned execution config for a session surface
+ * (stigmer/stigmer#664) — the client-side subset of the platform
+ * `RunConfig` that AgentShare and AgentChannel specs pin server-side
+ * (stigmer/stigmer#360). Budget clamps (`max_cost_usd`,
+ * `max_tool_rounds`) are deliberately absent: those are enforcement,
+ * which only the server can own.
+ *
+ * Passed to `SessionViewer` / `NewSessionViewer` (or the underlying
+ * flow hooks) by embedders whose product — not the end user — decides
+ * what serves the conversation: every execution on the surface (first
+ * message, follow-ups, retries) carries the pinned values, and the
+ * model picker hides automatically (a control that has no effect must
+ * not render).
+ *
+ * This is presentation-level pinning for product-embedded sessions,
+ * not a security boundary — a caller with the session's credentials
+ * can still create executions directly. Share/channel surfaces, where
+ * the audience is untrusted, get the server-enforced `RunConfig` on
+ * their specs instead.
+ *
+ * Ignored entirely for the `"guest"` audience: guest execution config
+ * is owned by the server-side share policy, and guest sends carrying
+ * no `modelName` is a pinned invariant.
+ */
+export interface SessionRunConfig {
+  /**
+   * Model every execution runs, as a plain `modelId` from the model
+   * registry. Wins over the composer's selection, the persisted
+   * Console preference, and the last execution's model.
+   */
+  readonly modelName?: string;
+  /**
+   * Service tier for every execution. `"fast"` requires
+   * {@link modelName}: the fast tier is a per-model price (the server
+   * refuses it fail-closed for Auto), so a tier pin without a model
+   * pin is a host configuration error and throws at submit.
+   */
+  readonly serviceTier?: ServiceTierOption;
+}
+
+/**
+ * Fail fast on the one statically-wrong shape: `serviceTier: "fast"`
+ * with no pinned model. Every layer below (composer gate, server
+ * validation) would refuse it anyway — but those surface as an end
+ * user's failed send, while this names the embedder's bug at the
+ * seam where it was written.
+ */
+export function assertValidRunConfig(runConfig: SessionRunConfig): void {
+  if (runConfig.serviceTier === "fast" && !runConfig.modelName) {
+    throw new Error(
+      "SessionRunConfig: serviceTier \"fast\" requires modelName — the fast "
+        + "tier is a per-model price and Auto (no pinned model) has no tier "
+        + "dimension. Pin the model the surface should run.",
+    );
+  }
+}

package/src/session/useNewSessionFlow.ts

@@ -15,9 +15,11 @@ import { withTimeout } from "../internal/withTimeout.js";
 import { useCreateAgentExecution } from "../execution/useCreateAgentExecution.js";
 import type { ExecutionTargetOption } from "./execution-target.js";
 import { useExecutionTarget } from "../execution-target-context.js";
+import { useApprovalDefaults } from "../approval-defaults-context.js";
 import { useRunnerAdapter } from "../runner-adapter.js";
 import { resolveExecutionRuntimeEnv, type RuntimeEnvProvider } from "./runtime-env.js";
 import type { SessionAudience } from "./audience.js";
+import { assertValidRunConfig, type SessionRunConfig } from "./run-config.js";
 
 const DEFAULT_AGENT_TIMEOUT_MS = 10_000;
 
@@ -141,6 +143,16 @@ export interface UseNewSessionFlowOptions {
    * or Environment resources. Large values bloat every prompt.
    */
   readonly sessionContext?: string;
+  /**
+   * Owner-pinned model/tier for the session's first execution
+   * (stigmer/stigmer#664). Stamped at submit, winning over the
+   * composer's selection and the restored Console preference. Pair
+   * with the same pin on the conversation surface
+   * (`useSessionPageFlow` / `SessionViewer`) so follow-ups match.
+   * Ignored for the `"guest"` audience (the platform share policy owns
+   * guest execution config). See {@link SessionRunConfig}.
+   */
+  readonly runConfig?: SessionRunConfig;
 }
 
 /** Return value of {@link useNewSessionFlow}. */
@@ -257,9 +269,24 @@ export function useNewSessionFlow(
     sessionContext,
   } = options;
   const isGuest = options.audience === "guest";
+  // Guests never carry a client pin: guest execution config is owned by
+  // the server-side share policy (GUEST_HARNESS reasoning). Validated at
+  // render so a statically-wrong pin (fast tier, no model) fails in the
+  // embedder's dev loop, not as the end user's failed send.
+  const runConfig = isGuest ? undefined : options.runConfig;
+  if (runConfig) assertValidRunConfig(runConfig);
+  const pinnedModelName = runConfig?.modelName;
+  const pinnedServiceTier = runConfig?.serviceTier;
   const contextTarget = useExecutionTarget();
   const executionTarget = options.executionTarget ?? contextTarget;
   const adapter = useRunnerAdapter();
+  // Host approval default (#302): pre-arm auto_approve_all on the bootstrap
+  // create when the provider says so. Guests never inherit it — a share-link
+  // visitor is not the operator the host's trust judgment covers (the
+  // GUEST_HARNESS fixed-platform-policy reasoning).
+  const approvalDefaults = useApprovalDefaults();
+  const autoApproveAll =
+    (!isGuest && approvalDefaults?.autoApproveAll) || undefined;
 
   const [harness, setHarnessRaw] = useState<HarnessOption>(() => {
     // Guests get the fixed platform policy (see GUEST_HARNESS) and never
@@ -385,12 +412,19 @@ export function useNewSessionFlow(
         const executionFields = {
           org,
           message,
-          modelName: selectedModel ?? validModelId,
+          // The owner pin wins over the composer and the restored
+          // preference (#664); the pinned tier is stamped only as
+          // "fast" — standard stays off the wire, preserving the #357
+          // UNSPECIFIED-vs-explicit telemetry distinction.
+          modelName: pinnedModelName ?? selectedModel ?? validModelId,
           runtimeEnv,
           attachments: context?.attachments,
           interactionMode: context?.interactionMode,
-          serviceTier: context?.serviceTier,
+          serviceTier: pinnedModelName
+            ? (pinnedServiceTier === "fast" ? "fast" : undefined)
+            : context?.serviceTier,
           workspaceFileRefs: context?.workspaceFileRefs,
+          autoApproveAll,
         };
 
         // Resolve which agent the bootstrapped session runs against: an
@@ -477,9 +511,12 @@ export function useNewSessionFlow(
       isGuest,
       harness,
       executionTarget,
+      autoApproveAll,
       adapter,
       getRuntimeEnv,
       validModelId,
+      pinnedModelName,
+      pinnedServiceTier,
       workspace,
       mcpServerUsages,
       skillRefs,

package/src/session/useSessionConversation.ts

@@ -21,7 +21,9 @@ import type { ServiceTierOption } from "../models/service-tier.js";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
 import { useConversationStoreRef } from "../internal/store/index.js";
-import { useCreateAgentExecution } from "../execution/useCreateAgentExecution.js";
+// Type-only import so the SharedAgentExecutionFields doc links below resolve;
+// the strict tsdoc gate (tsdoc:check) guards it against removal.
+import { useCreateAgentExecution, type SharedAgentExecutionFields } from "../execution/useCreateAgentExecution.js";
 import { useExecutionStream } from "../execution/useExecutionStream.js";
 import { useAgentExecutionActions } from "../execution/useAgentExecutionActions.js";
 import { useSubmitApproval } from "../execution/useSubmitApproval.js";
@@ -74,10 +76,12 @@ export interface SendFollowUpOptions {
    * Execution-scoped secrets and configuration (Execution Flow).
    *
    * Values are injected into the agent sandbox for this execution only
-   * and deleted when the execution completes. They override both
-   * Environment values and agent defaults.
+   * and deleted when the execution completes. They take the highest
+   * merge priority, overriding Environment values bound via the
+   * instance. Keys must be declared in the agent's env declarations
+   * (a whitelist, not a value source) or they are dropped.
    *
-   * @see {@link CreateAgentExecutionInput.runtimeEnv}
+   * @see {@link SharedAgentExecutionFields.runtimeEnv}
    */
   readonly runtimeEnv?: Record<string, EnvVarInput>;
   /**
@@ -87,7 +91,7 @@ export interface SendFollowUpOptions {
    * `agentExecution.uploadAttachment()`. Forwarded directly to
    * execution creation.
    *
-   * @see {@link CreateAgentExecutionInput.attachments}
+   * @see {@link SharedAgentExecutionFields.attachments}
    */
   readonly attachments?: AttachmentInput[];
   /**
@@ -104,19 +108,19 @@ export interface SendFollowUpOptions {
    * the unspecified-vs-explicit distinction (unset resolves to standard on
    * the platform side — never the provider account default).
    *
-   * @see {@link CreateAgentExecutionInput.serviceTier}
+   * @see {@link SharedAgentExecutionFields.serviceTier}
    */
   readonly serviceTier?: ServiceTierOption;
   /**
    * Marks this execution as a Build-from-plan turn.
    *
-   * @see {@link CreateAgentExecutionInput.buildFromPlan}
+   * @see {@link SharedAgentExecutionFields.buildFromPlan}
    */
   readonly buildFromPlan?: boolean;
   /**
    * Auto-approve every tool call for this execution (bypass the HITL gate).
    *
-   * @see {@link CreateAgentExecutionInput.autoApproveAll}
+   * @see {@link SharedAgentExecutionFields.autoApproveAll}
    */
   readonly autoApproveAll?: boolean;
   /**
@@ -125,7 +129,7 @@ export interface SendFollowUpOptions {
    * Lightweight "attention" signals — no upload, no injection. The agent
    * reads these files directly from the workspace filesystem.
    *
-   * @see {@link CreateAgentExecutionInput.workspaceFileRefs}
+   * @see {@link SharedAgentExecutionFields.workspaceFileRefs}
    */
   readonly workspaceFileRefs?: string[];
   /**
@@ -134,7 +138,7 @@ export interface SendFollowUpOptions {
    * The conversation read model hides the superseded execution so the
    * edited message replaces the original in place.
    *
-   * @see {@link CreateAgentExecutionInput.supersedesExecutionId}
+   * @see {@link SharedAgentExecutionFields.supersedesExecutionId}
    */
   readonly supersedesExecutionId?: string;
 }

package/src/session/useSessionPageFlow.ts

@@ -6,6 +6,7 @@ import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 import type { AgentResolution } from "../agent/index.js";
 import { useDefaultAgent } from "../agent/index.js";
 import { useStigmer } from "../hooks.js";
+import { useApprovalDefaults } from "../approval-defaults-context.js";
 import { useWorkspaceEntries, type UseWorkspaceEntriesReturn } from "../workspace/index.js";
 import { useSessionVariables, type UseSessionVariablesReturn } from "../execution/useSessionVariables.js";
 import type { SessionComposerSubmitContext, InteractionModeOption } from "../composer/index.js";
@@ -19,6 +20,7 @@ import { useAgentRefFromSession } from "./useAgentRefFromSession.js";
 import { usePersistedModel, type UsePersistedModelReturn } from "./usePersistedModel.js";
 import { specMcpUsagesToInput, specSkillRefsToInput } from "./session-spec-converters.js";
 import type { SessionAudience } from "./audience.js";
+import { assertValidRunConfig, type SessionRunConfig } from "./run-config.js";
 
 /**
  * Well-known Daytona sandbox workspace root. Used as the SDK safety-net
@@ -56,6 +58,16 @@ export interface UseSessionPageFlowOptions {
    * @default "integrator"
    */
   readonly audience?: SessionAudience;
+  /**
+   * Owner-pinned model/tier for every follow-up on this surface
+   * (stigmer/stigmer#664). Stamped at submit — after the composer, so
+   * it wins over composer state, the persisted Console preference, and
+   * the last execution's model — and therefore also covers retries,
+   * which re-enter the same submit path. Ignored for the `"guest"`
+   * audience (the server-side share policy owns guest execution
+   * config). See {@link SessionRunConfig}.
+   */
+  readonly runConfig?: SessionRunConfig;
 }
 
 /** Return value of {@link useSessionPageFlow}. */
@@ -130,10 +142,13 @@ export interface UseSessionPageFlowReturn {
   /**
    * Session-scoped "auto-approve tool calls" preference.
    *
-   * `false` by default. Flipped to `true` when the user chooses
-   * "Approve & don't ask again" at an approval gate (see {@link submitApproval}),
-   * and carried into every subsequent follow-up via {@link handleSubmit}. Held in
-   * memory only — reset on reload / new session, never persisted server-side.
+   * `false` by default; a host can pre-arm it app-wide via
+   * `StigmerProvider`'s `approvalDefaults` (#302, guests excluded). Flipped
+   * to `true` when the user chooses "Approve & don't ask again" at an
+   * approval gate (see {@link submitApproval}), and carried into every
+   * subsequent follow-up via {@link handleSubmit}. Held in memory only —
+   * reset on reload / new session back to the host default, never persisted
+   * server-side.
    */
   readonly autoApproveAll: boolean;
   /**
@@ -240,6 +255,18 @@ export function useSessionPageFlow(
 ): UseSessionPageFlowReturn {
   const { sessionId, org, getRuntimeEnv } = options;
   const isGuest = options.audience === "guest";
+  // Guests never carry a client pin: guest execution config is owned by
+  // the server-side share policy, and the no-modelName guest invariant
+  // is test-pinned.
+  const runConfig = isGuest ? undefined : options.runConfig;
+  // Render-time, not submit-time: the pin is static host configuration,
+  // so a statically-wrong shape (fast tier, no model) should fail at
+  // mount in the embedder's dev loop — not as an end user's failed send.
+  if (runConfig) assertValidRunConfig(runConfig);
+  // Scalars, not the object: hosts pass inline literals, and the submit
+  // callback's identity must not churn on every render (DD-010).
+  const pinnedModelName = runConfig?.modelName;
+  const pinnedServiceTier = runConfig?.serviceTier;
 
   const stigmer = useStigmer();
   const conv = useSessionConversation(sessionId, org);
@@ -294,9 +321,17 @@ export function useSessionPageFlow(
   const [skillRefs, setSkillRefs] = useState<ResourceRef[]>([]);
   const initialSyncDone = useRef(false);
 
-  // Session-scoped auto-approve, set at the approval gate (not pre-armed in the
-  // composer). Lives only in memory for the life of this page — reset on reload.
-  const [autoApproveAll, setAutoApproveAll] = useState(false);
+  // Session-scoped auto-approve. Armed either at the approval gate ("Approve &
+  // don't ask again") or from the host's provider-level approvalDefaults
+  // (#302) — an app-level trust judgment, so it seeds the INITIAL state only;
+  // the user's in-session "Turn off" always wins from then on. Guests never
+  // inherit the host default (a share-link visitor is not the operator the
+  // host's trust judgment covers). Lives only in memory for the life of this
+  // page — reset on reload re-applies the host default, never a user choice.
+  const approvalDefaults = useApprovalDefaults();
+  const [autoApproveAll, setAutoApproveAll] = useState(
+    () => !isGuest && (approvalDefaults?.autoApproveAll ?? false),
+  );
 
   const submitApproval = useCallback<UseSessionConversationReturn["submitApproval"]>(
     async (toolCallId, action, comment) => {
@@ -429,7 +464,11 @@ export function useSessionPageFlow(
 
       conv.sendFollowUp(message, {
         agentInstanceId: agentInstanceIdOverride,
-        modelName: selectedModel ?? modelId,
+        // The owner pin wins over everything the user or the SDK
+        // resolved (#664); the pinned tier is stamped only as "fast" —
+        // an untouched/standard tier stays off the wire, preserving the
+        // #357 UNSPECIFIED-vs-explicit telemetry distinction.
+        modelName: pinnedModelName ?? selectedModel ?? modelId,
         workspaceEntries: workspace.hasEntries
           ? workspace.toInput()
           : undefined,
@@ -438,7 +477,9 @@ export function useSessionPageFlow(
         runtimeEnv,
         attachments: context?.attachments,
         interactionMode: context?.interactionMode,
-        serviceTier: context?.serviceTier,
+        serviceTier: pinnedModelName
+          ? (pinnedServiceTier === "fast" ? "fast" : undefined)
+          : context?.serviceTier,
         buildFromPlan: context?.buildFromPlan,
         // Sourced from the session-scoped preference set at the approval gate,
         // not from the composer (the pre-arm toggle was removed).
@@ -449,7 +490,7 @@ export function useSessionPageFlow(
 
       sessionVariables.clear();
     },
-    [conv.sendFollowUp, modelId, workspace, mcpServerUsages, skillRefs, sessionVariables.clear, resolution, agentRef, sessionInstanceId, stigmer, autoApproveAll, getRuntimeEnv],
+    [conv.sendFollowUp, modelId, pinnedModelName, pinnedServiceTier, workspace, mcpServerUsages, skillRefs, sessionVariables.clear, resolution, agentRef, sessionInstanceId, stigmer, autoApproveAll, getRuntimeEnv],
   );
 
   // -------------------------------------------------------------------------