[FEATURE] Add Anthropic Advanced Tool Use beta support

[theslyprofessor]

Summary

Adds support for Anthropic's Advanced Tool Use beta features via feature flag.

Closes #4713

---

Motivation

OpenCode currently loads all MCP tool definitions upfront. For power users with multiple MCP servers, this creates high token costs (50K-100K+ tokens before any work begins).

Anthropic released beta features specifically designed to address this:

• 85% token reduction with Tool Search Tool
• 37% token reduction with Programmatic Tool Calling
• Significant accuracy improvements with Tool Use Examples

This PR adds the foundation for these capabilities.

---

Changes

Beta Header Support

Added OPENCODE_ADVANCED_TOOL_USE feature flag that enables the advanced-tool-use-2025-11-20 beta:

// packages/opencode/src/provider/provider.ts
const advancedToolUseEnabled = Env.all()["OPENCODE_ADVANCED_TOOL_USE"] === "true"

const betaFeatures = [
  "claude-code-20250219",
  "interleaved-thinking-2025-05-14",
  "fine-grained-tool-streaming-2025-05-14",
]

if (advancedToolUseEnabled) {
  betaFeatures.push("advanced-tool-use-2025-11-20")
}

Usage

export OPENCODE_ADVANCED_TOOL_USE=true
opencode

---

Breaking Changes

None. Feature flag defaults to false. Without the flag, OpenCode behaves exactly as before.

---

Testing

• ✅ Typecheck passes
• ✅ No breaking changes introduced
• ✅ Feature flag defaults to off (safe to merge)

---

Next Steps

This PR lays the foundation for:

1. Tool Search Tool - defer_loading config for MCP tools
2. Programmatic Tool Calling - Code execution sandbox
3. Tool Use Examples - input_examples in tool schemas

I can implement these in follow-up PRs if this approach is approved.

---

References

• Anthropic docs: https://www.anthropic.com/engineering/advanced-tool-use
• Issue [FEATURE]: Claude Advanced Tool Usage #4713: Feature request with community support
• Related: claude-code issue #12836 (100+ upvotes)

---

Author Notes

I'm a power user running OpenCode with 9+ MCP servers. This feature would save me 50K-70K tokens per session. Happy to implement the full feature set if this foundation is accepted.

Thanks for reviewing! 🚀

[github-actions]

Hey! Your PR title [FEATURE] Add Anthropic Advanced Tool Use beta support doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

[Copilot]

Pull request overview

This PR adds support for Anthropic's Advanced Tool Use beta features through a feature flag OPENCODE_ADVANCED_TOOL_USE. When enabled, it includes the advanced-tool-use-2025-11-20 beta header in Anthropic API requests, providing foundation for future token reduction features.

Key Changes:

• Adds OPENCODE_ADVANCED_TOOL_USE environment variable support
• Refactors hardcoded beta headers into a dynamic array
• Conditionally includes advanced tool use beta based on feature flag

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The feature flag should be defined in the Flag namespace (flag/flag.ts) using the truthy() helper function, consistent with other feature flags in the codebase. This approach provides a centralized location for all flags, makes them easier to discover, and follows the established pattern used by flags like OPENCODE_ENABLE_EXPERIMENTAL_MODELS, OPENCODE_DISABLE_CLAUDE_CODE, etc.

Suggested change

	const advancedToolUseEnabled = Env.all()["OPENCODE_ADVANCED_TOOL_USE"] === "true"
	const advancedToolUseEnabled = Flag.truthy("OPENCODE_ADVANCED_TOOL_USE")

[Copilot]

This comment is redundant with the comment on line 76. Consider removing one of them to reduce duplication.

Suggested change

// Add advanced tool use beta if enabled