can1357/oh-my-pi · error · StructuredSubagentError

Isolated subagent execution could not be prepared: ${message

Error message

Isolated subagent execution could not be prepared: ${message}

What it means

Thrown at stage "isolation" when `prepareIsolationContext` fails while setting up isolated execution for a subagent. The original error message (git/worktree setup failure, missing tool, filesystem error) is wrapped into a StructuredSubagentError with the underlying error attached as `cause`.

Source

Thrown at packages/coding-agent/src/task/structured-subagent.ts:584

			? (result: SingleResult) => request.session.recordEvalSubagentUsage?.(result.usage?.output ?? 0)
			: undefined;
	try {
		const id = await reserveStructuredSubagentId(request.session, {
			...request.identity,
			label: request.identity?.label ?? (request.invocationKind === "eval" ? "EvalAgent" : undefined),
		});
		const baseOptions = buildExecutorOptions(request, policy, lease, id);
		baseOptions.onCleanupDeferred = completion => {
			deferredCleanup = completion;
		};
		baseOptions.planReference = await loadPlanReference(request, policy);
		let isolationContext: IsolationContext | null = null;
		if (policy.isIsolated) {
			try {
				isolationContext = await prepareIsolationContext(request.session.cwd);
			} catch (error) {
				const message = error instanceof Error ? error.message : String(error);
				throw new StructuredSubagentError(
					"isolation",
					`Isolated subagent execution could not be prepared: ${message}`,
					{ cause: error },
				);
			}
		}
		let result: SingleResult;
		if (!isolationContext) {
			result = await runSubprocess(baseOptions);
			onSubprocessResult?.(result);
		} else {
			result = await runIsolatedSubprocess({
				baseOptions,
				context: isolationContext,
				preferredBackend: parseIsolationMode(request.session.settings.get("task.isolation.mode")),
				agentId: id,
				mergeMode: policy.mergeMode,
				artifactsDir: lease.artifactsDir,

View on GitHub (pinned to 9690622007)

Solutions

1. Read the wrapped `cause` message and fix the underlying isolation setup failure (repo state, git availability)
2. Run the session from a valid git working tree when using worktree isolation
3. Disable isolation (`isolation.requested: false`/omit) if the environment cannot support it

Example fix

// before: isolated run in a non-git directory
await task({ agent: "a", isolation: { requested: true } });
// after: init the repo first, or run without isolation
await task({ agent: "a" });

const probe = Bun.spawnSync(["git", "rev-parse", "--is-inside-work-tree"], { cwd: session.cwd });
if (probe.exitCode !== 0) throw new Error("Isolation requires a valid git working tree");

try {
  return await runStructuredSubagent(req);
} catch (e) {
  if (e instanceof StructuredSubagentError && e.stage === "isolation") {
    logger.error("isolation prep failed", { cause: e.cause });
    return runStructuredSubagent({ ...req, isolation: undefined }); // fall back to non-isolated
  }
  throw e;
}

When it happens

Trigger: `policy.isIsolated` is true and `prepareIsolationContext(request.session.cwd)` throws — e.g. worktree creation fails because the directory is not a git repo, git is missing, or the worktree path already exists.

Common situations: Running isolated subagents in a non-git project or bare checkout; dirty/conflicting worktree state; git unavailable or version too old in CI images; permission errors on the repo path.

Related errors

• agent() isolated apply failed for ${result.id}${summary ? `:
• agent() isolated nested patch apply failed for ${result.id}:
• Subagent isolation, apply, and merge controls are unavailabl
• Subagent isolated execution requires task.isolation.mode to
• No isolation backend is available.

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