Customization migration hint missing on first request for all Agent Host harnesses

[aeschli]

Problem

A fresh Claude chat does not show a customization migration hint on its first request. Sending a second message in the same chat immediately shows the correct hint.

Reproduction

1. Enable chat.customizations.migrationHint and the file migration categories.
2. Open a fresh Claude-backed chat in a workspace with migratable customizations.
3. Send hello.
4. Observe no migration hint.
5. Send a second hello in the same session.
6. Observe the correct hint: Found 8 workspace and 1 user customizations that are present but not used by Claude and could be migrated.

Cause

The workbench calculates the migration hint before sending the first request. At that time, the newly-created Claude chat does not yet have a registered chat backing:

• AgentService.createSession() asks ClaudeAgent.getChatCustomizations() for the initial snapshot.
• ClaudeAgent.getChatCustomizations() calls _findChatByUri() and returns [] when there is no backing.
• The backing and live ClaudeAgentSession are registered only as the first request resolves/materializes.
• That first request consequently publishes the customization snapshot too late for its own hint, but early enough for the following request.

Requested change

Make Claude provide its initial customization snapshot, including migration destinations, before the workbench computes the first request’s migration hint. The solution should establish or otherwise resolve the default chat backing during session creation without requiring an SDK request/materialization side effect.

The same pre-request snapshot should be used by getChatCustomizations() for a new provisional session, so customizations and migration source folders are available on the first user message.

Related

• Claude does not return DirectoryCustomization for empty target directories #334938 adds the missing empty Claude directory destinations.
• Fix Claude customization migration targets #334942 implements that fix but does not address first-request timing.
• Track customization migration readiness for Agent Host #332083 tracks migration readiness more generally.

[aeschli]

Correction / additional evidence: the Customizations overview uses CustomizationMigrationAvailabilityService, which calls the same ICustomizationMigrationService.computeMigration(...) implementation used by computeMigrationHint(). The overview can show the correct counts before any user request.

Therefore the defect is a race between two evaluations against the same Agent Host customization state, not distinct candidate-discovery implementations. The chat-request path computes its hint immediately when the first request is submitted; the overview refresh is scheduled after active-harness/session changes and can run after the initial Claude customization snapshot has reached the client. Once that snapshot arrives, both callers compute the same candidates.

The fix should ensure the first request waits for, or is given, the initial customization snapshot before calling computeMigrationHint(), rather than require another user request.

[aeschli]

Updated: this is provider-independent, and the root cause is a synchronous read of an unresolved subscription

Reproduced with Copilot as well as Claude, in the same workspace:

Request	Result
1st Hello in a fresh chat	no hint
2nd message in the same chat	Found 1 user customization file that is present but not used by Copilot and could be migrated.

Codex shows the same first-request behaviour. So this is not specific to the Claude harness, and it is not caused by a provider failing to publish destinations. (The separate Claude gap in #334938 / #334942 is a real but distinct bug: it removed the destinations entirely, for every request.)

Root cause

The migration hint resolves candidates through AgentCustomizationItemProvider.provideSourceFolders(), which calls IAgentHostCustomizationService.getCustomizations(sessionResource).

In WorkbenchAgentHostCustomizationService, that read is synchronous over an AHP subscription:

protected override _resolveTarget(sessionResource: URI) {
    ...
    const sessionState = this._readSessionState(sessionResource);
    return {
        customizations: sessionState?.customizations ?? [],
        ...
    };
}

private _readSessionState(sessionResource: URI): SessionState | undefined {
    const target = this._resolveSessionTarget(sessionResource);
    const subscription = target ? this._ensureSessionStateSubscription(sessionResource, target)?.sub : undefined;
    const value = subscription?.value;
    return value instanceof Error ? subscription?.verifiedValue : value;
}

_ensureSessionStateSubscription creates the subscription on demand, and IAgentSubscription.value is documented as:

undefined until the first snapshot arrives.

So the first read after a subscription is created always yields undefined, which degrades to customizations: [].

Why the first request in particular

_sessionStateSubscriptions is keyed by the chat UI resource. On the first Send of a new chat, ChatServiceImpl.sendRequest calls _materializeUntitledSession(), which swaps the untitled resource for a newly minted real resource (agent-host-PROVIDER:/untitled-<uuid> → agent-host-PROVIDER:/<uuid>) and rebinds the provisional backend session.

collectCustomizationMigrationHint() then runs against that brand-new resource, so:

1. no subscription exists for it yet,
2. one is created at that moment,
3. its value is still undefined,
4. getCustomizations() returns [],
5. provideSourceFolders() returns no folders,
6. createFileMigration() filters out every candidate,
7. no hint is produced — silently, as if there were nothing to migrate.

By the time anything else reads the same state the snapshot has arrived, which is why the second request and the Customizations overview both report the correct counts. The overview additionally re-renders on onDidChangeCustomizations, so it is inherently resilient to this; the hint is a one-shot with no wait or retry.

This also explains why the symptom looks intermittent: whenever the subscription happens to already be warm for the resolved resource, the hint appears.

Suggested fix

Make the hint path wait for the session state to be available instead of reading a possibly-unresolved subscription:

• have IAgentHostCustomizationService expose an awaitable readiness signal for a session's state (first snapshot arrived, or a bounded timeout), and
• await it in AgentCustomizationItemProvider.provideSourceFolders(), which is already async.

That fixes the hint for every harness at once, and leaves the reactive Customizations UI unchanged. Distinguishing "state not loaded yet" from "genuinely no destinations" is the key point — today they are indistinguishable, so a not-yet-loaded session is silently reported as having nothing to migrate.