feat(native-chat): open structured chat's wire and stored records to registered agents, behind a negotiated capability

src/main/claude/claude-structured-acquire-catalog.ts

@@ -0,0 +1,11 @@
+import { agentModelCatalogSessionAccess } from '../native-chat/agent-model-catalog/agent-model-catalog-fingerprint'
+import type { AgentModelCatalogStore } from '../native-chat/agent-model-catalog/agent-model-catalog-store'
+import { CLAUDE_STRUCTURED_AGENT } from './claude-structured-agent-definition'
+
+/** A Claude session's catalog, keyed by the config directory it launched under. */
+export function claudeAcquireCatalogAccess(
+  store: AgentModelCatalogStore | undefined,
+  claudeConfigDir: string | null
+) {
+  return agentModelCatalogSessionAccess(store, CLAUDE_STRUCTURED_AGENT, claudeConfigDir)
+}

src/main/claude/claude-structured-agent-definition.ts

@@ -1,9 +1,12 @@
 import type { StructuredAgentDefinition } from '../native-chat/agent-session-wire/structured-agent-definition'
+import { CLAUDE_STRUCTURED_HANDLE_NAMESPACE } from '../../shared/agent-session-provider-handle-encoding'
 import { isClaudeStructuredOptionKey } from './claude-structured-options'
 import { claudeFallbackModelOptions } from './claude-structured-session-options'
 
 export const CLAUDE_STRUCTURED_AGENT: StructuredAgentDefinition = {
   agent: 'claude',
+  handleTransport: CLAUDE_STRUCTURED_HANDLE_NAMESPACE.transport,
+  accountHomeVariable: 'CLAUDE_CONFIG_DIR',
   capabilities: {
     // Orca's marker-based rewind proof can never pass on the real binary; rewind returns via a fork.
     rewind: false,

src/main/claude/claude-structured-effort-default-at-rest.test.ts

@@ -144,6 +144,7 @@ function readAtRest(store: AgentModelCatalogStore, record: AgentSessionRecord) {
   const modelCatalog = createAgentModelCatalogService({
     store,
     getRecord: () => record,
+    drivesRecord: () => true,
     resolveAccountHome: async () => ({ variable: 'CLAUDE_CONFIG_DIR', path: ACCOUNT_HOME })
   })
   const resting = {

src/main/claude/claude-structured-launch-resolution.ts

@@ -34,7 +34,7 @@ import { resolveClaudeCommand } from '../codex-cli/command'
 import { resolveSessionFilePath } from '../native-chat/session-file-resolver'
 import { withoutInheritedClaudeConfigDir } from './claude-config-dir-pin'
 import type { AgentSessionRecordStore } from '../runtime/agent-session-record-store'
-import { agentConfigDirectoryVariable } from '../../shared/agent-session-account-home'
+import { CLAUDE_STRUCTURED_AGENT } from './claude-structured-agent-definition'
 
 export const CLAUDE_DEFAULT_SETTING_SOURCES = ['user', 'project', 'local'] as const
 export const CLAUDE_SESSION_STATE_EVENTS_ENV = 'CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS'
@@ -251,7 +251,7 @@ export function createClaudeStructuredLaunchResolver(
         `claude structured sessions run on the local host, not ${record.location.executionHostId}`
       )
     }
-    const pinned = agentConfigDirectoryVariable('claude')
+    const pinned = CLAUDE_STRUCTURED_AGENT.accountHomeVariable
     if (record.accountHome.variable !== pinned) {
       throw new Error(`claude sessions pin ${pinned}, not ${record.accountHome.variable}`)
     }
@@ -266,7 +266,7 @@ export function createClaudeStructuredLaunchResolver(
         gate && hasWslBoundClaudeAccount(gate) ? { reason: 'managedAccountUnsupported' } : {}
       )
     }
-    // A Claude record's chain holds only Claude handles; the record store refuses anything else.
+    // A Claude record's chain holds only Claude handles; the attach admission refuses anything else.
     const head = agentSessionProviderHandleChainHead(record.providerHandleChain)?.handle ?? null
     if (
       head &&

src/main/claude/claude-structured-session-acquisition.ts

@@ -41,7 +41,7 @@ import { readClaudeTranscriptEntryUuid } from './claude-transcript-entry-uuid'
 import { persistClaudeTurnResumePoint } from './claude-structured-resume-point'
 import { withAgentSessionCreatePhase } from '../observability/agent-session-instrumentation'
 import { resolveClaudeAcquisitionLaunch } from './claude-structured-acquisition-launch'
-import { agentModelCatalogSessionAccess } from '../native-chat/agent-model-catalog/agent-model-catalog-fingerprint'
+import { claudeAcquireCatalogAccess } from './claude-structured-acquire-catalog'
 import {
   bindClaudeConnectionJournalControls,
   createClaudeJournalFailureHandler
@@ -257,11 +257,7 @@ export async function acquireClaudeSession({
     })
     const session = publication.session
     liveSession = session
-    const catalogAccess = agentModelCatalogSessionAccess(
-      deps.modelCatalog,
-      'claude',
-      launch.claudeConfigDir
-    )
+    const catalogAccess = claudeAcquireCatalogAccess(deps.modelCatalog, launch.claudeConfigDir)
     if (catalogAccess) {
       session.catalogAccess = catalogAccess
     }

src/main/codex/codex-structured-acquire-catalog.ts

@@ -11,12 +11,13 @@ import {
   type CodexSessionOptionCatalog
 } from './codex-structured-model-catalog'
 import { agentModelCatalogSessionAccess } from '../native-chat/agent-model-catalog/agent-model-catalog-fingerprint'
+import { CODEX_STRUCTURED_AGENT } from './codex-structured-agent-definition'
 
 export function codexAcquireCatalogAccess(
   deps: Pick<CodexStructuredSessionAdapterDeps, 'modelCatalog'>,
   launch: Pick<CodexStructuredLaunch, 'codexHome'>
 ): CodexSessionCatalogAccess | undefined {
-  return agentModelCatalogSessionAccess(deps.modelCatalog, 'codex', launch.codexHome)
+  return agentModelCatalogSessionAccess(deps.modelCatalog, CODEX_STRUCTURED_AGENT, launch.codexHome)
 }
 
 /** The one catalog read a fast-mode restore needs, store-first. Null degrades

src/main/codex/codex-structured-agent-definition.ts

@@ -1,8 +1,11 @@
 import type { StructuredAgentDefinition } from '../native-chat/agent-session-wire/structured-agent-definition'
+import { CODEX_STRUCTURED_HANDLE_NAMESPACE } from '../../shared/agent-session-provider-handle-encoding'
 import { isCodexTurnOptionKey } from './codex-structured-turn-start'
 
 export const CODEX_STRUCTURED_AGENT: StructuredAgentDefinition = {
   agent: 'codex',
+  handleTransport: CODEX_STRUCTURED_HANDLE_NAMESPACE.transport,
+  accountHomeVariable: 'CODEX_HOME',
   capabilities: {
     // A thread with legacy, unpaginated history narrows this to unsupported once it runs.
     rewind: true,

src/main/codex/codex-structured-launch-resolution.ts

@@ -15,7 +15,7 @@ import type { CodexStructuredLaunch } from './codex-structured-session-adapter'
 import type { CodexStructuredPermissionPolicy } from './codex-structured-permission-policy'
 import { resolvePinnedCodexRolloutProof } from './codex-pinned-rollout-proof'
 import { isWindowsProcessStartTimeAvailable } from '../windows/windows-process-table'
-import { agentConfigDirectoryVariable } from '../../shared/agent-session-account-home'
+import { CODEX_STRUCTURED_AGENT } from './codex-structured-agent-definition'
 
 export type CodexStructuredLaunchResolverDeps = {
   store: AgentSessionRecordStore
@@ -86,7 +86,7 @@ export function createCodexStructuredLaunchResolver(
     ) {
       throw new Error('codex structured sessions require Windows process creation-time proof')
     }
-    const pinned = agentConfigDirectoryVariable('codex')
+    const pinned = CODEX_STRUCTURED_AGENT.accountHomeVariable
     if (accountHome.variable !== pinned) {
       throw new Error(`codex sessions pin ${pinned}, not ${accountHome.variable}`)
     }
@@ -95,7 +95,7 @@ export function createCodexStructuredLaunchResolver(
     // concern, and the permission posture they used to smuggle in is derived per acquisition.
     const permissionPolicy = deps.resolvePermissionPolicy?.()
     const head = agentSessionProviderHandleChainHead(record.providerHandleChain)
-    // A Codex record's chain holds only Codex handles; the record store refuses anything else.
+    // A Codex record's chain holds only Codex handles; the attach admission refuses anything else.
     const resumeThreadId = head?.handle.nativeId ?? null
     // The same saved options every turn sends, so the thread and its turns name one model.
     const model = record.options?.model

src/main/codex/codex-structured-session-options-catalog.test.ts

@@ -130,6 +130,7 @@ describe('Codex session options through the host catalog store', () => {
     const service = createAgentModelCatalogService({
       store,
       getRecord: () => undefined,
+      drivesRecord: () => true,
       resolveAccountHome: async () => ({ variable: 'CODEX_HOME', path: '/homes/a' }),
       probes: { codex: hungProbe }
     })

src/main/native-chat/agent-model-catalog/agent-model-catalog-fingerprint.ts

@@ -4,8 +4,7 @@ import type {
   AgentModelCatalogSessionAccess,
   AgentModelCatalogStore
 } from './agent-model-catalog-store'
-import { agentConfigDirectoryVariable } from '../../../shared/agent-session-account-home'
-import type { AgentSessionHandleProvider } from '../../../shared/agent-session-provider-handle'
+import type { AgentSessionStoredAgent } from '../../../shared/agent-session-stored-agent'
 
 /**
  * Everything that changes which models a listing can answer with: the agent,
@@ -14,7 +13,7 @@ import type { AgentSessionHandleProvider } from '../../../shared/agent-session-p
  * key is corrected by the next refresh, never by the fingerprint.
  */
 export type AgentModelCatalogIdentity = {
-  agent: 'claude' | 'codex'
+  agent: string
   accountHomeVariable: string
   accountHomePath: string
   /** Null on the native host; WSL distros each carry their own CLI. */
@@ -57,7 +56,7 @@ export function agentModelCatalogFingerprintForRecord(
  *  Native only: both structured adapters refuse non-native locations at launch. */
 export function agentModelCatalogSessionAccess(
   store: AgentModelCatalogStore | undefined,
-  agent: AgentSessionHandleProvider,
+  agent: Pick<AgentSessionStoredAgent, 'agent' | 'accountHomeVariable'>,
   accountHomePath: string | null
 ): AgentModelCatalogSessionAccess | undefined {
   if (!store || !accountHomePath) {
@@ -66,8 +65,8 @@ export function agentModelCatalogSessionAccess(
   return {
     store,
     fingerprint: agentModelCatalogFingerprint({
-      agent,
-      accountHomeVariable: agentConfigDirectoryVariable(agent),
+      agent: agent.agent,
+      accountHomeVariable: agent.accountHomeVariable,
       accountHomePath,
       wslDistro: null
     }),

src/main/native-chat/agent-model-catalog/agent-model-catalog-persistence.ts

@@ -5,6 +5,7 @@ import type {
   AgentSessionOptionChoice
 } from '../../../shared/agent-session-wire'
 import type { AgentModelCatalogEntry } from './agent-model-catalog-store'
+import { isStructuredAgentId } from '../../../shared/agent-session-provider-handle-encoding'
 
 const SCHEMA_VERSION = 1
 const SAVE_COALESCE_MS = 500
@@ -67,7 +68,7 @@ function parseEntry(value: unknown): AgentModelCatalogEntry | null {
   const row = asRecord(value)
   if (
     !row ||
-    (row.agent !== 'claude' && row.agent !== 'codex') ||
+    !isStructuredAgentId(row.agent) ||
     typeof row.fingerprint !== 'string' ||
     (row.origin !== 'live-session' && row.origin !== 'probe') ||
     typeof row.fetchedAt !== 'number' ||

src/main/native-chat/agent-model-catalog/agent-model-catalog-service.test.ts

@@ -55,6 +55,7 @@ describe('agent model catalog service', () => {
     const service = createAgentModelCatalogService({
       store,
       getRecord: () => record('/homes/a'),
+      drivesRecord: () => true,
       resolveAccountHome: async () => CODEX_HOME('/homes/selected'),
       probes: { codex: probe }
     })
@@ -73,6 +74,26 @@ describe('agent model catalog service', () => {
     })
   })
 
+  it('probes as for no record when this build cannot start the record as it is pinned', async () => {
+    const store = new AgentModelCatalogStore()
+    const probe = vi.fn(async (_home: string) => listing('gpt-a'))
+    // A Codex record pinning Claude's variable: its path is not a Codex home to probe under.
+    const pinned = { ...record('/x'), accountHome: { variable: 'CLAUDE_CONFIG_DIR', path: '/x' } }
+    const drivesRecord = vi.fn(() => false)
+    const service = createAgentModelCatalogService({
+      store,
+      getRecord: () => pinned,
+      drivesRecord,
+      resolveAccountHome: async () => CODEX_HOME('/homes/selected'),
+      probes: { codex: probe }
+    })
+
+    await service.read({ agent: 'codex', sessionId: 'session-1' })
+
+    expect(drivesRecord).toHaveBeenCalledWith(pinned)
+    expect(probe).toHaveBeenCalledExactlyOnceWith('/homes/selected')
+  })
+
   it('an account switch with no record reads and prewarms the NEW account, never the old entry', async () => {
     const store = new AgentModelCatalogStore()
     // The old account listed under its own fingerprint before the switch.
@@ -82,6 +103,7 @@ describe('agent model catalog service', () => {
     const service = createAgentModelCatalogService({
       store,
       getRecord: () => undefined,
+      drivesRecord: () => true,
       resolveAccountHome: async () => CODEX_HOME('/homes/new'),
       probes: { codex: probe }
     })
@@ -107,6 +129,7 @@ describe('agent model catalog service', () => {
     const service = createAgentModelCatalogService({
       store,
       getRecord: () => undefined,
+      drivesRecord: () => true,
       resolveAccountHome: async () => CODEX_HOME('/homes/selected')
     })
     const result = await service.read({ agent: 'codex' })
@@ -129,6 +152,7 @@ describe('agent model catalog service', () => {
     const service = createAgentModelCatalogService({
       store,
       getRecord: () => sessionRecord,
+      drivesRecord: () => true,
       resolveAccountHome: async () => CODEX_HOME('/homes/selected')
     })
     const result = await service.read({ agent: 'codex', sessionId: 'session-1' })
@@ -143,6 +167,7 @@ describe('agent model catalog service', () => {
     const service = createAgentModelCatalogService({
       store,
       getRecord: () => record('/homes/a'),
+      drivesRecord: () => true,
       resolveAccountHome: async () => CODEX_HOME('/homes/a'),
       probes: { codex: probe }
     })
@@ -164,6 +189,7 @@ describe('agent model catalog service', () => {
     const service = createAgentModelCatalogService({
       store,
       getRecord: () => undefined,
+      drivesRecord: () => true,
       resolveAccountHome: async () => {
         throw new Error('no store yet')
       },
@@ -189,6 +215,7 @@ describe('agent model catalog service', () => {
       const service = createAgentModelCatalogService({
         store,
         getRecord: () => undefined,
+        drivesRecord: () => true,
         resolveAccountHome: async () => CODEX_HOME('/homes/selected'),
         probes: { codex: probe }
       })
@@ -385,6 +412,7 @@ describe('agent model catalog service', () => {
       const service = createAgentModelCatalogService({
         store,
         getRecord: () => undefined,
+        drivesRecord: () => true,
         resolveAccountHome: async () => CODEX_HOME('/homes/selected')
       })
       expect(await service.read({ agent: 'codex', waitForListing: true })).toEqual({
@@ -401,6 +429,7 @@ describe('agent model catalog service', () => {
       const service = createAgentModelCatalogService({
         store,
         getRecord: () => undefined,
+        drivesRecord: () => true,
         resolveAccountHome: async () => CODEX_HOME('/homes/selected'),
         probes: { codex: probe }
       })
@@ -418,6 +447,7 @@ describe('agent model catalog service', () => {
       const service = createAgentModelCatalogService({
         store,
         getRecord: () => undefined,
+        drivesRecord: () => true,
         resolveAccountHome: async () => CODEX_HOME('/homes/selected'),
         workspaceMayOverrideDefaultModel
       })

src/main/native-chat/agent-model-catalog/agent-model-catalog-service.ts

@@ -3,7 +3,6 @@ import type {
   AgentSessionAccountHome,
   AgentSessionRecord
 } from '../../../shared/agent-session-record'
-import type { AgentSessionHandleProvider } from '../../../shared/agent-session-provider-handle'
 import {
   agentModelCatalogFingerprint,
   agentModelCatalogFingerprintForRecord
@@ -17,23 +16,26 @@ import type {
 export type AgentModelCatalogServiceDeps = {
   store: AgentModelCatalogStore
   getRecord: (sessionId: string) => AgentSessionRecord | undefined
+  /** Whether this build can start the record's agent as the record pins it; a record it cannot
+   *  names no account a probe may start that agent's CLI under. */
+  drivesRecord: (record: AgentSessionRecord) => boolean
   /** The account home a structured launch for this agent would pin right now —
    *  the SAME resolver the create path fills `record.accountHome` with, so a
    *  record-less read can never answer from another account's listing. */
-  resolveAccountHome: (agent: AgentSessionHandleProvider) => Promise<AgentSessionAccountHome>
+  resolveAccountHome: (agent: string) => Promise<AgentSessionAccountHome>
   /** Session-less listers, one per agent that has one on this host. */
-  probes?: Partial<Record<'claude' | 'codex', AgentModelCatalogProbe>>
+  probes?: Readonly<Partial<Record<string, AgentModelCatalogProbe>>>
   /** Whether the workspace's own config could pick a model other than the listed default. */
   workspaceMayOverrideDefaultModel?: (input: {
-    agent: 'claude' | 'codex'
+    agent: string
     workspacePath: string
     accountHomePath: string
   }) => Promise<boolean>
 }
 
 export type AgentModelCatalogService = {
   read: (params: {
-    agent: 'claude' | 'codex'
+    agent: string
     sessionId?: string
     /** Where a new chat would run; null when one was named but is not a local directory. */
     workspacePath?: string | null
@@ -60,7 +62,7 @@ function resultFromEntry(
 /** A named workspace keeps the listed default only when none of its own config can replace it. */
 async function workspaceKeepsListedDefault(
   deps: AgentModelCatalogServiceDeps,
-  agent: 'claude' | 'codex',
+  agent: string,
   workspacePath: string | null | undefined,
   accountHomePath: string | null
 ): Promise<boolean> {
@@ -93,7 +95,8 @@ export function createAgentModelCatalogService(
   return {
     async read(params) {
       const record = params.sessionId ? deps.getRecord(params.sessionId) : undefined
-      const scoped = record && record.provider === params.agent ? record : undefined
+      const scoped =
+        record && record.provider === params.agent && deps.drivesRecord(record) ? record : undefined
       let fingerprint: string
       let accountHomePath: string | null
       if (scoped) {