{"record":{"id":"71c77f7604a04fad","repo":"JuliusBrussee/caveman","slug":"cave-sandbox-subagent-definition-invalid","errorCode":"cave_sandbox_subagent_definition_invalid","errorMessage":"cave_sandbox_subagent_definition_invalid","messagePattern":"cave_sandbox_subagent_definition_invalid","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/tool-worker.ts","lineNumber":119,"sourceCode":"    throw new Error(\"cave_sandbox_request_invalid\");\n  }\n  if (request.allowNetwork !== true) installNetworkDeny();\n  const imported = await import(request.entry) as { default?: AgentDefinition; agent?: AgentDefinition };\n  let definition = imported.default ?? imported.agent;\n  if (!definition || definition.kind !== \"agent\") throw new Error(\"cave_sandbox_agent_export_missing\");\n  validateAgentGraph(definition);\n  if (agentDefinitionSHA256(definition) !== request.rootDefinitionSha256) {\n    throw new Error(\"cave_sandbox_definition_mismatch\");\n  }\n  const visited = new Set<AgentDefinition>([definition]);\n  for (const name of request.agentPath) {\n    const delegated = definition.tools.filter((item) =>\n      item.name === name && item.runtime?.kind === \"subagent\"\n    );\n    if (delegated.length !== 1) throw new Error(\"cave_sandbox_unknown_subagent\");\n    const child = delegated[0]!.runtime!.definition as AgentDefinition;\n    if (!child || child.kind !== \"agent\") {\n      throw new Error(\"cave_sandbox_subagent_definition_invalid\");\n    }\n    if (visited.has(child)) throw new Error(\"cave_sandbox_subagent_cycle\");\n    visited.add(child);\n    definition = child;\n  }\n  const selectedTools = definition.tools.filter((item) => item.name === request.tool);\n  if (selectedTools.length !== 1 || selectedTools[0]!.runtime?.kind === \"subagent\") {\n    throw new Error(\"cave_sandbox_unknown_tool\");\n  }\n  const selected = selectedTools[0]!;\n  if (toolDefinitionSHA256(selected) !== request.toolDefinitionSha256) {\n    throw new Error(\"cave_sandbox_tool_definition_mismatch\");\n  }\n  if (selected.effect !== \"read\" && request.allowSideEffects !== true) {\n    throw new Error(\"cave_sandbox_side_effect_denied\");\n  }\n  const value = await selected.execute(request.params as never, AbortSignal.timeout(selected.timeoutMs));\n  writeResult({ ok: true, value });","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/tool-worker.ts#L101-L137","documentation":"After selecting the subagent tool by name, the worker reads `runtime.definition` and requires it to be a truthy object with `kind === \"agent\"`. This error means the subagent tool was declared with runtime.kind \"subagent\" but its embedded definition is missing or not actually an agent definition.","triggerScenarios":"Constructing a subagent runtime manually with `definition: undefined` or a plain options object lacking kind:\"agent\"; a serialization round-trip that dropped the definition; passing a tool object where a definition was expected.","commonSituations":"Hand-rolling runtime objects instead of using the framework's subagent() builder; type assertions (`as AgentDefinition`) hiding an undefined; partial object spread that omits the definition key.","solutions":["Build subagent tools with the framework helper (e.g. subagent(name, definition)) so runtime.definition is always a validated AgentDefinition.","If constructing manually, assert the embedded object has kind:\"agent\", tools array, and required fields before spawning.","Run validateAgentGraph on the root definition in the parent to catch this before the worker does."],"exampleFix":"// before\ntool({ name: \"child\", runtime: { kind: \"subagent\", definition: childOptions as any } })\n\n// after\ntool({ name: \"child\", runtime: { kind: \"subagent\", definition: agent({ tools: childTools }) } })","handlingStrategy":"type-guard","validationCode":"for (const t of def.tools) {\n  if (t.runtime?.kind === \"subagent\") {\n    const child = t.runtime.definition;\n    if (!child || child.kind !== \"agent\") throw new Error(`subagent ${t.name} has invalid definition`);\n  }\n}","typeGuard":"function isValidSubagentRuntime(rt: unknown): rt is { kind: \"subagent\"; definition: AgentDefinition } {\n  const r = rt as { kind?: unknown; definition?: { kind?: unknown } } | undefined;\n  return !!r && r.kind === \"subagent\" && !!r.definition && r.definition.kind === \"agent\";\n}","tryCatchPattern":null,"preventionTips":["Always build subagent tools via the framework helper, never hand-assembled runtime objects.","Run validateAgentGraph(root) in the parent; it catches malformed nested definitions pre-spawn."],"tags":["sandbox","subagent","type-safety","cave"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}