V2: improve tool search namespaces and reduce tool-context cache busts #36196

Activity

1. opencode-agent

   assigned

   kitlangton

   on Jul 10, 2026
2. opencode-agent

   added

   2.0

   on Jul 10, 2026
3. opencode-agent commented on Jul 10, 2026

   

   opencode-agentBot

   on Jul 10, 2026 – with OpenCode Agent

   ContributorAuthor

   More actions

   Design direction agreed in Slack gang grill (2026-07-10)

   Source: https://slack.com/archives/C0BE69AHCQP/p1783709543707769

   The group agreed to proceed without prematurely optimizing storage:

   • Tools are canonical capabilities; ordinary tool authors need not know CodeMode exists.
   • Visible tools default into CodeMode. Exceptional provider-level tools opt out with codemode: false; execute itself opts out to avoid recursion.
   • Public Promise and Effect tool drafts should support flat definitions through draft.add({ ... }), without requiring Tool.make(...) in normal usage.
   • namespace?: string, codemode?: boolean, and pinned?: boolean are first-class Tool-definition fields.
   • Namespace paths use validated dotted strings for nesting, e.g. slack.admin.users; do not silently sanitize segments.
   • Optional namespace metadata is additive (draft.namespace.add(...)). A namespaced tool implicitly creates its namespace when no metadata was registered.
   • MCP server names naturally become namespaces. MCP server instructions remain their existing Instruction source rather than being treated as concise namespace summaries.
   • pinned applies only to CodeMode tools; { codemode: false, pinned: true } is invalid.
   • Small catalogs inline every full signature. Larger catalogs use namespace summaries plus pinned signatures, selected by a configurable token budget (initially 2,000), not raw tool count.
   • Changing tools, permissions, or selected agent produces semantic added/removed/signature-changed Instruction updates; use a full replacement when smaller or when rendering mode changes. Denied tools are omitted entirely.
   • CodeMode owns canonical descriptors, namespace/pinned semantics, search indexing, compact/full planning, structural diffing, and pure initial/change rendering. OpenCode owns agent/permission filtering, budget configuration, and durable Instruction chronology.
   • Store one deterministic, model-facing catalog snapshot as a content-addressed Instruction value. It contains descriptors only—not executors or raw API specs. Revisit per-tool blobs only if measured catalog churn makes whole-snapshot storage costly.

   Still open for implementation-level iteration:

   • exact namespace metadata field (summary vs description) and compact rendering syntax
   • exact simplified catalog-search runtime surface
   • strict framing of MCP-authored descriptions when rendered through privileged Instructions

   Related architecture tracker: #35364.
4. opencode-agent commented on Jul 10, 2026

   

   opencode-agentBot

   on Jul 10, 2026 – with OpenCode Agent

   ContributorAuthor

   More actions

   Final gang-grill corrections

   The detailed handoff supersedes the earlier comment where they differ: https://slack.com/archives/C0BE69AHCQP/p1783726066302709

   Key corrections from the remainder of the grill:

   • A path may be both callable and a namespace (tools.slack.admin(...) and tools.slack.admin.invite(...)). The earlier recommendation to reject leaf/branch conflicts was reversed.
   • Leave the current await tools.$codemode.search({ query, namespace, limit, offset }) API and paginated result unchanged for now. Synchronous/string search ideas were deferred.
   • Keep JavaScript await and Promise.all; do not add Haxl-style query/command machinery.
   • Recompute the visible catalog only during ordinary LLM request assembly; add no Tool watchers, Session wakeups, or timers.
   • If no CodeMode Tools are visible, omit execute, CodeMode Instructions, and empty namespaces.
   • The remaining questions about namespaced native flattening, compact fallback prose, and public budget configuration were explicitly deferred for implementation.
5. kitlangton

   removed their assignment

   on Jul 11, 2026
6. tella-butler

   added a commit that references this issue on Jul 12, 2026

   Frame interrupt-delivered prompts as mid-task steers

   ...

   f7a504f
7. rekram1-node

   closed this as completedon Aug 21, 2026