agentHost/claude: Phase 6.1 — auth, model config, mapper, lifecycle, doc alignment#315136
Merged
Conversation
…doc alignment Phase 6.1 lands the architectural follow-ups identified after Phase 6's sendMessage shipped. Eight tightly-scoped cycles (A–G) plus a stateless-mapper cleanup, all backed by an exhaustive M1–M13 mapping of the IAgent ↔ Claude SDK surface in CONTEXT.md. Cycle summary ------------- - A: CONTEXT.md mapping doc — the M1–M13 portrait of IAgent ↔ Claude SDK. - B: Auth — `createSession` / `_materializeProvisional` throw `ProtocolError(AHP_AUTH_REQUIRED, …, getProtectedResources())` instead of a plain `Error`, so the workbench surfaces the sign-in flow (mirrors `copilotAgent.ts:382-385`). - C: Turn.id = SDK uuid invariant — the host yields `SDKUserMessage.uuid = effectiveTurnId`, single-namespace contract documented as a glossary entry. - D: `getSessionMetadata?` per-session lookup; `listSessions` overlay read refactored onto `_readSessionMetadata`. - E: Permission-mode enum widened from 4-value to 6-value canonical (adds `dontAsk`, `auto`); `Options.model` / `Options.permissionMode` / effort flow through to the first `query()`; `_writeSessionMetadata` persists model + permission mode alongside the customization-directory key. - F: Mapper widening — `'assistant'` is canonical at the SDK seam, with reconciliation against `stream_event` partials so deltas + final message no longer double-emit. `tool_use` blocks on the canonical envelope warn through defense-in-depth instead of silently leaking. - E2/E5/E6 + C2: `IClaudeModelConfig` (`createClaudeThinkingLevelSchema`, `isClaudeEffortLevel`, `resolveClaudeEffort`) — pulled out as a stateless helper so the mapper / agent / model picker share one effort-level vocabulary. - G: Doc-alignment pass on `roadmap.md`, `phase5-plan.md`, `phase6-plan.md` driven by a 3-reviewer council pass. Resolves 10 drift items (see CONTEXT `ai-customization` / Phase 6.1 plan §"Cycle G — Stale phase-plan + roadmap refresh"); CONTEXT.md is the truth oracle and is unchanged. Files ----- - New helpers + tests: `src/vs/platform/agentHost/common/claudeModelConfig.ts`, `src/vs/platform/agentHost/test/common/claudeModelConfig.test.ts`, `src/vs/platform/agentHost/test/node/claudeMapSessionEvents.test.ts`, `src/vs/platform/agentHost/test/node/claudeMapSessionEventsTestUtils.ts`. - Plans: `phase6.1-plan.md` (the executed plan), `phase7-plan.md` (the next phase, drafted; not landing in this PR). - Touched code: `claudeAgent.ts`, `claudeAgentSdkService.ts`, `claudeAgentSession.ts`, `claudeMapSessionEvents.ts`, `claudeSessionConfigKeys.ts`. - Touched docs: `CONTEXT.md` (new — full M1–M13 mapping), `roadmap.md`, `phase5-plan.md`, `phase6-plan.md`. Verification ------------ - `npm run compile-check-ts-native`: 0 errors. - Affected test suites: 72/72 pass (`claudeAgent.test.ts` + `claudeModelConfig.test.ts` + `claudeMapSessionEvents.test.ts`). Risk ---- - Sidecar schema change: legacy sidecars without the `model` field default to `undefined`; tolerated. - Transcript discontinuity at Cycle C: sessions written before this PR have SDK-random uuids; one-time discontinuity expected, no migration. - Permission-mode enum widening: existing `'default' / 'acceptEdits' / 'bypassPermissions' / 'plan'` values remain valid; new values are additive. - Doc-only Cycle G changes carry no behavioral risk. Phase 7 (tools / permission / user input) and Phase 6.5 (fork) are not in this PR. See the in-tree plans.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR advances the VS Code agentHost Claude provider (Phases 4–6) toward the documented IAgent ↔ Claude SDK mapping by tightening auth error semantics, flowing model/config into the first SDK query, widening the mapper to handle canonical SDK envelopes, and aligning in-tree planning/roadmap docs. It also adds/updates a substantial set of unit tests to lock these contracts.
Changes:
- Enforce auth-required via
ProtocolError(AHP_AUTH_REQUIRED, …)for Claude lifecycle entrypoints, and add per-session metadata lookup (getSessionMetadata) backed by SDKgetSessionInfo. - Propagate
model,permissionMode, andthinkingLevel/effort into the firstquery()Options, persist/read model + permission mode in the per-session DB, and widen the advertised permission-mode enum to 6 values. - Update SDK-event mapping to recognize canonical
'assistant'envelopes, add direct mapper unit tests + fixtures, and refresh roadmap/phase plan docs.
Show a summary per file
| File | Description |
|---|---|
| src/vs/platform/agentHost/node/claude/claudeAgent.ts | Auth gating, model/config → Options plumbing, sidecar metadata read/write, model sorting, getSessionMetadata, permissionMode schema updates. |
| src/vs/platform/agentHost/node/claude/claudeAgentSdkService.ts | Extend SDK service boundary with getSessionInfo. |
| src/vs/platform/agentHost/node/claude/claudeAgentSession.ts | Adjust mapper callsite after mapper API change (no external state passed). |
| src/vs/platform/agentHost/node/claude/claudeMapSessionEvents.ts | Handle canonical 'assistant' envelope; simplify streaming mapping to stateless part-id derivation. |
| src/vs/platform/agentHost/common/claudeSessionConfigKeys.ts | Widen ClaudePermissionMode union to 6 values. |
| src/vs/platform/agentHost/common/claudeModelConfig.ts | New shared helper for thinking-level schema + effort resolution utilities. |
| src/vs/platform/agentHost/test/node/claudeAgent.test.ts | Expand coverage for auth, config propagation, model schema sourcing, canonical assistant behavior, metadata round-trips. |
| src/vs/platform/agentHost/test/node/claudeAgent.integrationTest.ts | Update SDK service test double for new getSessionInfo method. |
| src/vs/platform/agentHost/test/node/claudeMapSessionEvents.test.ts | New direct unit tests for mapSDKMessageToAgentSignals. |
| src/vs/platform/agentHost/test/node/claudeMapSessionEventsTestUtils.ts | New shared fixtures/builders for mapper and agent tests. |
| src/vs/platform/agentHost/test/common/claudeModelConfig.test.ts | New tests for resolveClaudeEffort, isClaudeEffortLevel, createClaudeThinkingLevelSchema. |
| src/vs/platform/agentHost/node/claude/roadmap.md | Roadmap alignment with the mapping/taxonomy and deferred fork plan. |
| src/vs/platform/agentHost/node/claude/phase5-plan.md | Doc alignment/status notes for fork + permission-mode evolution (contains a mismatch noted in review). |
| src/vs/platform/agentHost/node/claude/phase6-plan.md | Doc alignment/status notes for deferred fork approach. |
| src/vs/platform/agentHost/node/claude/phase6.1-plan.md | New/updated executed plan documenting cycles and decisions. |
| src/vs/platform/agentHost/node/claude/phase7-plan.md | New Phase 7 implementation plan doc. |
Copilot's findings
- Files reviewed: 16/17 changed files
- Comments generated: 1
Fix the Cycle G status note: the enum is 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'auto' (matching ClaudePermissionMode in claudeSessionConfigKeys.ts and the SDK's PermissionMode typedef), not the 'acceptAll' / 'denyAll' values previously listed. Addresses Copilot review comment on PR #315136.
Contributor
Screenshot ChangesBase: Changed (24)
|
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/CompletedRead/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/CompletedUnread/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/CompletedUnread/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/FailedWithDuration/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/FailedWithDuration/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/FailedWithoutDuration/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/FailedWithoutDuration/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithDiffChanges/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithDiffChanges/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithFileChangesList/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithFileChangesList/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithBadge/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithBadge/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithMarkdownBadge/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithMarkdownBadge/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithBadgeAndDiff/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/WithBadgeAndDiff/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/CloudProvider/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/CloudProvider/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/BackgroundProvider/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/BackgroundProvider/Light
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/ClaudeProvider/Dark
| Before | After |
|---|---|
 |
 |
agentSessionsViewer/ClaudeProvider/Light
| Before | After |
|---|---|
 |
 |
dmitrivMS
approved these changes
May 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 6.1 lands the architectural follow-ups identified after Phase 6's
sendMessage shipped. Eight tightly-scoped cycles (A–G) plus a stateless-mapper
cleanup, all backed by an exhaustive M1–M13 mapping of the IAgent ↔ Claude SDK
surface in CONTEXT.md.
tl;dr... this includes:
Cycle summary
createSession/_materializeProvisionalthrowProtocolError(AHP_AUTH_REQUIRED, …, getProtectedResources())instead of aplain
Error, so the workbench surfaces the sign-in flow (mirrorscopilotAgent.ts:382-385).SDKUserMessage.uuid = effectiveTurnId, single-namespace contract documented as a glossary entry.getSessionMetadata?per-session lookup;listSessionsoverlay readrefactored onto
_readSessionMetadata.dontAsk,auto);Options.model/Options.permissionMode/ effort flowthrough to the first
query();_writeSessionMetadatapersists model +permission mode alongside the customization-directory key.
'assistant'is canonical at the SDK seam, withreconciliation against
stream_eventpartials so deltas + final message nolonger double-emit.
tool_useblocks on the canonical envelope warn throughdefense-in-depth instead of silently leaking.
IClaudeModelConfig(createClaudeThinkingLevelSchema,isClaudeEffortLevel,resolveClaudeEffort) — pulled out as a statelesshelper so the mapper / agent / model picker share one effort-level vocabulary.
roadmap.md,phase5-plan.md,phase6-plan.mddriven by a 3-reviewer council pass. Resolves 10 drift items (see CONTEXT
ai-customization/ Phase 6.1 plan §"Cycle G — Stale phase-plan + roadmaprefresh"); CONTEXT.md is the truth oracle and is unchanged.
Files
src/vs/platform/agentHost/common/claudeModelConfig.ts,src/vs/platform/agentHost/test/common/claudeModelConfig.test.ts,src/vs/platform/agentHost/test/node/claudeMapSessionEvents.test.ts,src/vs/platform/agentHost/test/node/claudeMapSessionEventsTestUtils.ts.phase6.1-plan.md(the executed plan),phase7-plan.md(the nextphase, drafted; not landing in this PR).
claudeAgent.ts,claudeAgentSdkService.ts,claudeAgentSession.ts,claudeMapSessionEvents.ts,claudeSessionConfigKeys.ts.CONTEXT.md(new — full M1–M13 mapping),roadmap.md,phase5-plan.md,phase6-plan.md.Verification
npm run compile-check-ts-native: 0 errors.claudeAgent.test.ts+claudeModelConfig.test.ts+claudeMapSessionEvents.test.ts).Risk
modelfield default toundefined; tolerated.SDK-random uuids; one-time discontinuity expected, no migration.
'default' / 'acceptEdits' / 'bypassPermissions' / 'plan'values remain valid; new values are additive.Phase 7 (tools / permission / user input) and Phase 6.5 (fork) are not in this
PR. See the in-tree plans.