claude-code - 💡(How to fix) Fix [DOCS] Subagent resume docs omit `cwd` continuity for `SendMessage` resumes [1 participants]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

Resume subagents (and related SendMessage / Agent SDK resume guidance)

Current Documentation

The docs currently say:

Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.

When a subagent completes, Claude receives its agent ID. Claude uses the SendMessage tool with the agent's ID as the to field to resume it.

If a stopped subagent receives a SendMessage, it auto-resumes in the background without requiring a new Agent invocation.

The Agent SDK page currently says:

To resume a subagent programmatically:

1. Capture the session ID: Extract session_id from messages during the first query
2. Extract the agent ID: Parse agentId from the message content
3. Resume the session: Pass resume: sessionId in the second query's options, and include the agent ID in your prompt

Separate session docs mention the cwd requirement more generally:

If a resume call returns a fresh session instead of the expected history, the most common cause is a mismatched cwd.

What's Wrong or Missing?

The subagent resume docs explain history continuity, but they do not explain working-directory continuity.

Changelog v2.1.118 includes: Fixed subagents resumed via SendMessage not restoring the explicit cwd they were spawned with.

That fix implies a user-visible contract that resumed subagents should continue in the same working directory/worktree they originally started with, including an explicit cwd when one was used. The current docs do not say that anywhere in the Resume subagents section or the SendMessage tool description.

For SDK users, the subagent resume page also omits the practical requirement that resume calls must keep the original cwd, even though the separate session docs already note that mismatched cwd can make resume behave like a fresh session.

Suggested Improvement

Add one short note anywhere subagent resume is documented:

Resumed subagents continue in the working directory (or isolated worktree) they were originally spawned with. SendMessage resumes the existing subagent context; it does not switch the subagent to the caller's current directory.

Then add an SDK-specific note in the Agent SDK subagents page that links to the session resume docs, for example:

When resuming programmatically, use the same session and the same cwd as the original query. If the cwd changes, resume may not find the existing transcript and can behave like a fresh session.

It would also help to add a short clause to the SendMessage row in Tools reference noting that resumed subagents keep their original working directory/worktree.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.118

Exact changelog entry: Fixed subagents resumed via SendMessage not restoring the explicit cwd they were spawned with