Repository navigation
feat(v2): configure tool availability per session #35647
Description
Summary
V2 needs a public API and generated SDK surface for enabling or disabling tools for a specific Session. Today tool definitions are filtered by the selected Agent’s configured permissions, but neither the Session API nor the prompt API can apply Session-specific tool availability.
V1 behavior
V1 accepted a tool map on session.prompt(...):
await client.session.prompt({
sessionID,
tools: {
bash: false,
write: false,
},
})The implementation translated those entries into permission rules and persisted them on the Session. This provided the capability, but the contract was misleading: a field on one prompt mutated durable Session configuration. The field is now deprecated in V1.
V2 gap
PromptInput.Promptcontains only text and attachments.Session.Infohas no Session-specific tool or permission configuration.ToolRegistry.materialize(...)receives only the selected Agent’s permission rules.- SDK consumers cannot create a restricted Session without defining a separate Agent in configuration.
Desired behavior
Provide an explicit Session-scoped API for tool availability, exposed through Protocol and generated clients. The common SDK use case should be straightforward:
await client.session.configure({
sessionID,
tools: {
bash: false,
write: false,
},
})The exact endpoint and representation need design. In particular, decide:
- Whether this is a tool-specific allow/deny map or a Session permission ruleset.
- How Session rules compose with Agent permissions and built-in tool permission actions.
- Whether changes are durable Session configuration, scoped to one admitted prompt, or whether both concepts are needed.
- Whether consumers can inspect the effective tool catalog after composition.
Non-goal
Do not restore V1’s implicit behavior where sending a prompt silently mutates persistent Session configuration.
Activity
opencode-agent commentedon Jul 8, 2026
Active implementation: V2 PR #35691.
marwenchaabouni commentedon Oct 14, 2026
A practical use case for session-scoped MCP configuration:
I often work with multiple OpenCode chats in parallel, each requiring different MCP servers. For example, one chat may need Granola for meeting notes, while another needs Firecrawl for web research.
Currently, keeping the required MCPs enabled means that unrelated tool definitions may also be included in the context of chats that do not need them. Switching MCPs manually is inconvenient when moving between parallel tasks, and it undermines the benefit of having separate chats.
Expected behavior: Each chat/session should be able to select which MCP servers are exposed to the model, independently of other open sessions. Ideally, this selection should persist with the session.
This would reduce unnecessary context consumption and make MCP management more practical for users who maintain several task-specific conversations.
Would session-scoped MCP selection be covered by this issue, or is it outside the current implementation scope? I would be interested in contributing if there is a defined direction for the UI or API.
P.S. This becomes even more relevant when working with multiple MCP servers across several chats simultaneously, as the unnecessary context overhead can accumulate across different tasks.
opencodejr commentedon Oct 28, 2026
Thanks for writing this up. I checked the current
devcode (77a0fd6). As described, v2 has no Session-scoped way to configure which tools are available:PromptInput.Promptcarries only text and attachments, and tool availability comes from the selected Agent's permissions. This is how v2 is currently designed, not a bug, so there's nothing to reproduce. It's better tracked as feature work. The open design questions you listed (an allow/deny map versus a permission ruleset, how Session rules compose with Agent rules, durable versus per-prompt scope, and inspecting the effective tool catalog) are the next step.neriousy commentedon Nov 12, 2026
Closing as completed by #48351.
session.createandsession.updateacceptpermissions, and a session's rules apply after the agent's. A session rule that denies a tool for all resources removes that tool from the model's tool list, for example:{ "permissions": [{ "action": "bash", "resource": "*", "effect": "deny" }] }Wildcards work too, so one MCP server's tools can be hidden for a single session. Two things are still missing: a
tools: { bash: false }shorthand on the prompt, and a way to see a session's effective tool list. Please open a new issue for either one if you need it.