What causes "Unknown subagent session file" in can1357/oh-my-pi?

Use the sessionFile path that was returned when the subagent was created, not a hand-built path.

Unknown subagent session file

Error message

Unknown subagent session file

What it means

resolveSessionFile accepts an explicit sessionFile in the selector, but only if that file is part of the transcript's known session files (checked by #hasTranscriptSessionFile). Passing a path the transcript does not recognize throws 'Unknown subagent session file', preventing reads of arbitrary or untracked session files through this RPC surface.

Source

Thrown at packages/coding-agent/src/modes/rpc/rpc-subagents.ts:260

	handleEvent(payload: SubagentEventPayload): void {
		if (this.#staleSubagentIds.has(payload.id)) return;
		if (this.#subscriptionLevel !== "events") return;
		this.#output({ type: "subagent_event", payload } satisfies RpcSubagentEventFrame);
	}

	resolveSessionFile(selector: RpcSubagentTranscriptSelector): string {
		if (selector.subagentId) {
			const snapshot = this.#subagents.get(selector.subagentId);
			const sessionFile = snapshot?.sessionFile ?? this.#transcriptSessionFilesBySubagentId.get(selector.subagentId);
			if (!sessionFile) {
				throw new Error(`Unknown subagent or session file unavailable: ${selector.subagentId}`);
			}
			return sessionFile;
		}

		if (selector.sessionFile) {
			if (this.#hasTranscriptSessionFile(selector.sessionFile)) return selector.sessionFile;
			throw new Error("Unknown subagent session file");
		}

		throw new Error("get_subagent_messages requires subagentId or sessionFile");
	}
}

View on GitHub (pinned to 9690622007)

Solutions

Use the sessionFile path that was returned when the subagent was created, not a hand-built path.
Prefer selector.subagentId so the resolver looks up the correct registered file.
Verify the file belongs to the current transcript/session before calling.

Example fix

// before
subagents.resolveSessionFile({ sessionFile: "/tmp/other-project/session.jsonl" });
// after
subagents.resolveSessionFile({ subagentId: spawnedSubagent.id });

Defensive patterns

Strategy: validation

Validate before calling

// only pass session files that were obtained from this session's subagent records
if (!sessionFileFromSubagentRecord) throw new Error("refusing to resolve hand-built session path");

Try / catch

try {
  const file = subagents.resolveSessionFile({ sessionFile });
} catch (err) {
  if (err instanceof Error && err.message === "Unknown subagent session file") {
    // retry via subagentId or report the untracked file
  } else throw err;
}

Prevention

Never construct session file paths manually; use paths returned by subagent spawn results.
Use subagentId selectors so the resolver finds the registered file.
Remember paths are transcript-scoped; files from other sessions/projects are rejected.

When it happens

Trigger: Passing selector.sessionFile set to a path that was never registered as a subagent session in the current transcript — e.g. an absolute path to a session from another project, a renamed/moved file, or a fabricated path.

Common situations: Pointing the selector at a main-session file instead of a subagent session file; constructing the path by hand rather than using an ID returned by the subagent APIs; sessions moved between machines where the recorded paths differ.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/24b26624b6bbc8bc. Report an issue: GitHub.