{"record":{"id":"06fd5888fa8230c1","repo":"JuliusBrussee/caveman","slug":"cave-claude-subagent-bridge-unavailable-06fd58","errorCode":"cave_claude_subagent_bridge_unavailable","errorMessage":"cave_claude_subagent_bridge_unavailable","messagePattern":"cave_claude_subagent_bridge_unavailable","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":924,"sourceCode":"    entryPath: snapshot.entryPath,\n    sourceFiles: snapshot.sourceFiles,\n    executionContext,\n    dispose: snapshot.dispose,\n  };\n}\n\n/** Package-internal harness bridge. Reuses Pi's exact tool/result policy. */\nexport function createHarnessToolExecutor(input: {\n  definition: AgentDefinition;\n  tool: ToolDefinition;\n  sandbox: HarnessToolSandbox;\n  sandboxProfile?: RunOptions[\"sandboxProfile\"];\n  engineBin?: string;\n  providerDefinition?: { description: string; input: TSchema };\n  deferLockedToolResult?: boolean;\n}): (params: unknown, signal?: AbortSignal) => Promise<unknown> {\n  if (input.tool.runtime?.kind === \"subagent\") {\n    throw new Error(\"cave_claude_subagent_bridge_unavailable\");\n  }\n  const sandboxExecute = input.definition.sandbox === \"required\"\n    ? (params: unknown, signal?: AbortSignal) => executeSandboxedTool(\n      input.sandbox.entryPath!,\n      input.sandbox.sourceFiles,\n      input.sandbox.stagingRoot!,\n      input.tool.name,\n      params,\n      input.tool.timeoutMs,\n      true,\n      input.sandboxProfile,\n      input.sandbox.executionContext,\n      toolDefinitionSHA256(input.tool),\n      signal,\n    )\n    : undefined;\n  const executor = toPiTool(\n    input.tool,","sourceCodeStart":906,"sourceCodeEnd":942,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/runtime.ts#L906-L942","documentation":"Thrown by createHarnessToolExecutor() when the tool handed to the package-internal harness bridge is a subagent tool (tool.runtime?.kind === \"subagent\"). This bridge reuses Pi's exact tool/result policy for a single staged tool; nested agent invocation is not implemented on that path, so it refuses rather than executing the subagent incorrectly.","triggerScenarios":"Calling createHarnessToolExecutor with a ToolDefinition whose runtime.kind === \"subagent\" — i.e. a tool produced by subagent(...) rather than a plain tool(...).","commonSituations":"A harness or test that iterates over definition.tools indiscriminately and builds an executor for each, including nested-agent tools; refactoring an agent to use subagents while keeping a custom harness bridge that predates them.","solutions":["Filter subagent tools out before building harness executors: definition.tools.filter(t => t.runtime?.kind !== \"subagent\")","Run subagent tools through the normal agent runtime (run/stream) instead of the harness bridge","Replace the subagent tool with a plain tool for the harness scenario if nested agent execution is not needed there"],"exampleFix":"// before\nfor (const t of definition.tools) {\n  executors[t.name] = createHarnessToolExecutor({ definition, tool: t, sandbox });\n}\n\n// after\nfor (const t of definition.tools) {\n  if (t.runtime?.kind === \"subagent\") continue;\n  executors[t.name] = createHarnessToolExecutor({ definition, tool: t, sandbox });\n}","handlingStrategy":"type-guard","validationCode":"const plainTools = definition.tools.filter(t => t.runtime?.kind !== \"subagent\");\n// build harness executors only for plainTools","typeGuard":"const isSubagentTool = (t: ToolDefinition): boolean =>\n  (t.runtime as { kind?: string } | undefined)?.kind === \"subagent\";","tryCatchPattern":null,"preventionTips":["Never feed definition.tools wholesale to the harness bridge","Keep harness scenarios on plain tool(...) definitions","Route subagent tools through the normal run/stream entry points only"],"tags":["harness","subagents","tools"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}