anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 02:05:26 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[BUG]: Subagents inappropriately inherit main agent instructions from CLAUDE.md/AGENTS.md #2964

New Issue
Open
opened 2026-02-16 17:38:03 -05:00 by yindo · 4 comments
yindo commented 2026-02-16 17:38:03 -05:00
Owner
Copy Link
Copy Source

Originally created by @tinhnguyen0110 on GitHub (Nov 19, 2025).

Description

Subagents are receiving CLAUDE.md / AGENTS.md instruction files that are intended only for the main agent.
Because SystemPrompt.custom() loads all instruction files for every agent without checking whether the agent is a subagent, domain-specific prompts leak into specialized subagents.

This causes two major problems:

  1. Instruction Leakage
    Subagents inherit main-agent instructions they should never see, which contaminates their system prompt.

  2. Subagents Ignore Their Own /agent Instructions
    When subagents receive these leaked context blocks, they no longer follow the instructions defined in their dedicated /agent folder.
    The leaked prompts override or conflict with the subagent’s intended behavior, resulting in incorrect execution.

Impact:

  • Subagents do not behave according to their specialized role.
  • Workflow-specific constraints break because subagent logic is overridden by main-agent instructions.

Code Reference:
File: packages/opencode/src/session/system.ts:627

system.push(...(await SystemPrompt.custom())) // Loads for ALL agents

SystemPrompt.custom() loads instruction files for both main agents and subagents without distinction, which is the root cause of the instruction leakage.

OpenCode version

v1.0.78

Steps to reproduce

No response

Screenshot and/or share link

Image

Operating System

Ubuntu

Terminal

No response

Originally created by @tinhnguyen0110 on GitHub (Nov 19, 2025). ### Description Subagents are receiving `CLAUDE.md` / `AGENTS.md` instruction files that are intended only for the main agent. Because `SystemPrompt.custom()` loads all instruction files for **every** agent without checking whether the agent is a subagent, domain-specific prompts leak into specialized subagents. This causes **two major problems**: 1. **Instruction Leakage** Subagents inherit main-agent instructions they should never see, which contaminates their system prompt. 2. **Subagents Ignore Their Own /agent Instructions** When subagents receive these leaked context blocks, they no longer follow the instructions defined in their dedicated `/agent` folder. The leaked prompts override or conflict with the subagent’s intended behavior, resulting in incorrect execution. **Impact:** * Subagents do not behave according to their specialized role. * Workflow-specific constraints break because subagent logic is overridden by main-agent instructions. --- **Code Reference:** File: `packages/opencode/src/session/system.ts:627` ```ts system.push(...(await SystemPrompt.custom())) // Loads for ALL agents ``` `SystemPrompt.custom()` loads instruction files for **both main agents and subagents** without distinction, which is the root cause of the instruction leakage. ### OpenCode version v1.0.78 ### Steps to reproduce _No response_ ### Screenshot and/or share link <img width="670" height="414" alt="Image" src="https://github.com/user-attachments/assets/cca34fe7-665d-484e-90d3-33e3486bbf45" /> ### Operating System Ubuntu ### Terminal _No response_
yindo added the bug label 2026-02-16 17:38:03 -05:00
yindo commented 2026-02-16 17:38:03 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Nov 19, 2025):

Do other tools not send AGENTS.md to subagents? I get where you are coming from but I thought the whole point was supposed to be a prompt for all agents

@rekram1-node commented on GitHub (Nov 19, 2025): Do other tools not send AGENTS.md to subagents? I get where you are coming from but I thought the whole point was supposed to be a prompt for all agents
yindo commented 2026-02-16 17:38:03 -05:00
Author
Owner
Copy Link
Copy Source

@tinhnguyen0110 commented on GitHub (Nov 20, 2025):

I’ve been using Claude Code’s agent system extensively, and in their architecture subagents do not read or inherit CLAUDE.md or any other global instruction file.

Here’s how Claude handles it:

  • The main agent loads all CLAUDE.md layers (enterprise, project, user).
  • Subagents start with a completely clean context window and do not automatically receive any of the main-agent instructions or memory.
  • Each subagent only reads the instruction file defined in its own /agents/<subagent>/ folder.

Because of that design, having subagents automatically receive global files like CLAUDE.md / AGENTS.md is not recommended. It breaks specialization and causes instruction conflicts. Subagents are meant to stay focused and predictable.

If additional instructions are needed for a subagent, they should be defined directly inside that subagent’s own system prompt file. That’s exactly how Claude intends subagents to remain isolated, controlled, and role-specific.

So the current behavior (injecting SystemPrompt.custom() into all agents) introduces instruction leakage that Claude’s architecture avoids by design.

You can read Claude’s subagent documentation here:
https://code.claude.com/docs/en/sub-agents#what-are-subagents

And here is the relevant excerpt from the docs:

“Subagents are pre-configured AI personalities that Claude Code can delegate tasks to.
They have their own context window, their own system prompt, and operate independently.”

@tinhnguyen0110 commented on GitHub (Nov 20, 2025): I’ve been using Claude Code’s agent system extensively, and in their architecture **subagents do not read or inherit `CLAUDE.md` or any other global instruction file**. Here’s how Claude handles it: * The **main agent** loads all `CLAUDE.md` layers (enterprise, project, user). * **Subagents** start with a completely clean context window and do *not* automatically receive any of the main-agent instructions or memory. * Each subagent only reads the instruction file defined in its own `/agents/<subagent>/` folder. Because of that design, having subagents automatically receive global files like `CLAUDE.md` / `AGENTS.md` is **not recommended**. It breaks specialization and causes instruction conflicts. Subagents are meant to stay focused and predictable. If additional instructions are needed for a subagent, they should be defined **directly inside that subagent’s own system prompt file**. That’s exactly how Claude intends subagents to remain isolated, controlled, and role-specific. So the current behavior (injecting `SystemPrompt.custom()` into all agents) introduces instruction leakage that Claude’s architecture avoids by design. You can read Claude’s subagent documentation here: [https://code.claude.com/docs/en/sub-agents#what-are-subagents](https://code.claude.com/docs/en/sub-agents#what-are-subagents) And here is the relevant excerpt from the docs: > “Subagents are pre-configured AI personalities that Claude Code can delegate tasks to. > They have their own context window, their own system prompt, and operate independently.”
yindo commented 2026-02-16 17:38:03 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Nov 20, 2025):

@tinhnguyen0110 I just tested with claude code, it does give the CLAUDE.md to subagents

@rekram1-node commented on GitHub (Nov 20, 2025): @tinhnguyen0110 I just tested with claude code, it does give the CLAUDE.md to subagents
yindo commented 2026-02-16 17:38:03 -05:00
Author
Owner
Copy Link
Copy Source

@tinhnguyen0110 commented on GitHub (Nov 20, 2025):

Hi @rekram1-node , after testing in Claude Code, I see that subagents receiving CLAUDE.md / AGENTS.md is intended behavior. My earlier report was mistaken.

I was confused because in the CLI setup instructions, CLAUDE.md / AGENTS.md are shown as files to create, but it doesn’t mention that subagents will read them. Also, these files aren’t really the main agent’s prompts, and it’s not obvious that the main agent has its own prompts or acts as the orchestrator when running in CLI mode.

So the current behavior in OpenCode aligns with Claude Code’s design.

@tinhnguyen0110 commented on GitHub (Nov 20, 2025): Hi @rekram1-node , after testing in Claude Code, I see that subagents receiving CLAUDE.md / AGENTS.md is intended behavior. My earlier report was mistaken. I was confused because in the CLI setup instructions, CLAUDE.md / AGENTS.md are shown as files to create, but it doesn’t mention that subagents will read them. Also, these files aren’t really the main agent’s prompts, and it’s not obvious that the main agent has its own prompts or acts as the orchestrator when running in CLI mode. So the current behavior in OpenCode aligns with Claude Code’s design.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#2964
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?