{"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":"Error","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/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/primitives.ts#L120-L156","documentation":"The tool result policy controls how tool output is returned to the model: \"auto\", \"inline\", \"page\", \"compress\", or \"exact_ccr\". tool() accepts either a string policy or an object (an artifact policy normalized via artifactResultPolicy). After normalization, anything outside the five allowed strings throws 'unknown tool result policy'.","triggerScenarios":"Passing result: \"summary\", \"stream\", \"text\", null, or a misspelled option like \"compres\". Also fires when artifactResultPolicy returns a non-allowed string for the object form.","commonSituations":"Assuming an arbitrary string is forwarded verbatim, upgrading from an older version that supported a since-removed policy name (e.g. a renamed paging mode), or copy-pasting docs from a different major version.","solutions":["Use one of the five literals; omit result to get the default \"auto\"","Choose deliberately: small outputs -> \"inline\"; large outputs -> \"page\"; context-sensitive shrinking -> \"compress\"; byte-exact capture -> \"exact_ccr\"","After upgrading the package, grep your codebase for result: and re-check each value against the current allowed list"],"exampleFix":"// before\nconst t = tool({ name: \"search\", effect: \"read\", result: \"summary\", execute: ... });\n\n// after\nconst t = tool({ name: \"search\", effect: \"read\", result: \"compress\", execute: ... });","handlingStrategy":"validation","validationCode":"const POLICIES = [\"auto\", \"inline\", \"page\", \"compress\", \"exact_ccr\"];\nif (cfg.result !== undefined && !POLICIES.includes(cfg.result)) {\n  throw new Error(`result policy must be one of ${POLICIES.join(\", \")}, got ${JSON.stringify(cfg.result)}`);\n}","typeGuard":"type ResultPolicy = \"auto\" | \"inline\" | \"page\" | \"compress\" | \"exact_ccr\";\nconst isResultPolicy = (v: unknown): v is ResultPolicy =>\n  typeof v === \"string\" && [\"auto\", \"inline\", \"page\", \"compress\", \"exact_ccr\"].includes(v);","tryCatchPattern":null,"preventionTips":["Omit result when unsure — the \"auto\" default is correct for most tools","Re-check the allowed policy list after every major-version upgrade of this package","Type result as the literal union in your tool helpers"],"tags":["validation","result-policy","api-misuse","versioning"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}