[FEATURE]: Add hidden field to tool.definition hook output for tool suppression #23297

Problem

The tool.definition hook allows plugins to modify tool descriptions and parameters, but cannot remove tools from the LLM's tool list entirely. This means deferred/lazy tool loading plugins (like opencode-tool-search) must still send stub entries for every deferred tool, wasting ~10-20 tokens per tool per turn.

With 180+ tools, that's ~2,000-3,600 tokens of overhead per turn that could be eliminated.

Proposed solution

Add an optional hidden boolean to the tool.definition hook output:

"tool.definition"?: (input: {
    toolID: string;
}, output: {
    description: string;
    parameters: any;
    hidden?: boolean;  // NEW — when true, tool is excluded from the LLM tool list
}) => Promise<void>;

On the Go side, the change is minimal — skip the tool when building the tool list if output.Hidden is true:

// In resolveTools or equivalent:
if hookOutput.Hidden {
    continue
}

Why this matters

• The famitzsy8/opencode-tool-search-tool fork proves this pattern works by modifying prompt.ts → resolveTools() to filter deferred tools. This proposal brings the same capability to the plugin API.
• Anthropic's native defer_loading: true API already supports this pattern server-side. This hook enhancement would let plugins implement equivalent behavior client-side.
• Multiple community PRs (feat: add mcp_lazy mode for on-demand MCP tool loading #8771, feat: mcp-search tool for lazy loading mcp #12520) and issues ([FEATURE]:Add mcp search tool, reduce mcp tool occupying a lot of context #8625, [FEATURE]: Claude-style Tool Search Tool Implementation in OpenCode #9461, Feature Request: Two-Step MCP Tool Discovery for On-Demand Loading #16206) request lazy tool loading. A hidden field on the hook is the minimal change that unblocks plugin-based solutions without core changes.

Alternatives considered

• Modifying description to a short stub: Already implemented in opencode-tool-search, but each tool still costs ~10-20 tokens for its name + minimal schema. The hidden field eliminates this entirely.
• Separate tool.filter hook: More complex; a single boolean field on the existing hook is simpler and sufficient.

Related

• [FEATURE]: pass sessionID into tool.definition hooks #17334 — Pass sessionID into tool.definition hooks
• [FEATURE]: Pass sessionID, model, and agent info to tool.definition hook #17954 — Pass sessionID, model, and agent info to tool.definition hook
• feat: add mcp_lazy mode for on-demand MCP tool loading #8771, feat: mcp-search tool for lazy loading mcp #12520 — mcp_lazy mode PRs
• [FEATURE]:Add mcp search tool, reduce mcp tool occupying a lot of context #8625, [FEATURE]: Claude-style Tool Search Tool Implementation in OpenCode #9461, Feature Request: Two-Step MCP Tool Discovery for On-Demand Loading #16206 — Feature requests for lazy/deferred tool loading