{"record":{"id":"46a5e49ac939f1da","repo":"vercel/ai","slug":"harness-codex-does-not-support-built-in-tool-fil","errorCode":null,"errorMessage":"Harness 'codex' does not support built-in tool filtering controls.","messagePattern":"Harness 'codex' does not support built-in tool filtering controls\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-codex/src/codex-harness.ts","lineNumber":210,"sourceCode":"  sandboxCredentialEnvironment: z.record(z.string(), z.string()).optional(),\n});\n\ntype CodexBridgeCoords = z.infer<typeof codexBridgeCoordsSchema>;\n\nexport function createCodex(\n  settings: CodexHarnessSettings = {},\n): HarnessV1<typeof CODEX_BUILTIN_TOOLS> {\n  return {\n    specificationVersion: 'harness-v1',\n    harnessId: 'codex',\n    builtinTools: CODEX_BUILTIN_TOOLS,\n    supportsBuiltinToolApprovals: false,\n    lifecycleStateSchema: codexResumeStateSchema,\n    getBootstrap: getCodexBootstrap,\n    doStart: async startOpts => {\n      const model = settings.model ?? DEFAULT_CODEX_MODEL;\n      if (startOpts.builtinToolFiltering != null) {\n        throw new HarnessCapabilityUnsupportedError({\n          message:\n            \"Harness 'codex' does not support built-in tool filtering controls.\",\n          harnessId: 'codex',\n        });\n      }\n      if (\n        startOpts.permissionMode != null &&\n        startOpts.permissionMode !== 'allow-all'\n      ) {\n        throw new HarnessCapabilityUnsupportedError({\n          message:\n            \"Harness 'codex' does not support built-in tool approval requests; use permissionMode: 'allow-all'.\",\n          harnessId: 'codex',\n        });\n      }\n      const sandboxSession = startOpts.sandboxSession;\n      const toolSafeSandboxSession =\n        getRestrictedSandboxSession(sandboxSession);","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-codex/src/codex-harness.ts#L192-L228","documentation":"The codex harness declares supportsBuiltinToolFiltering: false. If doStart receives startOpts.builtinToolFiltering (an attempt to enable/disable built-in tools like web search), it throws HarnessCapabilityUnsupportedError because the harness cannot forward those controls to the Codex CLI.","triggerScenarios":"Calling createCodex(...).start({ builtinToolFiltering: {...} }) or passing builtinToolFiltering in start options with any non-null value.","commonSituations":"Shared harness abstraction code that uniformly passes builtinToolFiltering to every harness; switching from a harness that supports filtering (e.g. claude) to codex without changing start options.","solutions":["Remove builtinToolFiltering from the start options when using the codex harness.","Control built-in tools via Codex-native configuration (config.toml / CLI flags) instead.","Feature-detect harness capabilities before setting filtering options."],"exampleFix":"// before\nharness.start({ builtinToolFiltering: { exclude: ['web_search'] } });\n// after\nharness.start({}); // configure built-in tools in codex config instead","handlingStrategy":"validation","validationCode":"if (startOpts?.builtinToolFiltering != null) {\n  throw new Error('codex harness: remove builtinToolFiltering from start options');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await harness.start(startOpts);\n} catch (e) {\n  if (/does not support built-in tool filtering/.test(String(e?.message))) {\n    // retry without builtinToolFiltering\n  } else throw e;\n}","preventionTips":["Check harness capability flags before setting start options","Keep harness-specific options out of shared start-option builders","Configure built-in tools through codex config files instead"],"tags":["harness-codex","unsupported-capability","tool-filtering","start-options"],"backgroundTag":"unsupported-capability","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}