JuliusBrussee/caveman · error

cave_sandbox_subagent_definition_invalid

cave_sandbox_subagent_definition_invalid

Error message

cave_sandbox_subagent_definition_invalid

What it means

After locating exactly one subagent tool for the current agentPath name, the worker reads `runtime.definition` as the child AgentDefinition. If that child is missing/null or its `kind` is not "agent", the worker throws `cave_sandbox_subagent_definition_invalid`. A subagent's runtime must embed a complete, well-kinded agent definition for the walk to continue.

Solutions

1. Attach the fully built child AgentDefinition to the subagent tool's runtime.definition.
2. Ensure the child object has `kind: "agent"` (built via the agent builder, not a raw tool or partial object).
3. Pass the built definition object itself, not a name/id reference, when constructing the subagent runtime.
4. Run graph validation (validateAgentGraph) locally before building to catch malformed nested definitions early.

Example fix

// before
runtime: { kind: "subagent", definition: "child-agent" as unknown as AgentDefinition }

// after
runtime: { kind: "subagent", definition: childAgentDefinition }

function childDefinitionIsValid(tool: { runtime?: { kind?: string; definition?: unknown } }): boolean {
  const child = tool.runtime?.definition as AgentDefinition | undefined;
  return Boolean(child && (child as { kind?: string }).kind === "agent");
}
// run over every subagent tool before building

const isAgentDefinition = (v: unknown): v is AgentDefinition =>
  typeof v === "object" && v !== null && (v as { kind?: string }).kind === "agent";

When it happens

Trigger: A subagent tool's `runtime.definition` is undefined (built with a reference that was never resolved), points at an object with a different `kind` (e.g. a tool or workflow), or was replaced by a non-definition value (function, string id).

Common situations: Hand-assembling a subagent runtime without attaching the child definition; passing a string identifier instead of the built child agent; TypeScript `as AgentDefinition` hiding a wrong-shaped object; serialization stripping nested definitions.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• cave_sandbox_unknown_subagent
• cave_sandbox_agent_export_missing
• cave_sandbox_request_invalid
• cave_sandbox_subagent_cycle
• cave_sandbox_unknown_tool

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/71c77f7604a04fad. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/tool-worker.ts:119

    throw new Error("cave_sandbox_request_invalid");
  }
  if (request.allowNetwork !== true) installNetworkDeny();
  const imported = await import(request.entry) as { default?: AgentDefinition; agent?: AgentDefinition };
  let definition = imported.default ?? imported.agent;
  if (!definition || definition.kind !== "agent") throw new Error("cave_sandbox_agent_export_missing");
  validateAgentGraph(definition);
  if (agentDefinitionSHA256(definition) !== request.rootDefinitionSha256) {
    throw new Error("cave_sandbox_definition_mismatch");
  }
  const visited = new Set<AgentDefinition>([definition]);
  for (const name of request.agentPath) {
    const delegated = definition.tools.filter((item) =>
      item.name === name && item.runtime?.kind === "subagent"
    );
    if (delegated.length !== 1) throw new Error("cave_sandbox_unknown_subagent");
    const child = delegated[0]!.runtime!.definition as AgentDefinition;
    if (!child || child.kind !== "agent") {
      throw new Error("cave_sandbox_subagent_definition_invalid");
    }
    if (visited.has(child)) throw new Error("cave_sandbox_subagent_cycle");
    visited.add(child);
    definition = child;
  }
  const selectedTools = definition.tools.filter((item) => item.name === request.tool);
  if (selectedTools.length !== 1 || selectedTools[0]!.runtime?.kind === "subagent") {
    throw new Error("cave_sandbox_unknown_tool");
  }
  const selected = selectedTools[0]!;
  if (toolDefinitionSHA256(selected) !== request.toolDefinitionSha256) {
    throw new Error("cave_sandbox_tool_definition_mismatch");
  }
  if (selected.effect !== "read" && request.allowSideEffects !== true) {
    throw new Error("cave_sandbox_side_effect_denied");
  }
  const value = await selected.execute(request.params as never, AbortSignal.timeout(selected.timeoutMs));
  writeResult({ ok: true, value });

View on GitHub (pinned to 3ee70a1026)