Subagent sessions don't inherit parent SessionFs state, breaking spill-then-delegate flows

[loganrosen]

Subagents launched via the task tool run as sub-sessions with their own session_id. Because every SessionFs RPC carries session_id, and the standard create_session_fs_handler factory binds a fresh SessionFsProvider per session_id, a subagent's SessionFs scope is disjoint from the parent's. The parent's spilled tool outputs are therefore unreachable from the subagent.

This breaks any flow where the parent agent escalates to task after an "Output too large… Saved to: /session-state/temp/X.txt" spill. The subagent's response in our trace:

The file path /session-state/temp/1776981956649-copilot-tool-output-nf0exj.txt does not exist in the current environment. The directory structure you referenced doesn't appear to be available.

This is independent of #1091: even if the spill template stopped referencing tools the consumer disabled, task would still be referenced as a fallback (the spill suggests "tools like grep, head/tail, view, ... or jq"), and task is structurally unable to reach a parent-session file because its sub-session has its own SessionFs scope.

Reproduction

1. Provide a custom SessionFsProvider via create_session_fs_handler, with a factory that binds per session.session_id (the standard pattern).
2. Register a custom tool that returns >32KB so it triggers spill.
3. Prompt the parent agent to invoke that tool, then to delegate (e.g. "use the task tool to summarize the result").
4. Parent agent calls the tool → spill writes to its {base}/{parent_session_id}/session-state/temp/X.txt. Parent invokes task with the spill path in the prompt. Subagent's SessionFs scope is {base}/{subagent_session_id}/; the file at the parent's path is not visible. Subagent reports the file doesn't exist.

Possible fixes (any one works)

• Don't reference task in the spill template — it's structurally never a valid read tool for a parent-session file.
• Share SessionFs scope across all sessions in the same task tree (or at least for paths under session_state_path).
• Provide a per-task-tree workspace handle distinct from per-session SessionFs.

Related

• Tool output truncation references tools that may be disabled #1091 — spill template references tools the consumer can't reach.
• MCP tool responses silently truncated to 10KB before large-output-to-file mechanism can save them copilot-cli#1732 — original spill mechanism design.

Versions

Reproduced on github-copilot-sdk 0.3.0 with bundled Copilot CLI 1.0.36-0. Walked the changelogs through CLI 1.0.40-0 (latest pre-release) — no spill-related fixes shipped, so this is current behavior.

[github-actions]

Investigation findings

I investigated this by tracing the relevant code paths in the Node SDK (the same structural issue applies to Python and Go SDKs).

Files examined

• nodejs/src/client.ts — session registration and registerClientSessionApiHandlers
• nodejs/src/generated/rpc.ts — registerClientSessionApiHandlers implementation
• nodejs/src/sessionFsProvider.ts — SessionFsProvider interface
• nodejs/src/types.ts — SessionFsConfig, SessionLifecycleEvent

Root cause confirmed

The bug is real. Here's what happens at the code level:

1. registerClientSessionApiHandlers (rpc.ts:2435) is the sole entry point for all sessionFs.* RPC calls. It resolves the handler by looking up sessionId in the client's sessions map:

   registerClientSessionApiHandlers(this.connection, (sessionId) => {
       const session = sessions.get(sessionId);
       if (!session) throw new Error(`No session found for sessionId: ${sessionId}`);
       return session.clientSessionApis;
   });

2. The sessions map is only populated via client.createSession() and client.resumeSession() (lines 713, 855). Sub-sessions spawned internally by the CLI's task tool are never added to this map.

3. When the CLI's task tool creates a sub-session and issues sessionFs.* RPCs using the sub-session's sessionId, the lookup throws No session found for sessionId: ${subSessionId}. The CLI receives a JSON-RPC error and the sub-agent effectively has no SessionFs access — meaning spill files written to the parent's scope are completely unreachable.

4. Even if the SDK were extended to auto-register sub-sessions (e.g., by calling createSessionFsHandler when a subagent.started lifecycle event arrives), the standard factory pattern (session) => new Provider(join(base, session.sessionId)) would still produce a disjoint scope under the sub-session's own sessionId.

Classification: bug

The createSessionFsHandler contract provides no way to express "this sub-session should share the parent's scope," and the SDK doesn't forward sub-session SessionFs RPCs at all (it throws). The spill-then-delegate flow is structurally broken. This is confirmed as a bug, not working-as-designed behavior.

The possible fixes noted in the issue are all valid avenues (removing task from the spill template, sharing scope across a task tree, or a per-task-tree workspace handle); the right fix likely involves coordination between the SDK and the CLI on how sub-session SessionFs requests should be resolved.

Generated by Bug Handler for issue #1168 · ● 1.6M · ◷

[loganrosen]

Probed the parent-agent path empirically and the bug is broader than the title suggests — the built-in fs tools (view, grep, head, tail, jq, bash) don't route through SessionFs RPC for paths under session_state_path either, so even the parent agent (whose session IS registered) can't reach its own spill files.

Setup: custom SessionFsProvider writing under {base}/{session_id}/, instrumented to log every SessionFs RPC. Triggered a spill, then asked the model to read it.

[SessionFs RPC] read_file('/session-state/workspace.yaml')
[SessionFs RPC] exists('/session-state/checkpoints/index.md') = True
[SessionFs RPC] read_file('/session-state/checkpoints/index.md')
[SessionFs RPC] exists('/session-state/plan.md') = False
...spill happens...
TOOL [return_big] result preview: Output too large to read at once (44.4 KB). Saved to: /session-state/temp/1777497546602-copilot-tool-output-1umfkr.txt
[SessionFs RPC] exists('/session-state/plan.md') = False
TOOL [bash] result preview: temp directory not found

RPCs targeting spill path (/session-state/temp/1777497546602-copilot-tool-output-1umfkr.txt): 0

The CLI uses SessionFs RPC for its own internals (workspace.yaml, plan.md, checkpoints/index.md) but not for user-facing read tools. So the spill writer puts files in one namespace and the suggested readers look in another.

Subagent isolation (this issue's original framing) and parent-agent failure are two manifestations of the same root cause: built-in fs tools aren't SessionFs-aware. A fix that routes those tools through SessionFs RPC for session_state_path-prefixed paths covers both.

Reproduced on github-copilot-sdk 0.3.0 with bundled CLI 1.0.36-0; CLI changelog through 1.0.40-0 has no spill-related fixes.