Compare commits

..

1 Commits

Author SHA1 Message Date
Ben Brandt
184b7df993 fix: match v1 session/options to resume when workspace roots change (#1679)
The [Session options
RFD](https://agentclientprotocol.com/rfds/session-options) says that
querying an existing session should report what restoring it in the
requested workspace would return, without changing that session. On v1
the query always returned the held session’s options. Changing
`additionalDirectories` could therefore show Haiku in the picker even
though `session/resume` with the same directories returned Sonnet.

`session/options` now makes the same reuse decision as `session/load`
and `session/resume`. When the workspace matches, it answers from the
live session without launching Claude Code. When it differs, it reads
the options through a non-persisting query and leaves the live query
running. The probe keeps the live permission mode, starts no configured
MCP servers, and does not attach the adapter’s session-update hooks.
Claude Code has no transcript until the first prompt, so for a held but
unprompted session the probe can fall back to a fresh query without
claiming the held session’s ID. An unknown ID still returns `-32002`.

## Verification

- Added regression coverage for held sessions with and without a stored
conversation. The changed-workspace cases failed before the fix. Also
covered the no-query path when the held session has MCP servers and a
system prompt, neither of which `session/options` accepts.
- `npm run build` and `npm run check` passed. Adapter test suite: 4,414
passed, 41 skipped; the focused v1 options suite passed with the final
assertions.
- Exercised v1 over stdio with the bundled Claude Code binary and a
local Messages API stub. For both a saved conversation and an unprompted
one, the live session stayed on `opus`; the preview for the changed
roots and subsequent resume both returned `default`. The preview left
`session/list` and the transcript files unchanged.
2026-11-20 15:48:20 +00:00
3 changed files with 110 additions and 46 deletions

View File

@@ -28,6 +28,7 @@ let initModels: Record<string, unknown>[] | undefined;
/** Holds the CLI initialization until the test resolves it. */
let initGate: Promise<void> | undefined;
let initError: Error | undefined;
let missingConversation: string | undefined;
/** When set, the SDK refuses the query's options with it: `query()` throws. */
let optionsRefusal: Error | undefined;
let setModelImpl: ((model: string) => Promise<void>) | undefined;
@@ -65,6 +66,9 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
initializationResult: async () => {
await initGate;
if (initError) throw initError;
if (args.options.resume && args.options.resume === missingConversation) {
throw new Error(`No conversation found with session ID: ${args.options.resume}`);
}
return initializationResponse();
},
setModel: (model: string) => (setModelImpl ? setModelImpl(model) : Promise.resolve()),
@@ -126,6 +130,7 @@ describe("createSession options merging", () => {
initModels = undefined;
initGate = undefined;
initError = undefined;
missingConversation = undefined;
optionsRefusal = undefined;
setModelImpl = undefined;
interruptImpl = undefined;
@@ -1488,12 +1493,18 @@ describe("createSession options merging", () => {
});
it("answers session/options with what session/new returns, from a query that it closes", async () => {
const options = await agent.sessionOptions({ cwd, additionalDirectories: ["/extra"] });
const context = {
cwd,
additionalDirectories: ["/extra"],
_meta: { claudeCode: { options: { mcpServers: { docs: { command: "docs-server" } } } } },
};
const options = await agent.sessionOptions(context);
expect(capturedOptions).toMatchObject({
cwd,
additionalDirectories: ["/extra"],
mcpServers: {},
strictMcpConfig: true,
persistSession: false,
});
expect(capturedOptions!.resume).toBeUndefined();
@@ -1501,7 +1512,7 @@ describe("createSession options merging", () => {
expect(agent.sessions).toEqual({});
expect(updates).toEqual([]);
const { sessionId, ...created } = await agent.newSession({ cwd, mcpServers: [] });
const { sessionId, ...created } = await agent.newSession({ ...context, mcpServers: [] });
expect(sessionId).toBeDefined();
expect(capturedOptions!.persistSession).toBeUndefined();
expect(options).toEqual(created);
@@ -1518,7 +1529,11 @@ describe("createSession options merging", () => {
});
it("answers session/options of a held session with its current options, without a query", async () => {
const { sessionId } = await agent.newSession({ cwd, mcpServers: [] });
const { sessionId } = await agent.newSession({
cwd,
mcpServers: [{ name: "docs", type: "http", url: "https://example.test/mcp", headers: [] }],
systemPrompt: { mode: "append", content: [{ type: "text", text: "Be brief." }] },
});
const { configOptions } = await agent.setSessionConfigOption({
sessionId,
configId: "model",
@@ -1526,13 +1541,45 @@ describe("createSession options merging", () => {
});
capturedOptions = undefined;
const options = await agent.sessionOptions({ cwd, sessionId });
const options = await agent.sessionOptions({ cwd, sessionId, additionalDirectories: [] });
expect(capturedOptions).toBeUndefined();
expect(options).toEqual({ modes: agent.sessions[sessionId]!.modes, configOptions });
expect(values(options).model).toBe("claude-haiku-4-5");
});
it.each(["stored", "not yet stored"] as const)(
"predicts resume in a changed workspace without replacing the held session (%s)",
async (transcript) => {
const { sessionId } = await agent.newSession({
cwd,
mcpServers: [],
configOptions: [
{ configId: "model", value: "claude-haiku-4-5" },
{ configId: "mode", value: "plan" },
],
});
const held = agent.sessions[sessionId]!;
if (transcript === "not yet stored") missingConversation = sessionId;
const context = { cwd, sessionId, additionalDirectories: [path.join(cwd, "src")] };
const preview = await agent.sessionOptions(context);
const probe = capturedOptions;
expect(agent.sessions[sessionId]).toBe(held);
expect(held.queryClosed).not.toBe(true);
expect(values(held).model).toBe("claude-haiku-4-5");
const { modes, configOptions } = await agent.resumeSession(context);
expect(preview).toEqual({ modes, configOptions });
expect(probe).toMatchObject({
persistSession: false,
additionalDirectories: context.additionalDirectories,
});
expect(probe!.resume).toBe(transcript === "stored" ? sessionId : undefined);
expect(probe!.sessionId).not.toBe(sessionId);
},
);
it("answers session/options of a stored session from a query that resumes it", async () => {
const sessionId = "7f1c5b0e-3c53-4c0c-9d0a-0d6c1f0a2b11";
await agent.sessionOptions({ cwd, sessionId });
@@ -1545,7 +1592,7 @@ describe("createSession options merging", () => {
it("fails session/options of an unknown session with -32002", async () => {
const sessionId = "7f1c5b0e-3c53-4c0c-9d0a-0d6c1f0a2b11";
initError = new Error(`No conversation found with session ID: ${sessionId}`);
missingConversation = sessionId;
await expect(agent.sessionOptions({ cwd, sessionId })).rejects.toMatchObject({
code: RequestError.sessionNotFound(sessionId).code,

View File

@@ -1943,7 +1943,7 @@ export class ClaudeAcpAgent {
* the same `cwd`, additional directories and `_meta` would answer with, or
* `session/load` and `session/resume` of `sessionId`.
*
* A session that this connection holds answers with what it has now.
* A held session answers from memory if load/resume would reuse its query.
* Otherwise a query starts as the session's would, without MCP servers, and
* closes once its options are read (`optionsOnly` in `createSession`). The
* query does not persist: it stores no session, and it does not write to
@@ -1951,24 +1951,23 @@ export class ClaudeAcpAgent {
* hooks in it, as in every query.
*
* It sends no update, and it creates, loads and changes no session. A
* `sessionId` without a stored conversation fails with `-32002`.
* `sessionId` that is neither held nor stored fails with `-32002`.
*/
async sessionOptions(params: SessionOptionsRequest): Promise<SessionOptionsResponse> {
while (this.providerUpdate) await this.providerUpdate;
const held = params.sessionId != null ? this.sessions[params.sessionId] : undefined;
if (held) {
await this.validateCwd(params.cwd, params.additionalDirectories);
return { modes: held.modes, configOptions: held.configOptions };
}
const { modes, configOptions } = await this.createSession(
{
cwd: params.cwd,
mcpServers: [],
additionalDirectories: params.additionalDirectories,
_meta: params._meta,
},
{ resume: params.sessionId ?? undefined, optionsOnly: true },
);
const setup = {
cwd: params.cwd,
mcpServers: [],
additionalDirectories: params.additionalDirectories,
_meta: params._meta,
};
const { modes, configOptions } =
params.sessionId == null
? await this.createSession(setup, { optionsOnly: true })
: await this.getOrCreateSession(
{ ...setup, sessionId: params.sessionId },
{ optionsOnly: true },
);
return { modes, configOptions };
}
@@ -2125,7 +2124,7 @@ export class ClaudeAcpAgent {
let result: NewSessionResponse;
if (this.sessions[params.sessionId]) {
const resumedSession = await readResumedSession(params.sessionId, this.logger);
result = await this.getOrCreateSession(params, resumedSession);
result = await this.getOrCreateSession(params, { resumedSession });
timing.phase("session-ready");
await this.replaySessionHistory(params.sessionId, resumedSession.messages);
} else {
@@ -2815,14 +2814,10 @@ export class ClaudeAcpAgent {
}
/**
* Starts a new query for the session `sessionId`, which ran on this
* connection and whose query is gone: it resumes the stored conversation.
* `resume` names the Claude session, which shares the ACP session id, so the
* new query continues the same conversation under the same id. Claude Code
* writes the conversation at the first prompt, so resuming a session that was
* never prompted fails with `sessionNotFound`, and keeps failing. Such a
* session starts a fresh query under the same id instead: it has no history
* to lose, and the client keeps a session it can use.
* Starts the query that a held session would resume with. Claude Code writes
* the conversation at the first prompt. If there's nothing to resume, start
* fresh: a replacement keeps the session's id; an options probe keeps neither
* query nor id.
*/
private async recreateLiveSession(
params: NewSessionRequest,
@@ -2831,6 +2826,7 @@ export class ClaudeAcpAgent {
permissionMode?: PermissionMode;
resumedModelHint?: string | Promise<string | undefined>;
replacingSession?: Session;
optionsOnly?: boolean;
},
): Promise<NewSessionResponse> {
try {
@@ -2841,11 +2837,10 @@ export class ClaudeAcpAgent {
)) {
throw error;
}
this.logger.log(
`session ${sessionId} was never persisted; starting a fresh query under the same id`,
);
this.logger.log(`session ${sessionId} has no stored conversation; starting a fresh query`);
return await this.createSession(params, {
reuseSessionId: sessionId,
// A probe doesn't claim the id of the session it is describing.
...(options.optionsOnly ? { optionsOnly: true } : { reuseSessionId: sessionId }),
permissionMode: options.permissionMode,
replacingSession: options.replacingSession,
});
@@ -9879,7 +9874,10 @@ export class ClaudeAcpAgent {
systemPrompt?: NewSessionRequest["systemPrompt"];
_meta?: NewSessionRequest["_meta"];
},
resumedSession?: ResumedSessionSnapshot,
{
resumedSession,
optionsOnly,
}: { resumedSession?: ResumedSessionSnapshot; optionsOnly?: boolean } = {},
): Promise<NewSessionResponse> {
// Reject a bad `cwd` or prompt before reusing or tearing down a live session.
await this.validateCwd(params.cwd, params.additionalDirectories);
@@ -9888,7 +9886,17 @@ export class ClaudeAcpAgent {
// A recreated live session keeps its mode, not the mode of the transcript.
const livePermissionMode = existingSession?.modes.currentModeId as PermissionMode | undefined;
if (existingSession) {
const fingerprint = computeSessionFingerprint(params);
// `session/options` cannot supply MCP servers or a system prompt. Their
// absence in a probe is not a request to replace the held session's.
const fingerprint = computeSessionFingerprint(
optionsOnly
? {
...params,
mcpServers: existingSession.creationParams?.mcpServers,
systemPrompt: existingSession.creationParams?.systemPrompt,
}
: params,
);
if (fingerprint === existingSession.sessionFingerprint) {
return {
sessionId: params.sessionId,
@@ -9897,11 +9905,8 @@ export class ClaudeAcpAgent {
};
}
// Session-defining params changed (e.g. cwd pointed at a git worktree,
// MCP servers reconfigured, or the skill set changed). Tear down the
// existing session and recreate it so the underlying Query process picks
// up the new values.
await this.teardownSession(params.sessionId);
// Load/resume replaces the query. An options probe leaves it running.
if (!optionsOnly) await this.teardownSession(params.sessionId);
}
const sessionParams = {
@@ -9913,6 +9918,7 @@ export class ClaudeAcpAgent {
};
const creation = {
permissionMode: livePermissionMode,
optionsOnly,
...(resumedSession ? { resumedModelHint: resumedSession.model } : {}),
};
// A live session may never have been prompted, so it may have no stored
@@ -10021,7 +10027,10 @@ export class ClaudeAcpAgent {
// We want to create a new session id unless it is resume,
// but not resume + forkSession.
let sessionId;
if (creationOpts.publicSessionId) {
if (creationOpts.optionsOnly) {
// The transcript to read is `resume`. No callback from this query owns that session.
sessionId = randomUUID();
} else if (creationOpts.publicSessionId) {
sessionId = creationOpts.publicSessionId;
} else if (creationOpts.forkSession) {
sessionId = randomUUID();
@@ -10418,7 +10427,14 @@ export class ClaudeAcpAgent {
},
...(creationOpts.resume !== undefined && { resume: creationOpts.resume }),
...(creationOpts.forkSession !== undefined && { forkSession: creationOpts.forkSession }),
...(creationOpts.optionsOnly ? { persistSession: false } : {}),
// The probe neither reports session updates through our hooks nor
// starts the MCP servers in the client's options or workspace settings.
...(creationOpts.optionsOnly && {
persistSession: false,
hooks: userProvidedOptions?.hooks,
strictMcpConfig: true,
mcpServers: {},
}),
abortController,
};
@@ -10473,7 +10489,9 @@ export class ClaudeAcpAgent {
(error.message === "Query closed before response received" ||
error.message.includes("No conversation found with session ID"))
) {
throw RequestError.sessionNotFound(sessionId);
throw RequestError.sessionNotFound(
creationOpts.optionsOnly ? creationOpts.resume : sessionId,
);
}
throw startupFailureError(error) ?? error;
}

View File

@@ -136,8 +136,7 @@ export function computeSessionFingerprint(params: {
canonicalJson({
cwd: params.cwd,
mcpServers: servers,
additionalDirectories: params.additionalDirectories,
additionalRoots: meta?.additionalRoots,
additionalDirectories: params.additionalDirectories ?? meta?.additionalRoots ?? [],
systemPrompt: meta?.systemPrompt,
clientSystemPrompt: params.systemPrompt ?? undefined,
disableBuiltInTools: meta?.disableBuiltInTools,