myrlin-workbook 1.2.0-alpha.2 → 1.2.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myrlin-workbook",
-  "version": "1.2.0-alpha.2",
+  "version": "1.2.0-alpha.4",
   "description": "Browser-based project manager for AI coding assistants (Claude Code, ChatGPT Codex). Multi-provider session discovery, search, live terminals, docs, kanban, themes.",
   "main": "src/index.js",
   "bin": {

package/src/providers/codex/spawn.js

@@ -1,35 +1,34 @@
 /**
  * Codex provider spawn descriptor builder.
  *
- * Phase 17 Plan 17-02 (CDX-07 spawn half).
+ * Phase 17 Plan 17-02 (CDX-07 spawn half) shipped the minimum surface:
+ * `resume <id>` when providerSessionId is set, fresh-session otherwise.
+ * Phase 21 Plan 21-01 extends this with optional providerSettings so the
+ * frontend right-click menu can drive Codex CLI flags (model, sandbox,
+ * approval policy, reasoning effort, bypass, feature enables).
  *
- * Pure function that builds the SpawnDescriptor pty-manager uses to launch
- * the Codex CLI. Mirrors the shape established by src/providers/claude/spawn.js
- * so the existing pty-manager pass-through plumbing (Plan 14-04) needs no
- * Codex-specific code path.
+ * Pure function. Pty-manager (Plan 14-04) reads the returned descriptor and
+ * owns the actual node-pty.spawn call. No filesystem touches, no env
+ * mutation, no network. Validation is defensive: unsafe values trigger a
+ * console.warn and are dropped silently rather than throwing, so a stale
+ * frontend value never blocks a pane spawn.
  *
- * Phase 17 ships the minimum surface: a `resume <id>` invocation when
- * providerSessionId is set, a fresh-session invocation when it is not. No
- * --model, --verbose, --workdir, or other flags are passed today; Phase 19
- * (Codex Live PTY End-to-End) will add them once the live terminal plumbing
- * exists. Keeping the surface narrow now avoids exposing flags that may be
- * renamed by upstream Codex before they are tested.
+ * Flag translation (providerSettings -> argv):
+ *   model               -> ['-m', model]
+ *   sandbox             -> ['-s', sandbox]
+ *   approvalPolicy      -> ['-a', approvalPolicy]
+ *   reasoningEffort     -> ['-c', 'model_reasoning_effort="<effort>"']
+ *   bypassApprovalsAndSandbox: true
+ *                       -> ['--dangerously-bypass-approvals-and-sandbox']
+ *   features: [name,..] -> ['--enable', name] pairs
  *
- * CODEX_HOME env scoping: process.env.CODEX_HOME is propagated through the
- * descriptor so a user with a non-default $CODEX_HOME survives a Myrlin pane
- * spawn (the spawned `codex` process otherwise inherits the parent's env,
- * which works in the common case, but explicit propagation is the
- * documentation-friendly form: the descriptor advertises which env keys
- * matter). When the parent env does NOT set CODEX_HOME, env.CODEX_HOME is
- * set to undefined which pty-manager treats as DELETE-this-key. Net effect
- * for the unset case is identical to leaving the env alone; the explicit
- * assign documents the contract.
+ * Positional ordering invariant: any `resume <id>` positional pair stays
+ * LAST in args so flags cannot be misparsed as the resume id. This matches
+ * the Codex CLI convention (subcommand positions trail option flags).
  *
- * Validation: the providerSessionId is checked against /^[a-zA-Z0-9_-]+$/
- * before being placed in args. Shell unsafe characters (semicolons,
- * backticks, spaces, etc.) trigger an Error. This matches the pattern in
- * claude/spawn.js verbatim so any input that passes the SHELL_UNSAFE gate
- * for Claude also passes for Codex.
+ * Enum allow-lists are intentionally short and conservative. Drop-unknown
+ * with a console.warn keeps the spawn path resilient against typos and
+ * stale fields from older clients.
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  *
@@ -38,68 +37,161 @@
 
 'use strict';
 
-// The literal 'codex' below is the CLI binary name (the npm-published Codex
-// CLI installs a `codex` executable). This file lives inside src/providers/codex/,
-// which the grep gate (Plan 14-05) skips, so the marker is defensive (extra
-// signal for future readers) rather than required.
 const CODEX_BINARY = 'codex'; // gsd:provider-literal-allowed (Codex provider CLI binary)
 
+// Same shell-safe regex Claude uses for its providerSessionId gate.
+const SAFE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+// Shell-unsafe characters for free-form values (model names, etc.). Mirrors
+// pty-manager.js SHELL_UNSAFE so anything that passes here also passes the
+// outer gate; we keep the local copy so this module is testable standalone.
+const SHELL_UNSAFE_RE = /[;&|`$(){}[\]<>!#*?\n\r\\'"]/;
+
+// Enum allow-lists. Conservative on purpose: only values the Codex CLI
+// accepts today. Unknown values get dropped with a console.warn instead of
+// crashing the spawn so a stale frontend cache never blocks a pane.
+const SANDBOX_VALUES = new Set([
+  'read-only',
+  'workspace-write',
+  'danger-full-access',
+]);
+
+const APPROVAL_VALUES = new Set([
+  'untrusted',
+  'on-failure',
+  'on-request',
+  'never',
+]);
+
+const EFFORT_VALUES = new Set([
+  'minimal',
+  'low',
+  'medium',
+  'high',
+]);
+
+// Feature name format: short alphanumeric + dash/underscore. Matches Codex
+// CLI --enable token shape (e.g. web_search, view_image).
+const FEATURE_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+
+// Model id format: alphanumeric + dot/dash/underscore/colon. Cap length so
+// argv stays bounded. The colon allows version-suffixed model ids
+// ("gpt-5:2025-09-01"-shape).
+const MODEL_ID_RE = /^[a-zA-Z0-9._:-]{1,128}$/;
+
 /**
- * Validate providerSessionId against the same shell-safe regex Claude uses.
- * UUIDs (with or without hyphens) and slug-style identifiers pass; anything
- * with spaces, quotes, semicolons, backticks, or other shell-special bytes
- * trips the gate.
+ * Validate providerSessionId. Reused by tests.
  *
- * @param {string} id - candidate providerSessionId
- * @returns {boolean} true when id is safe to interpolate into argv tokens
+ * @param {*} id
+ * @returns {boolean}
  */
 function isSafeProviderSessionId(id) {
-  return typeof id === 'string' && /^[a-zA-Z0-9_-]+$/.test(id);
+  return typeof id === 'string' && SAFE_ID_RE.test(id);
+}
+
+/**
+ * Translate an optional providerSettings bundle to Codex CLI argv tokens.
+ * Pure function. Unknown values are dropped with a single console.warn so
+ * one bad field does not abort the spawn.
+ *
+ * @param {Object} [settings] - providerSettings.codex bundle. Optional.
+ * @returns {string[]} Flag tokens ordered model, sandbox, approval, effort,
+ *   bypass, then feature pairs. Caller appends positional args after.
+ */
+function buildFlagsFromSettings(settings) {
+  if (!settings || typeof settings !== 'object') return [];
+  const flags = [];
+
+  if (typeof settings.model === 'string' && settings.model.length > 0) {
+    if (MODEL_ID_RE.test(settings.model) && !SHELL_UNSAFE_RE.test(settings.model)) {
+      flags.push('-m', settings.model);
+    } else {
+      console.warn('[codex/spawn] dropping unsafe/oversized model: ' + settings.model);
+    }
+  }
+
+  if (typeof settings.sandbox === 'string' && settings.sandbox.length > 0) {
+    if (SANDBOX_VALUES.has(settings.sandbox)) {
+      flags.push('-s', settings.sandbox);
+    } else {
+      console.warn('[codex/spawn] dropping unknown sandbox: ' + settings.sandbox);
+    }
+  }
+
+  if (typeof settings.approvalPolicy === 'string' && settings.approvalPolicy.length > 0) {
+    if (APPROVAL_VALUES.has(settings.approvalPolicy)) {
+      flags.push('-a', settings.approvalPolicy);
+    } else {
+      console.warn('[codex/spawn] dropping unknown approvalPolicy: ' + settings.approvalPolicy);
+    }
+  }
+
+  if (typeof settings.reasoningEffort === 'string' && settings.reasoningEffort.length > 0) {
+    if (EFFORT_VALUES.has(settings.reasoningEffort)) {
+      // TOML-safe value formatting: quote the string so the Codex `-c key=val`
+      // parser treats it as a literal even if a future effort name contains
+      // chars TOML would interpret. Today all enum values are bare words and
+      // quoting them is a no-op, but the quotes future-proof the contract.
+      flags.push('-c', 'model_reasoning_effort="' + settings.reasoningEffort + '"');
+    } else {
+      console.warn('[codex/spawn] dropping unknown reasoningEffort: ' + settings.reasoningEffort);
+    }
+  }
+
+  if (settings.bypassApprovalsAndSandbox === true) {
+    flags.push('--dangerously-bypass-approvals-and-sandbox');
+  }
+
+  if (Array.isArray(settings.features)) {
+    for (const name of settings.features) {
+      if (typeof name === 'string' && FEATURE_NAME_RE.test(name) && !SHELL_UNSAFE_RE.test(name)) {
+        flags.push('--enable', name);
+      } else {
+        console.warn('[codex/spawn] dropping unsafe feature name: ' + name);
+      }
+    }
+  }
+
+  return flags;
 }
 
 /**
  * Build a SpawnDescriptor for the Codex CLI.
  *
  * Pure function. Does NOT touch the filesystem, the network, or any state.
- * Does NOT mutate process.env. Throws on invalid input. Returns a descriptor
- * that pty-manager joins, shell-wraps, and runs through node-pty.
+ * Does NOT mutate process.env. Throws on invalid providerSessionId. Unknown
+ * providerSettings values are dropped (warn only) rather than thrown.
  *
- * Phase 17 minimum surface:
- *   - providerSessionId set    -> ['resume', '<id>']
- *   - providerSessionId unset  -> []
+ * argv ordering:
+ *   [<flag tokens from providerSettings...>, 'resume', '<id>']
  *
- * Phase 19 (Codex Live PTY) will extend this with --model, --verbose, and
- * the equivalent of Claude's initialPrompt argument once the live PTY
- * plumbing has shipped and the Codex flag surface is locked.
+ * The positional resume pair stays LAST so flag-shaped resume ids cannot be
+ * misparsed (the Codex CLI takes the subcommand as a trailing position).
  *
- * @param {Object} [init] - spawn input bundle
- * @param {string|null} [init.providerSessionId] - Codex session UUID for `resume`.
- *   Validated against /^[a-zA-Z0-9_-]+$/. Throws on unsafe input.
- * @param {string|null} [init.cwd] - Working directory; passes through.
- *   pty-manager validates and falls back to homedir if missing.
- * @returns {{cmd: string, args: string[], cwd: (string|null), env: Object<string,(string|undefined)>}} SpawnDescriptor.
+ * @param {Object} [init]
+ * @param {string|null} [init.providerSessionId] - Codex session UUID for
+ *   `resume`. Validated against /^[a-zA-Z0-9_-]+$/. Throws on unsafe input.
+ * @param {string|null} [init.cwd] - Working directory; pass-through.
+ * @param {Object} [init.providerSettings] - Optional Codex settings bundle.
+ *   See buildFlagsFromSettings for accepted keys.
+ * @returns {{cmd:string, args:string[], cwd:(string|null), env:Object}}
  * @throws {Error} when providerSessionId fails the safety regex.
  */
-function spawnCommand({ providerSessionId = null, cwd = null } = {}) {
-  // Validate first so we never produce an unsafe argv even partially.
+function spawnCommand({ providerSessionId = null, cwd = null, providerSettings = null } = {}) {
   if (providerSessionId && !isSafeProviderSessionId(providerSessionId)) {
     throw new Error('unsafe providerSessionId: ' + providerSessionId);
   }
 
-  const args = [];
+  // Flags first, positional resume <id> last so flag/value pairs cannot
+  // accidentally swallow the resume id at argv-parse time.
+  const args = buildFlagsFromSettings(providerSettings);
   if (providerSessionId) {
-    // Codex's resume subcommand takes the session UUID as a positional arg.
-    // The exact CLI invocation is:  codex resume <uuid>
-    args.push('resume');
-    args.push(providerSessionId);
+    args.push('resume', providerSessionId);
   }
-  // Phase 17 deliberately stops here. Additional flags belong in Phase 19.
 
   // CODEX_HOME scoping: read process.env at call time so a test that
   // mutates the env in a try/finally sees the change reflected here.
-  // We DO NOT cache the value at module load. The undefined-means-delete
-  // semantic is honored by pty-manager (see pty-manager.js: any env value
-  // that is `=== undefined` is removed from the spawn env via delete).
+  // Undefined-means-delete semantic honored by pty-manager.
   const codexHomeFromEnv = process.env.CODEX_HOME;
   const envOverride = {
     CODEX_HOME: typeof codexHomeFromEnv === 'string' && codexHomeFromEnv.length > 0
@@ -115,4 +207,4 @@ function spawnCommand({ providerSessionId = null, cwd = null } = {}) {
   };
 }
 
-module.exports = { spawnCommand };
+module.exports = { spawnCommand, buildFlagsFromSettings };

package/src/state/store.js

@@ -747,6 +747,66 @@ class Store extends EventEmitter {
     return this.updateSession(id, { status, pid });
   }
 
+  /**
+   * Persist per-session provider settings (Phase 21 Plan 21-01).
+   *
+   * Shape:
+   *   session.providerSettings = { [providerId]: { ...settings } }
+   *
+   * Per-provider merging: the new settings object REPLACES the existing
+   * bundle for that providerId. Other providers' bundles on the same
+   * session are untouched. Caller is responsible for shallow-merging if
+   * a partial update is desired (the route currently sends a full
+   * canonical bundle, so replace-on-write is the right default).
+   *
+   * @param {string} sessionId
+   * @param {string} providerId - Provider id string (registry-issued).
+   * @param {Object} settings - The canonical settings bundle to persist.
+   * @returns {Object|null} Updated session or null if not found.
+   */
+  updateSessionProviderSettings(sessionId, providerId, settings) {
+    const session = this._state.sessions[sessionId];
+    if (!session) return null;
+    if (!session.providerSettings || typeof session.providerSettings !== 'object') {
+      session.providerSettings = {};
+    }
+    session.providerSettings[providerId] = settings;
+    session.lastActive = new Date().toISOString();
+    this.save();
+    this.emit('session:updated', session);
+    return session;
+  }
+
+  /**
+   * Read the effective provider settings for a session, with fallback to
+   * the per-provider defaults in `state.settings.providerDefaults[providerId]`.
+   * Used by the route handler so the UI sees defaults when a session has
+   * no overrides yet.
+   *
+   * @param {string} sessionId
+   * @param {string} providerId
+   * @returns {Object} Settings bundle (may be empty object).
+   */
+  getSessionProviderSettings(sessionId, providerId) {
+    const session = this._state.sessions[sessionId];
+    const fromSession = session
+      && session.providerSettings
+      && typeof session.providerSettings === 'object'
+      && session.providerSettings[providerId]
+      && typeof session.providerSettings[providerId] === 'object'
+      ? session.providerSettings[providerId]
+      : null;
+    if (fromSession) return fromSession;
+    const defaults = this._state.settings
+      && this._state.settings.providerDefaults
+      && typeof this._state.settings.providerDefaults === 'object'
+      && this._state.settings.providerDefaults[providerId]
+      && typeof this._state.settings.providerDefaults[providerId] === 'object'
+      ? this._state.settings.providerDefaults[providerId]
+      : {};
+    return defaults;
+  }
+
   addSessionLog(id, message) {
     const session = this._state.sessions[id];
     if (!session) return;

package/src/web/pty-manager.js

@@ -349,6 +349,17 @@ class PtySessionManager {
     // ── Block B (Plan 14-04): Build descriptor (provider OR inline) ──
     let descriptor;
     if (useProvider) {
+      // Phase 21 Plan 21-01: per-session providerSettings drives provider CLI flags.
+      // Read the bundle for THIS provider so a Claude session never receives
+      // a Codex-shaped bundle and vice versa. Missing/non-object yields null;
+      // the provider's spawnCommand treats null as "no extra flags".
+      const providerSettingsBundle = storeSession
+        && storeSession.providerSettings
+        && typeof storeSession.providerSettings === 'object'
+        && storeSession.providerSettings[providerId]
+        && typeof storeSession.providerSettings[providerId] === 'object'
+        ? storeSession.providerSettings[providerId]
+        : null;
       try {
         descriptor = provider.spawnCommand({
           sessionId,
@@ -359,6 +370,7 @@ class PtySessionManager {
           model,
           verbose,
           initialPrompt,
+          providerSettings: providerSettingsBundle,
         });
       } catch (err) {
         console.error('[PTY] Provider ' + providerId + ' spawnCommand failed for ' + sessionId + ': ' + err.message);

package/src/web/public/app.js

@@ -11397,6 +11397,188 @@ class CWMApp {
     this._renderContextItems('Open View', items, x, y);
   }
 
+  /**
+   * Build the "Codex settings" submenu (Plan 21-01).
+   *
+   * Pure factory: returns an array of menu items suitable for the existing
+   * _renderContextItems renderer (label/submenu/check/hint/action/danger
+   * shape). Reads the session's current providerSettings from
+   * this.state.allSessions (or this.state.sessions) and uses the values to
+   * mark the active option with a check in each submenu.
+   *
+   * Each leaf action PUTs the new bundle to the server and shows a toast
+   * hinting the user to restart the pane for the change to take effect
+   * (pty-manager only reads providerSettings on spawn). The bypass toggle
+   * routes through showConfirmModal first because it weakens the sandbox.
+   *
+   * Dispatched from showTerminalContextMenu when the pane's
+   * dataset.provider matches the Codex provider id. Pane menus for other
+   * providers skip this branch so a Claude pane never shows a Codex submenu.
+   *
+   * @param {number} slotIdx - Terminal pane slot index.
+   * @param {Object} tp - The TerminalPane instance for this slot.
+   * @returns {Array<Object>} Menu items to splice into the pane context menu.
+   */
+  _buildCodexPaneMenu(slotIdx, tp) { // gsd:provider-literal-allowed (Codex pane menu factory)
+    const sessionId = tp.sessionId;
+    // Look up the session record to read providerSettings.codex. Defensive
+    // because some panes (Codex Desktop project sessions) may not exist in
+    // the live sessions list yet; in that case we render with empty
+    // settings and let the user dial them in.
+    const allSessions = [
+      ...(this.state.sessions || []),
+      ...(this.state.allSessions || []),
+    ];
+    const sess = allSessions.find(s => s && s.id === sessionId) || {};
+    const codexSettings = (sess.providerSettings && sess.providerSettings.codex) /* gsd:provider-literal-allowed */ || {};
+
+    const putSettings = async (partial) => {
+      const next = { ...codexSettings, ...partial };
+      try {
+        await this.api('PUT', '/api/sessions/' + encodeURIComponent(sessionId) + '/provider-settings', { settings: next });
+        // Mutate the cached session so subsequent menu opens reflect the
+        // change without a full refetch. The next saveTerminalLayout or
+        // loadSessions tick will rehydrate from the server.
+        if (!sess.providerSettings) sess.providerSettings = {};
+        sess.providerSettings.codex = next; // gsd:provider-literal-allowed
+        this.showToast('Codex settings updated — restart pane to apply', 'info');
+      } catch (err) {
+        this.showToast(err.message || 'Failed to update Codex settings', 'error');
+      }
+    };
+
+    // Catalog of accepted values per setting. Mirrors backend allow-lists.
+    const MODEL_OPTIONS = [
+      { id: 'gpt-5-codex', label: 'gpt-5-codex' },
+      { id: 'gpt-5', label: 'gpt-5' },
+      { id: 'o3', label: 'o3' },
+    ];
+    const SANDBOX_OPTIONS = [
+      { id: 'read-only', label: 'read-only' },
+      { id: 'workspace-write', label: 'workspace-write' },
+      { id: 'danger-full-access', label: 'danger-full-access (risky)' },
+    ];
+    const APPROVAL_OPTIONS = [
+      { id: 'untrusted', label: 'untrusted (prompt for unknown commands)' },
+      { id: 'on-failure', label: 'on-failure' },
+      { id: 'on-request', label: 'on-request' },
+      { id: 'never', label: 'never (auto-approve everything)' },
+    ];
+    const EFFORT_OPTIONS = [
+      { id: 'minimal', label: 'minimal' },
+      { id: 'low', label: 'low' },
+      { id: 'medium', label: 'medium' },
+      { id: 'high', label: 'high' },
+    ];
+    const FEATURE_OPTIONS = [
+      { id: 'web_search', label: 'Web search' },
+      { id: 'view_image', label: 'View images' },
+      { id: 'plan_tool', label: 'Plan tool' },
+      { id: 'apply_patch_tool', label: 'Apply patch tool' },
+    ];
+
+    const codexItems = [];
+
+    // 1. Model submenu
+    codexItems.push({
+      label: 'Model',
+      icon: '&#129504;',
+      hint: codexSettings.model || 'default',
+      submenu: MODEL_OPTIONS.map(opt => ({
+        label: opt.label,
+        action: () => putSettings({ model: opt.id }),
+        check: codexSettings.model === opt.id,
+      })),
+    });
+
+    // 2. Sandbox submenu
+    codexItems.push({
+      label: 'Sandbox',
+      icon: '&#128274;',
+      hint: codexSettings.sandbox || 'default',
+      submenu: SANDBOX_OPTIONS.map(opt => ({
+        label: opt.label,
+        action: () => putSettings({ sandbox: opt.id }),
+        check: codexSettings.sandbox === opt.id,
+        danger: opt.id === 'danger-full-access',
+      })),
+    });
+
+    // 3. Approval Policy submenu
+    codexItems.push({
+      label: 'Approval Policy',
+      icon: '&#9989;',
+      hint: codexSettings.approvalPolicy || 'default',
+      submenu: APPROVAL_OPTIONS.map(opt => ({
+        label: opt.label,
+        action: () => putSettings({ approvalPolicy: opt.id }),
+        check: codexSettings.approvalPolicy === opt.id,
+        danger: opt.id === 'never',
+      })),
+    });
+
+    // 4. Reasoning Effort submenu
+    codexItems.push({
+      label: 'Reasoning Effort',
+      icon: '&#128173;',
+      hint: codexSettings.reasoningEffort || 'default',
+      submenu: EFFORT_OPTIONS.map(opt => ({
+        label: opt.label,
+        action: () => putSettings({ reasoningEffort: opt.id }),
+        check: codexSettings.reasoningEffort === opt.id,
+      })),
+    });
+
+    // 5. Bypass toggle with confirmation modal
+    const isBypassOn = codexSettings.bypassApprovalsAndSandbox === true;
+    codexItems.push({
+      label: isBypassOn ? 'Bypass: ON (click to disable)' : 'Bypass Approvals & Sandbox',
+      icon: '&#9888;',
+      danger: true,
+      check: isBypassOn,
+      action: async () => {
+        if (isBypassOn) {
+          // Turning OFF a dangerous flag is safe; no confirmation needed.
+          await putSettings({ bypassApprovalsAndSandbox: false });
+          return;
+        }
+        // Turning ON: require explicit confirmation. The bypass flag
+        // disables BOTH the approval workflow AND the sandbox, so the
+        // session can read/write/exec anything the user can. Worth a
+        // second click before flipping.
+        const confirmed = await this.showConfirmModal({
+          title: 'Enable Bypass for Codex?',
+          message: 'This disables BOTH the approval workflow AND the sandbox for this Codex session. The session can read/write/execute anything you can. Continue?',
+          confirmText: 'Enable Bypass',
+          confirmClass: 'btn-danger',
+        });
+        if (confirmed) {
+          await putSettings({ bypassApprovalsAndSandbox: true });
+        }
+      },
+    });
+
+    // 6. Features submenu (multi-select via per-item toggle)
+    const activeFeatures = Array.isArray(codexSettings.features) ? codexSettings.features : [];
+    codexItems.push({
+      label: 'Features',
+      icon: '&#9881;',
+      hint: activeFeatures.length ? activeFeatures.join(', ') : 'none',
+      submenu: FEATURE_OPTIONS.map(opt => ({
+        label: opt.label,
+        action: () => {
+          const next = activeFeatures.includes(opt.id)
+            ? activeFeatures.filter(f => f !== opt.id)
+            : [...activeFeatures, opt.id];
+          putSettings({ features: next });
+        },
+        check: activeFeatures.includes(opt.id),
+      })),
+    });
+
+    return codexItems;
+  }
+
   showTerminalContextMenu(slotIdx, x, y) {
     const tp = this.terminalPanes[slotIdx];
     if (!tp) return;
@@ -11556,6 +11738,21 @@ class CWMApp {
       });
     }
 
+    // ── Provider-specific submenu (Plan 21-01) ────────────────
+    // Dispatch by data-provider on the pane element. The Codex pane gets
+    // a "Codex settings" submenu with model/sandbox/approval/effort/bypass/
+    // features; Claude panes get nothing here and fall through unchanged.
+    const paneElForProvider = document.getElementById(`term-pane-${slotIdx}`);
+    const paneProvider = paneElForProvider && paneElForProvider.dataset && paneElForProvider.dataset.provider;
+    if (paneProvider === 'codex') { // gsd:provider-literal-allowed (per-provider dispatch)
+      items.push({ type: 'sep' });
+      items.push({
+        label: 'Codex settings',
+        icon: '&#129504;',
+        submenu: this._buildCodexPaneMenu(slotIdx, tp),
+      });
+    }
+
     // ── Pane management ───────────────────────────────────────
     items.push({ type: 'sep' });
 

package/src/web/public/styles.css

@@ -10224,13 +10224,25 @@ html {
    fades to transparent before reaching the xterm canvas; the xterm
    canvas paints over the pane background, so text contrast is never
    reduced by the tint (Pitfall F mitigation). */
+/* Per-design 2026-05-11: pane-provider visual treatment bumped to be
+   noticeable at-a-glance for mixed-provider grids. Combines a 3px solid
+   accent strip at top (was 1px), a deeper top-fade tint (was 24px), and
+   a 2px bottom accent. Whole-pane subtle background tint via color-mix
+   (12% saturation) sits BEHIND the xterm canvas; xterm paints opaque
+   over its own area so text contrast is never reduced (Pitfall F). */
 .terminal-pane[data-provider="claude"]:not(.terminal-pane-empty) {
-  border-top: 1px solid var(--provider-claude-accent);
-  background: linear-gradient(180deg, var(--provider-claude-tint) 0, transparent 24px), var(--bg-primary);
+  border-top: 3px solid var(--provider-claude-accent);
+  border-bottom: 2px solid var(--provider-claude-accent);
+  background:
+    linear-gradient(180deg, var(--provider-claude-tint) 0, transparent 64px),
+    color-mix(in srgb, var(--mauve) 4%, var(--bg-primary));
 }
 .terminal-pane[data-provider="codex"]:not(.terminal-pane-empty) {
-  border-top: 1px solid var(--provider-codex-accent);
-  background: linear-gradient(180deg, var(--provider-codex-tint) 0, transparent 24px), var(--bg-primary);
+  border-top: 3px solid var(--provider-codex-accent);
+  border-bottom: 2px solid var(--provider-codex-accent);
+  background:
+    linear-gradient(180deg, var(--provider-codex-tint) 0, transparent 64px),
+    color-mix(in srgb, var(--green) 4%, var(--bg-primary));
 }
 
 /* 2px provider stripe on the left edge of the project accordion. */

package/src/web/server.js

@@ -1503,6 +1503,110 @@ app.delete('/api/sessions/:id', requireAuth, (req, res) => {
   return res.json({ success: true });
 });
 
+/**
+ * PUT /api/sessions/:id/provider-settings
+ *
+ * Phase 21 Plan 21-01: persist per-session provider settings.
+ *
+ * Request body: { settings: { ...providerSpecificFields } }
+ *   For Codex sessions, accepted keys are: model, sandbox, approvalPolicy,
+ *   reasoningEffort, bypassApprovalsAndSandbox, features.
+ *
+ * Validation:
+ *   - 404 if session id is unknown
+ *   - 400 if body.settings is not a plain object
+ *   - 400 if any key is unknown or its value fails the per-key allow-list
+ *   - 400 if a free-form string value contains shell-unsafe characters
+ *
+ * Response: 200 with the canonical persisted bundle.
+ *
+ * Note: pty-manager re-reads providerSettings from the store on every
+ * spawn, so a setting change takes effect the next time the pane is
+ * (re)started. The frontend surfaces a toast hint after a successful PUT.
+ */
+const CODEX_SANDBOX_VALUES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
+const CODEX_APPROVAL_VALUES = new Set(['untrusted', 'on-failure', 'on-request', 'never']);
+const CODEX_EFFORT_VALUES = new Set(['minimal', 'low', 'medium', 'high']);
+const CODEX_FEATURE_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+const CODEX_MODEL_ID_RE = /^[a-zA-Z0-9._:-]{1,128}$/;
+const CODEX_ALLOWED_KEYS = new Set([
+  'model', 'sandbox', 'approvalPolicy', 'reasoningEffort',
+  'bypassApprovalsAndSandbox', 'features',
+]);
+
+function validateCodexProviderSettings(settings) {
+  if (settings === null || typeof settings !== 'object' || Array.isArray(settings)) {
+    return { ok: false, error: 'settings must be a plain object' };
+  }
+  for (const key of Object.keys(settings)) {
+    if (!CODEX_ALLOWED_KEYS.has(key)) {
+      return { ok: false, error: 'unknown setting key: ' + key };
+    }
+  }
+  if (settings.model !== undefined) {
+    if (typeof settings.model !== 'string' || !CODEX_MODEL_ID_RE.test(settings.model) || SHELL_UNSAFE.test(settings.model)) {
+      return { ok: false, error: 'invalid model id' };
+    }
+  }
+  if (settings.sandbox !== undefined && !CODEX_SANDBOX_VALUES.has(settings.sandbox)) {
+    return { ok: false, error: 'invalid sandbox value' };
+  }
+  if (settings.approvalPolicy !== undefined && !CODEX_APPROVAL_VALUES.has(settings.approvalPolicy)) {
+    return { ok: false, error: 'invalid approvalPolicy value' };
+  }
+  if (settings.reasoningEffort !== undefined && !CODEX_EFFORT_VALUES.has(settings.reasoningEffort)) {
+    return { ok: false, error: 'invalid reasoningEffort value' };
+  }
+  if (settings.bypassApprovalsAndSandbox !== undefined && typeof settings.bypassApprovalsAndSandbox !== 'boolean') {
+    return { ok: false, error: 'bypassApprovalsAndSandbox must be boolean' };
+  }
+  if (settings.features !== undefined) {
+    if (!Array.isArray(settings.features)) {
+      return { ok: false, error: 'features must be an array' };
+    }
+    for (const name of settings.features) {
+      if (typeof name !== 'string' || !CODEX_FEATURE_NAME_RE.test(name) || SHELL_UNSAFE.test(name)) {
+        return { ok: false, error: 'invalid feature name: ' + name };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+app.put('/api/sessions/:id/provider-settings', requireAuth, (req, res) => {
+  const store = getStore();
+  const sessionId = req.params.id;
+  const session = store.getSession(sessionId);
+  if (!session) {
+    return res.status(404).json({ error: 'Session not found.' });
+  }
+  const settings = req.body && req.body.settings;
+  if (settings === undefined || settings === null || typeof settings !== 'object' || Array.isArray(settings)) {
+    return res.status(400).json({ error: 'settings must be a plain object' });
+  }
+  const providerId = session.provider || 'claude'; // gsd:provider-literal-allowed (back-compat default; tag for un-tagged legacy sessions)
+  // Per-provider validation. Today only Codex has a settings surface; Claude
+  // gets a 400 until a future plan defines its bundle shape.
+  if (providerId === 'codex') { // gsd:provider-literal-allowed
+    const check = validateCodexProviderSettings(settings);
+    if (!check.ok) {
+      return res.status(400).json({ error: check.error });
+    }
+  } else {
+    return res.status(400).json({ error: 'provider does not accept provider-settings: ' + providerId });
+  }
+  const updated = store.updateSessionProviderSettings(sessionId, providerId, settings);
+  if (!updated) {
+    return res.status(404).json({ error: 'Session not found.' });
+  }
+  return res.json({
+    success: true,
+    sessionId,
+    provider: providerId,
+    settings: updated.providerSettings[providerId],
+  });
+});
+
 /**
  * POST /api/sessions/:id/start
  * Launch the session process and mark it as recently used.