Feature hasn't been suggested before.
Describe the enhancement you want to request
Every AGENTS.md in scope is delivered to every agent that reads instructions. There is no way for a file to say "this part is for the orchestrator" or "this is for reviewers only".
Two costs:
Tokens. Orchestration doctrine — delegation rules, dispatch patterns, subagent routing — is dead weight in every subagent's context. In our setup that is several thousand tokens per dispatch, on every dispatch.
Correctness. A subagent reading "delegate this to a subagent" has nowhere to send it. Instructions written for one reader are actively misleading to another, and the model has no way to tell which it is.
The existing context: "sparse" idea (if adopted) drops instruction files by origin — where the file was found. That is a different axis from who the file is for, and neither substitutes for the other.
Suggested behaviour
Frontmatter on the instruction file declaring its intended reader:
---
opencode:
audience:
- role: main
- agent: reviewer*
---Points worth deciding deliberately:
- Role should probably be structural — derived from whether the session has a parent, not from the agent file's declared
mode. A mode: "primary" agent dispatched as a child is functionally a subagent.
- A typo must not silently disable filtering.
audiance: main is valid YAML, so a permissive schema cannot catch it, and failing open reinstates exactly the delivery the directive exists to prevent.
- There is more than one delivery path. System-prompt assembly,
Instruction.resolve() via the read tool, and the file: attachment path all deliver instruction content; filtering one leaves the others open.
Version
v1.18.5
Additional context
PR #38957 implements this. Note that the V2 SessionCore assembles system context through a separate path (packages/core/src/instruction-context.ts) which would need its own handling.
Feature hasn't been suggested before.
Describe the enhancement you want to request
Every
AGENTS.mdin scope is delivered to every agent that reads instructions. There is no way for a file to say "this part is for the orchestrator" or "this is for reviewers only".Two costs:
Tokens. Orchestration doctrine — delegation rules, dispatch patterns, subagent routing — is dead weight in every subagent's context. In our setup that is several thousand tokens per dispatch, on every dispatch.
Correctness. A subagent reading "delegate this to a subagent" has nowhere to send it. Instructions written for one reader are actively misleading to another, and the model has no way to tell which it is.
The existing
context: "sparse"idea (if adopted) drops instruction files by origin — where the file was found. That is a different axis from who the file is for, and neither substitutes for the other.Suggested behaviour
Frontmatter on the instruction file declaring its intended reader:
Points worth deciding deliberately:
mode. Amode: "primary"agent dispatched as a child is functionally a subagent.audiance: mainis valid YAML, so a permissive schema cannot catch it, and failing open reinstates exactly the delivery the directive exists to prevent.Instruction.resolve()via the read tool, and thefile:attachment path all deliver instruction content; filtering one leaves the others open.Version
v1.18.5
Additional context
PR #38957 implements this. Note that the V2 SessionCore assembles system context through a separate path (
packages/core/src/instruction-context.ts) which would need its own handling.