{"record":{"id":"c9a08db70c498201","repo":"JuliusBrussee/caveman","slug":"caveman-agent-unknown-tool-result-policy-json-s","errorCode":null,"errorMessage":"caveman agent: unknown tool result policy ${JSON.stringify(result)}","messagePattern":"caveman agent: unknown tool result policy (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/primitives.ts","lineNumber":138,"sourceCode":"export function tool<Input, Output, TResult>(\n  options: StandardJSONToolOptions<Input, Output, TResult>,\n): ToolDefinition<Output, TResult>;\nexport function tool(\n  options: ToolOptions<TSchema, unknown> |\n    StandardToolOptions<unknown, unknown, unknown> |\n    StandardJSONToolOptions<unknown, unknown, unknown>,\n): ToolDefinition<unknown, unknown> {\n  if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(options.name)) {\n    throw new Error(`caveman agent: invalid tool name ${JSON.stringify(options.name)}`);\n  }\n  if (![\"read\", \"write\", \"idempotent\", \"external\"].includes(options.effect)) {\n    throw new Error(`caveman agent: unknown tool effect ${JSON.stringify(options.effect)}`);\n  }\n  const result = typeof options.result === \"object\"\n    ? artifactResultPolicy(options.result)\n    : options.result ?? \"auto\";\n  if (![\"auto\", \"inline\", \"page\", \"compress\", \"exact_ccr\"].includes(result)) {\n    throw new Error(`caveman agent: unknown tool result policy ${JSON.stringify(result)}`);\n  }\n  const timeoutMs = options.timeoutMs ?? 30_000;\n  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {\n    throw new Error(\"caveman agent: tool timeoutMs must be a positive integer\");\n  }\n  const standard = standardToolSchema(options.input);\n  let input: TSchema;\n  if (standard === undefined) {\n    input = options.input as TSchema;\n  } else {\n    let converted = \"inputJSONSchema\" in options\n      ? options.inputJSONSchema\n      : undefined;\n    if (converted === undefined && standard.jsonSchema !== undefined) {\n      try {\n        converted = standard.jsonSchema.input({ target: \"draft-07\" });\n      } catch (error) {\n        throw new Error(\"caveman agent: Standard Schema cannot emit draft-07 input JSON Schema\", {","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/primitives.ts#L120-L156","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use one of the valid policies: \"auto\", \"inline\", \"page\", \"compress\", \"exact_ccr\"","Remove the result field entirely to get the \"auto\" default","Validate config-supplied result values against the allow-list before constructing the tool"],"exampleFix":"// before\ntool({ name: \"search\", result: \"compact\", ... })\n// after\ntool({ name: \"search\", result: \"compress\", ... })","handlingStrategy":"type-guard","validationCode":"const RESULT_POLICIES = [\"auto\", \"inline\", \"page\", \"compress\", \"exact_ccr\"] as const;\nfunction isResultPolicy(v: unknown): v is typeof RESULT_POLICIES[number] {\n  return (RESULT_POLICIES as readonly unknown[]).includes(v);\n}","typeGuard":"function isResultPolicy(v: unknown): v is \"auto\" | \"inline\" | \"page\" | \"compress\" | \"exact_ccr\" {\n  return [\"auto\", \"inline\", \"page\", \"compress\", \"exact_ccr\"].includes(v as never);\n}","tryCatchPattern":"try {\n  const def = tool(options);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"unknown tool result policy\")) {\n    // fall back to result: \"auto\"\n  } else throw err;\n}","preventionTips":["Omit result to use the \"auto\" default unless a policy is genuinely needed","Validate config-driven result values against the allow-list at load time","Reuse a single ResultPolicy union type across the codebase"],"tags":["validation","enum","tool-definition","configuration"],"backgroundTag":"invalid-enum-value","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}