feat: add opt-in provider web search

[tomdps]

Summary

• add strict, registry-derived providerSettings.codex.webSearch and providerSettings.opencode.webSearch booleans, both defaulting to false
• dynamically attest local CLI control support while keeping requested and effective state distinct in runtime probe and executable build output
• apply native search controls to fresh and resumed commands, including isolated child settings projection
• fail closed with an actionable unsupported-capability error when explicitly enabled search cannot be proven; preserve that structured permanent fault through host and isolated task-start wrappers so lifecycle retry logic terminalizes it

Closes #859

Exact behavior

Codex

Enabled commands use the upstream noninteractive control:

codex exec --config 'web_search="live"' ...
codex exec --config 'web_search="live"' resume SESSION_ID ...

Support requires nonempty codex exec --help output containing --config and a parseable Codex version >= 0.146.0. Missing, malformed, older, or help-incompatible installations are unsupported. Absent/false settings add no arguments and do not trigger search-specific probing when caller-supplied feature metadata is otherwise sufficient.

This intentionally does not emit codex exec --search: current upstream ExecCli rejects that argument, and the top-level TUI --search flag is not translated into noninteractive exec configuration. Codex's TypeScript SDK emits --config 'web_search="live"' before both fresh prompts and resume:

• https://github.com/openai/codex/blob/main/sdk/typescript/src/exec.ts
• https://github.com/openai/codex/blob/main/codex-rs/cli/src/main.rs
• https://github.com/openai/codex/blob/main/codex-rs/exec/src/cli.rs

OpenCode

Enabled fresh and resumed commands receive OPENCODE_ENABLE_EXA=1; unrelated environment entries are retained. Support requires a parseable OpenCode version >= 1.0.137. Missing, malformed, or older versions are unsupported.

Upstream sources:

• https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/effect/runtime-flags.ts
• https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/tool/registry.ts

Scope matrix

Provider	Declared setting	Additive control	Support proof
Codex	providerSettings.codex.webSearch	--config 'web_search="live"'	nonempty exec help with --config + version >= 0.146.0
OpenCode	providerSettings.opencode.webSearch	OPENCODE_ENABLE_EXA=1	version >= 1.0.137
Claude, Gemini, Kiro, Copilot, Pi, Gateway	unsupported; field rejected	none established	none established

Permission/tool allowlists authorize tools already present; they are not treated as controls that enable search. Probes attest only installed CLI support, not account, backend, network, or browser/API reachability.

Files changed

• AGENTS.md
• cli/commands/providers.js
• cli/index.js
• docs/providers.md
• src/agent-cli-provider/adapters/codex.ts
• src/agent-cli-provider/adapters/common.ts
• src/agent-cli-provider/adapters/index.ts
• src/agent-cli-provider/adapters/opencode.ts
• src/agent-cli-provider/contract-actions.ts
• src/agent-cli-provider/contract-fallback.ts
• src/agent-cli-provider/contract-options.ts
• src/agent-cli-provider/errors.ts
• src/agent-cli-provider/index.ts
• src/agent-cli-provider/provider-registry.ts
• src/agent-cli-provider/single-agent-runtime.ts
• src/agent-cli-provider/types.ts
• src/providers/index.js
• src/task-run-model-args.js
• src/task-spawn-cleanup-ownership.js
• src/task-startup-error.js
• tests/agent-cli-provider/executable-contract-build.test.js
• tests/agent-cli-provider/executable-contract-option-validation.test.js
• tests/agent-cli-provider/parity.test.js
• tests/agent-cli-provider/providers-command-parity.test.js
• tests/isolated-task-launch-recovery.test.js
• tests/opencode-docker-settings-boundary.test.js
• tests/provider-cli-builder.test.js
• tests/settings-providers.test.js
• tests/unit/task-startup-capability-error.test.js

Focused checks for supervisor

Not run, per request:

npm run build:agent-cli-provider
npx mocha tests/provider-cli-builder.test.js tests/settings-providers.test.js tests/opencode-docker-settings-boundary.test.js tests/isolated-task-launch-recovery.test.js tests/unit/task-startup-capability-error.test.js
npx mocha tests/agent-cli-provider/executable-contract-build.test.js tests/agent-cli-provider/executable-contract-option-validation.test.js tests/agent-cli-provider/parity.test.js tests/agent-cli-provider/providers-command-parity.test.js
npx eslint cli/index.js cli/commands/providers.js src/agent-cli-provider src/providers/index.js src/task-run-model-args.js src/task-spawn-cleanup-ownership.js src/task-startup-error.js tests/provider-cli-builder.test.js tests/settings-providers.test.js tests/opencode-docker-settings-boundary.test.js tests/isolated-task-launch-recovery.test.js tests/unit/task-startup-capability-error.test.js tests/agent-cli-provider/*.test.js
npx prettier --check AGENTS.md docs/providers.md cli/index.js cli/commands/providers.js src/agent-cli-provider src/providers/index.js src/task-run-model-args.js src/task-spawn-cleanup-ownership.js src/task-startup-error.js tests/provider-cli-builder.test.js tests/settings-providers.test.js tests/opencode-docker-settings-boundary.test.js tests/isolated-task-launch-recovery.test.js tests/unit/task-startup-capability-error.test.js tests/agent-cli-provider/*.test.js
npm test

No live model API, browser/API reachability, gateway, retry, or telemetry checks are required.

[greptile-apps]

Greptile Summary

Adds opt-in, registry-derived native web-search controls for Codex and OpenCode.

• Attests support from local CLI help and version output and distinguishes requested from effective state.
• Applies search controls to fresh, resumed, hosted, and isolated task launches.
• Propagates unsupported-capability startup failures as permanent lifecycle faults.
• Extends provider settings, documentation, and parity/recovery coverage.

Confidence Score: 4/5

The PR is not yet safe to merge because an OpenCode continuation caller can still bypass local resume attestation with a supplied feature override.

The earlier empty-help detection defect is fixed, but the separate resume-override thread remains unresolved: with web search absent or false, runtime feature resolution returns caller overrides unchanged, allowing supportsResume: true to emit --session or --continue on an installation whose help output does not prove those controls.

Files Needing Attention: src/agent-cli-provider/single-agent-runtime.ts, src/agent-cli-provider/adapters/opencode.ts

Important Files Changed

Filename	Overview
src/agent-cli-provider/single-agent-runtime.ts	Adds web-search setting resolution, runtime support attestation, and requested/effective configuration reporting.
src/agent-cli-provider/adapters/codex.ts	Adds version-and-help-gated Codex web-search configuration for fresh and resumed commands.
src/agent-cli-provider/adapters/opencode.ts	Adds OpenCode web-search environment control, strict continuation detection, and session argument construction.
src/task-startup-error.js	Adds structured serialization and preservation of unsupported provider-capability startup failures.
src/agent-cli-provider/provider-registry.ts	Declares registry-owned web-search settings and static capability metadata for Codex and OpenCode.
docs/providers.md	Documents opt-in web-search settings, minimum CLI versions, control mechanisms, and fail-closed behavior.

_{Reviews (11): Last reviewed commit: "fix: preserve only structured startup fa..." | Re-trigger Greptile}

[github-actions]

🎉 This PR is included in version 6.16.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀