JuliusBrussee/caveman · error

caveman agent: unknown tool result policy

Error message

caveman agent: unknown tool result policy ${JSON.stringify(result)}

What it means

tool() resolves the result policy from options.result (or artifactResultPolicy when given an object), defaulting to "auto", then requires it to be one of ["auto", "inline", "page", "compress", "exact_ccr"]. An unrecognized policy string is rejected because the runtime would not know how to shape the tool output.

Solutions

1. Use one of the valid policies: "auto", "inline", "page", "compress", "exact_ccr"
2. Remove the result field entirely to get the "auto" default
3. Validate config-supplied result values against the allow-list before constructing the tool

Example fix

// before
tool({ name: "search", result: "compact", ... })
// after
tool({ name: "search", result: "compress", ... })

const RESULT_POLICIES = ["auto", "inline", "page", "compress", "exact_ccr"] as const;
function isResultPolicy(v: unknown): v is typeof RESULT_POLICIES[number] {
  return (RESULT_POLICIES as readonly unknown[]).includes(v);
}

function isResultPolicy(v: unknown): v is "auto" | "inline" | "page" | "compress" | "exact_ccr" {
  return ["auto", "inline", "page", "compress", "exact_ccr"].includes(v as never);
}

try {
  const def = tool(options);
} catch (err) {
  if (err instanceof Error && err.message.includes("unknown tool result policy")) {
    // fall back to result: "auto"
  } else throw err;
}

When it happens

Trigger: tool({ result: "summarize" }) or any string outside the five allowed policies; an object result handled by artifactResultPolicy that itself resolves to an invalid policy value.

Common situations: Guessing policy names instead of consulting the API (e.g. "truncated", "compact"); older docs/configs using removed policy names; passing a user-supplied string from configuration straight into result.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• bedrock endpoint must be runtime or mantle
• caveman agent: unknown tool effect
• strategy must be all or deferred
• apiKey, baseURL, and agent are required
• ASGI context resolver or request bounds are invalid

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

Appendix: source

Thrown at packages/agent/src/primitives.ts:138

export function tool<Input, Output, TResult>(
  options: StandardJSONToolOptions<Input, Output, TResult>,
): ToolDefinition<Output, TResult>;
export function tool(
  options: ToolOptions<TSchema, unknown> |
    StandardToolOptions<unknown, unknown, unknown> |
    StandardJSONToolOptions<unknown, unknown, unknown>,
): ToolDefinition<unknown, unknown> {
  if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(options.name)) {
    throw new Error(`caveman agent: invalid tool name ${JSON.stringify(options.name)}`);
  }
  if (!["read", "write", "idempotent", "external"].includes(options.effect)) {
    throw new Error(`caveman agent: unknown tool effect ${JSON.stringify(options.effect)}`);
  }
  const result = typeof options.result === "object"
    ? artifactResultPolicy(options.result)
    : options.result ?? "auto";
  if (!["auto", "inline", "page", "compress", "exact_ccr"].includes(result)) {
    throw new Error(`caveman agent: unknown tool result policy ${JSON.stringify(result)}`);
  }
  const timeoutMs = options.timeoutMs ?? 30_000;
  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
    throw new Error("caveman agent: tool timeoutMs must be a positive integer");
  }
  const standard = standardToolSchema(options.input);
  let input: TSchema;
  if (standard === undefined) {
    input = options.input as TSchema;
  } else {
    let converted = "inputJSONSchema" in options
      ? options.inputJSONSchema
      : undefined;
    if (converted === undefined && standard.jsonSchema !== undefined) {
      try {
        converted = standard.jsonSchema.input({ target: "draft-07" });
      } catch (error) {
        throw new Error("caveman agent: Standard Schema cannot emit draft-07 input JSON Schema", {

View on GitHub (pinned to 3ee70a1026)