{"record":{"id":"568d06b73fad38a5","repo":"JuliusBrussee/caveman","slug":"cave-tool-sandbox-entry-required","errorCode":"cave_tool_sandbox_entry_required","errorMessage":"cave_tool_sandbox_entry_required: sandboxed tools need entryPath","messagePattern":"cave_tool_sandbox_entry_required: sandboxed tools need entryPath","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":886,"sourceCode":"\n/** Package-internal harness bridge. Not exported from package entry point. */\nexport interface HarnessToolSandbox {\n  readonly stagingRoot?: string;\n  readonly entryPath?: string;\n  readonly sourceFiles: readonly string[];\n  readonly executionContext: InternalExecutionContext;\n  dispose(): Promise<void>;\n}\n\n/** Package-internal harness bridge. Stages one immutable source graph. */\nexport async function prepareHarnessToolSandbox(\n  definition: AgentDefinition,\n  options: Pick<RunOptions, \"rootDir\" | \"entryPath\">,\n): Promise<HarnessToolSandbox> {\n  const executionContext = rootExecutionContext(definition);\n  if (options.entryPath === undefined &&\n      requiresSandboxEntry(definition, executionContext.sandboxRequired)) {\n    throw new Error(\n      \"cave_tool_sandbox_entry_required: sandboxed tools need entryPath\",\n    );\n  }\n  if (options.entryPath === undefined) {\n    return {\n      sourceFiles: Object.freeze([]),\n      executionContext,\n      async dispose() {},\n    };\n  }\n  const rootDir = options.rootDir ?? process.cwd();\n  const requested = resolve(rootDir, options.entryPath);\n  const snapshot = await stageSandboxSourceGraph(\n    rootDir,\n    requested,\n    dirname(fileURLToPath(import.meta.url)),\n  );\n  return {","sourceCodeStart":868,"sourceCodeEnd":904,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/runtime.ts#L868-L904","documentation":"prepareHarnessToolSandbox requires an entryPath when the agent definition's sandbox mode demands one (requiresSandboxEntry given sandboxRequired). Sandboxed tools must know which entry module to stage and execute.","triggerScenarios":"Calling sandbox() (prepareHarnessToolSandbox) with options.entryPath undefined while the definition requires a sandbox entry (definition.sandbox === 'required' or executionContext.sandboxRequired).","commonSituations":"Forgetting to pass entryPath in run options after enabling sandbox: 'required'; renaming/moving the entry file so config loses the path; examples/docs updated to require entryPath after a version change.","solutions":["Pass entryPath pointing to the tool's entry module in the run/sandbox options.","Set definition.sandbox to a mode that doesn't require an entry if sandboxing isn't needed.","Fix the config so the entry path is resolved relative to the correct rootDir.","Check requiresSandboxEntry to understand when entryPath is mandatory."],"exampleFix":"// before\nawait sandbox(definition, { rootDir: \"/app\" });\n// after\nawait sandbox(definition, { rootDir: \"/app\", entryPath: \"/app/tools/main.ts\" });","handlingStrategy":"validation","validationCode":"if (definition.sandbox === \"required\" && options.entryPath === undefined) {\n  throw new Error(\"sandboxed tools need entryPath\");\n}","typeGuard":"const needsEntryPath = (d: AgentDefinition, o: { entryPath?: string }): boolean =>\n  o.entryPath === undefined && d.sandbox === \"required\";","tryCatchPattern":"try {\n  const sbx = await sandbox(definition, options);\n} catch (e) {\n  if (e.message.startsWith(\"cave_tool_sandbox_entry_required\")) {\n    console.error(\"Provide options.entryPath for sandboxed tool definitions\");\n  } else throw e;\n}","preventionTips":["Always set entryPath in run options when sandbox: 'required'.","Resolve entryPath relative to rootDir once in a shared config helper.","Update sandbox mode and options together when changing sandbox settings."],"tags":["sandbox","missing-argument","configuration"],"backgroundTag":"missing-required-option","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"}