Feature Request: Enable plugins per-agent at the config layer (not only globally)

[LazyGrep]

中文描述

背景 / Background

目前 plugin 数组在 opencode.json 中是全局生效的——所有插件一旦配置,就会对所有 agent 加载(包括 build、plan、general、explore 以及用户自定义 agent)。配置层没有任何按 agent 启用插件的手段。

当前行为 / Current behavior:

{
  "plugin": [
    "opencode-gemini-auth",
    "opencode-foo@1.2.3"
  ]
}

需求 / Feature Request

希望插件能够按 agent(代理)设置启用,而不是只能全局启用。例如:

{
  "plugin": {
    "opencode-foo@1.2.3": {
      "agents": ["build", "plan"]
    }
  }
}

或类似(在 agent 下声明):

{
  "agent": {
    "my-agent": {
      "plugin": ["opencode-foo@1.2.3"]
    }
  }
}

与 #24953 的关系 / Relation to #24953

#24953 提出的是插件 API 层的 per-agent 工具可见性过滤(通过 tool.definition hook 在运行时隐藏工具)。本 issue 提出的是配置层的 per-agent 插件启用(在加载时决定哪些插件对哪些 agent 生效)。两者互补:前者控制"工具是否出现在 LLM 上下文中",后者控制"插件本身是否加载"——例如某个插件带有独立初始化/后台逻辑,仅运行时隐藏工具并不能阻止它加载执行。

使用场景 / Use Cases

1. 权限隔离:某些插件(如 MCP 相关、敏感操作插件)只应给特定的 agent 启用,避免其他 agent 意外触发。
2. 上下文与性能控制:部分信息型/重量级插件不需要在所有 agent 中加载,按 agent 启用可减小上下文开销和启动成本。
3. Agent 专业化:让不同的 agent 拥有不同的工具集,而不是所有 agent 共享同一套全局插件。

期望行为 / Expected Behavior

• 支持在 opencode.json 中按 agent 配置插件启用;
• 保持现有全局配置向后兼容(未指定 agent 的插件保持全局生效);
• 若 agent 未指定插件,回退到全局插件配置;
• 与 FEATURE: Plugin API - per-agent tool visibility filtering #24953 的运行时工具过滤方案协同工作。

环境 / Environment

• opencode 版本: 最新版(2026-08)
• 平台: Linux

---

English Description

Background

Currently the plugin array in opencode.json is global — once configured, a plugin is loaded for every agent (build, plan, general, explore, and any custom agents). There is no way at the config layer to enable plugins per-agent.

Feature Request

Allow plugins to be enabled per-agent instead of only globally. For example:

{
  "plugin": {
    "opencode-foo@1.2.3": {
      "agents": ["build", "plan"]
    }
  }
}

Or alternatively, declared under the agent:

{
  "agent": {
    "my-agent": {
      "plugin": ["opencode-foo@1.2.3"]
    }
  }
}

Relation to #24953

#24953 proposes plugin API-level per-agent tool visibility filtering (hiding tools at runtime via a tool.definition hook). This issue proposes config-level per-agent plugin enabling (deciding at load time which plugins apply to which agents). The two are complementary: the former controls "whether tools appear in the LLM context", the latter controls "whether the plugin is loaded at all" — a plugin with its own initialization or background logic still runs even if its tools are hidden at runtime.

Use Cases

1. Permission isolation: plugins that are sensitive (e.g. MCP-related, privileged operations) should only be enabled for specific agents.
2. Context & performance control: info-heavy or heavyweight plugins don't need to load for every agent; per-agent enabling reduces context overhead and startup cost.
3. Agent specialization: give different agents different toolchains instead of one shared global plugin set.

Expected Behavior

• Support per-agent plugin enabling in opencode.json;
• Keep backward compatibility with the existing global config (plugins without an agent restriction remain global);
• Fall back to the global plugin list when an agent specifies none;
• Work together with FEATURE: Plugin API - per-agent tool visibility filtering #24953's runtime tool filtering.

Environment

• opencode version: latest (2026-08)
• Platform: Linux

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• The title should start with [FEATURE]: as required by the Feature Request template (e.g. [FEATURE]: Enable plugins per-agent at the config layer)
• The Feature Request template requires a verification checkbox confirming you have searched for existing issues

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

This issue has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new issue that follows our issue templates.