anomalyco / anomalyco/opencode

feat(core): add cache-safe Code Mode namespace instructions

Open
#45,147 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

2.0 core enhancement
Dominant language
TypeScript
Stars
209k
Forks
27.5k
PR merge metrics
PR metrics pending

Description

Problem

Plugin-defined Code Mode namespaces currently expose only their name, tool count, and individual tool listings. They cannot provide shared namespace-level descriptions or usage instructions.

This makes it difficult to explain a policy that applies to several related tools without repeating that guidance on every tool. For example, session-management tools need to distinguish independent top-level sessions from built-in subagents:

Use built-in subagents for ordinary delegated work. Create an independent session only when the user requests a separate conversation, durable parallel work, or a dedicated worktree.

MCP servers already have server-level instructions, but plugin-defined namespaces do not have an equivalent capability.

Why context hooks are not sufficient

A session context hook can append guidance to the system prompt, but it runs after durable instructions are assembled and tracked. Adding, changing, or removing that guidance therefore rewrites the existing prompt prefix rather than flowing through chronological instruction updates, unnecessarily invalidating provider prompt caches.

The current workaround is to pin one representative tool and put the policy in the first line of its description. This preserves cache behavior because Code Mode catalog changes already participate in the durable instruction machinery, but it couples namespace-wide policy to an arbitrary tool.

Requested behavior

  • Allow a plugin or tool registration to attach a description or instructions to a Code Mode namespace.
  • Present namespace guidance once when the namespace is available, alongside its tools or as a related durable instruction source.
  • Route additions, edits, and removals through the existing durable instruction and chronological update machinery so existing prompt prefixes remain stable.
  • Define behavior for partial catalogs, tool discovery/search, namespace ownership or collisions, and namespace removal.
  • Consider whether MCP server instructions and plugin-defined namespace instructions can share the same underlying abstraction without changing existing MCP behavior.

Acceptance criteria

  • A plugin can register namespace-level guidance without duplicating it across tool descriptions.
  • The model receives that guidance whenever the namespace is available.
  • Installing, updating, or removing guidance in an existing session does not rewrite its historical prompt prefix.
  • Catalog updates remain deterministic when multiple tools or plugins share a namespace.
  • Focused tests cover initial rendering, chronological updates, partial catalogs, and removal.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing Code Mode namespace and tool registration, then follow the durable instruction and chronological update machinery. Compare the existing MCP server-instruction path and determine how partial catalogs, discovery, collisions, removal, and shared namespaces should behave; done means focused tests cover initial rendering, updates, partial catalogs, and removal without rewriting historical prompt prefixes.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.