feat(agent): add subagent model setting

[charlesvien]

Problem

Subagents inherit the main session model, which defaults to Opus (claude-opus-4-8). A dynamic-workflow research fan-out of 30+ agents runs entirely on the most expensive tier, and there is no setting anywhere in the product to change that. The only exception today is the hardcoded ph-explore agent pinned to sonnet.

Changes

• buildSessionOptions injects CLAUDE_CODE_SUBAGENT_MODEL into every spawned Claude CLI env. The CLI applies it as a hard override for all subagents, including dynamic-workflow agent() fan-outs. Resolution order at spawn: a hand-written env entry in the merged .claude/settings.json layers (read only, never written; mirrors how the settings model beats the session meta model), then the host-provided app setting, then a pre-set process env var (cloud orchestrator or shell), then the new DEFAULT_SUBAGENT_MODEL = "sonnet".
• The preference is stored in the app's own settings store: a subagentModel key in the electron-store settings behind IWorkspaceSettings (same home as worktree location and auto-suspend). Nothing writes to Claude settings files.
• AgentService reads the stored value and threads it into session _meta as subagentModel on all three start paths (new, resume, imported), the same channel the main model uses, so new and reconnected sessions pick up changes.
• agent.getSubagentModel / agent.setSubagentModel tRPC procedures forward to AgentService, which forwards to IWorkspaceSettings.
• Settings > Claude Code gets a "Models" section with a "Subagent model" select: "Sonnet (default)", "Inherit main model" and the gateway catalog (GLM-flag filtered like the session picker). Optimistic update with rollback on error. The stored value is the raw gateway id; conversion to a CLI alias happens once at spawn via toSdkModelId.

Notes:

• The bundled CLI (2.1.170) supports the env var (present in the binary). It predates the 2.1.196 inherit semantics change, so "Inherit main model" forces subagents onto the main model rather than restoring per-agent frontmatter. That matches the UI label; ph-explore follows the main model in inherit mode until the CLI is bumped.
• Cloud sandboxes get the sonnet default automatically (shared options builder) and respect an orchestrator-provided process env var, but the desktop setting does not propagate to cloud tasks. Follow-up: a POSTHOG_CODE_SUBAGENT_MODEL task-run field in the backend. Interim escape hatch: the Sandbox Environments environment variables field.
• The availableModels allowlist only gates the human-facing pickers, not this env var. Documented, not enforced, in v1.

How did you test this?

• pnpm --filter @posthog/agent test: 836 passed, including cases for the spawn resolution order (settings env > host-provided setting > process env > default), the gateway-id-to-alias it.each mapping and the user-layer env merge into SettingsManager.
• pnpm --filter @posthog/workspace-server test: 597 passed, including AgentService.getSubagentModel/setSubagentModel forwarding to IWorkspaceSettings and _meta.subagentModel threading (present when set, absent when unset).
• pnpm --filter @posthog/ui component tests: 8 cases for SubagentModelSetting (default/inherit/catalog display, raw-value fallback, disabled while loading and mutating, error text, missing catalog).
• pnpm typecheck (22 tasks), biome lint on all touched files and node scripts/check-host-boundaries.mjs (no new violations).
• Verified CLAUDE_CODE_SUBAGENT_MODEL appears in the bundled 2.1.170 CLI binary.
• Not run: a live desktop session driving a real subagent end to end (needs a signed-in app; flagged for manual verification).

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

[github-actions]

React Doctor found no issues in the changed files. 🎉

_{Reviewed by React Doctor for commit 9a06e92.}

[greptile-apps]

_{Reviews (1): Last reviewed commit: "add subagent model setting" | Re-trigger Greptile}

[stamphog]

Gates denied this PR because it modifies package exports (deps_toolchain gate) and exceeds the T1 complexity threshold. Request a human review from a team member before re-requesting auto-approval.

[stamphog]

Gates denied this PR because it modifies package dependencies/exports (deps_toolchain gate) and exceeds the complexity ceiling for auto-review. This needs a human reviewer — request a review from a team member before re-requesting auto-approval.

[greptile-apps]

_{Reviews (2): Last reviewed commit: "store subagent model in app settings" | Re-trigger Greptile}