JuliusBrussee/caveman · error · Error

cave_reserved_tool_name

cave_reserved_tool_name

Error message

cave_reserved_tool_name:${declared.name}

What it means

The `cave_` prefix is reserved for framework built-ins (such as `cave_retrieve`) so user tools can never shadow or impersonate them. `validateAgentGraph` rejects any user-declared tool whose name starts with `cave_`, including the offending name in the message.

Source

Thrown at packages/agent/src/definition-graph.ts:43

    // it to run closures outside an ancestor's required containment.
    if (sandboxRequired && definition.sandbox === "host") {
      throw new Error("cave_host_sandbox_nested_under_required");
    }
    const memo = visited[sandboxRequired ? 1 : 0]!;
    if (memo.has(definition)) return;
    active.add(definition);
    const childSandboxRequired = sandboxRequired ||
      definition.sandbox === "required";
    const names = new Set<string>();
    for (const declared of definition.tools) {
      if (!declared || declared.kind !== "tool" ||
          typeof declared.name !== "string") {
        throw new Error("cave_tool_definition_invalid");
      }
      if (names.has(declared.name)) throw new Error("cave_duplicate_tool_name");
      names.add(declared.name);
      if (declared.name.startsWith("cave_")) {
        throw new Error(`cave_reserved_tool_name:${declared.name}`);
      }
      if (typeof Reflect.get(declared, TOOL_IMPLEMENTATION_SOURCE) !== "string") {
        throw new Error(`cave_untrusted_tool_definition:${declared.name}`);
      }
      if (declared.runtime?.kind !== "subagent") continue;
      const child = declared.runtime.definition as AgentDefinition;
      visit(child, depth + 1, childSandboxRequired);
    }
    active.delete(definition);
    memo.add(definition);
  };

  visit(root, 0, false);
}

/**
 * True when any agent in the graph opts into host mode.
 *

View on GitHub (pinned to 766dce6b13)

Solutions

1. Rename the tool to drop the prefix (e.g. `cave_search` → `search` or `vault_search`).
2. If you intended built-in behavior like recovery retrieval, enable the built-in (`cave_retrieve` comes with the plan) rather than redeclaring it.

Example fix

// before
const search = tool({ name: "cave_search", ... });
// after
const search = tool({ name: "search", ... });

for (const name of definition.tools.map((declared) => declared.name)) {
  if (name.startsWith("cave_")) {
    throw new Error(`tool name "${name}" uses the reserved cave_ prefix`);
  }
}

When it happens

Trigger: Declaring a tool named `cave_search`, `cave_compress`, or anything starting with `cave_` in an agent definition's `tools` array.

Common situations: Naming tools after the framework's built-ins by convention ("cave_* means caveman-related tools"); wrapping a built-in and keeping its name; tutorial code that mimics internal tool names.

Related errors

• cave_duplicate_tool_name
• caveman agent: duplicate tool name
• caveman agent: tool prefix cave_ is reserved by framework ($
• strategy must be all or deferred
• initialToolCount must be a non-negative integer

AI-assisted analysis of JuliusBrussee/caveman@766dce6b13 (2026-08-18). Data as JSON: /api/errors/e77b9682c5c001c9. Report an issue: GitHub.