SIGN IN SIGN UP

Phase 10.5: unify ClaudeAgentSession lifecycle, retire ClaudeMaterializer (#317884)

* Phase 10.5: unify ClaudeAgentSession lifecycle, retire ClaudeMaterializer

Collapse the dual-map session lifecycle (`_provisionalSessions` +
`_sessions`) onto a single `ClaudeAgentSession` identity per `sessionId`.
The session now owns its full materialize flow (SDK startup, abort gates,
DB ref open, pipeline construction, rematerializer attach, metadata
overlay write, bijective state seed). `ClaudeMaterializer` is gone; its
pure helpers (`buildOptions`, `buildClientMcpServers`,
`buildSubprocessEnv`) live in a new `claudeSdkOptions.ts` module.

Why
- Phase 10's race regressions (C1, C1-resume, S1) were all compensation
  for the dual-map split. With one object identity per session, the
  fixes become structurally trivial and the compensation paths delete.
- `_materializeProvisional` and `_resumeSession` were ~80-line
  orchestrators trying to be methods on the session entity \u2014 now they
  are: build canUseTool + delegate to `session.materialize(ctx)`, then
  fire the public materialize event.

Behavior preserved
- `IAgent` provider surface unchanged.
- Phase 10 race regression tests still cover the same races
  (materialize gap, resume bootstrap gap, rebind failure leaves diff
  dirty).
- Resume path explicitly skips the overlay write (overlay is the SOURCE
  on resume); new test guards this.

`changeModel` simplified
- `session.setModel(model)` is now the single mutation entry. It stashes
  provisional state when no pipeline exists, queues runtime model+effort
  with the 'max'->'xhigh' clamp when materialized, and writes the
  metadata overlay in both cases. Agent's `changeModel` collapses to a
  sequencer + delegation.

Tests
- 1810/1810 agentHost unit suite passing.
- 7/7 real Claude SDK integration tests passing (2 pre-existing pending).
- Live workbench E2E: full tool-call round-trip end-to-end
  (createSession -> setClientTools(13 tools) -> materialize ->
  openBrowserPage request -> workbench permission UI -> approve ->
  workbench opens https://example.com -> tool_result returned ->
  session.result). 0 occurrences of legacy failure patterns.

Plan + roadmap
- Roadmap Phase 10.5 marked DONE.
- Full plan at src/vs/platform/agentHost/node/claude/phase10.5-plan.md.

* Address PR review: fix stale setModel link + document buildOptions ambient env reads
T
Tyler James Leonhardt committed
336d4b28ca977292c84bd7db1f9150bcd34311e4
Parent: cc5fe93
Committed by GitHub <noreply@github.com> on 5/21/2026, 11:49:34 PM