Per-agent scoping for workspace instruction injection (dsh-agent-instructions)

[phyliuxin]

Summary

@deepseek-ai/dsh-agent-instructions injects the workspace instruction chain into every
agent in the tree. There is no way to scope it per agent, per task class, or per subagent role.
For a delegated child whose task needs zero project context — a bounded review, a source
check, a numeric recheck, a verdict — that is more than overhead: it arrives with user-role
authority, and it includes the user-global file, not just the project chain.

What is observed

A subagent was dispatched for a bounded read-only task: review one note and report whether two
of its sections contradict each other. The delegation prompt named exactly one file and
explicitly said not to load workspace memory, ownership-map, AGENTS.md, or any skill.

Two distinct effects appear in the child's session event log, and they should not be conflated.

(a) Injected automatically, before the child acts. One user-role message is present in the
child's context regardless of the prompt:

Observation	Value
Message length (rendered text)	16,089 chars
Role	user
Instruction files carried	3: $DSH_HOME/AGENTS.md (user-global), project-root AGENTS.md, project-root CLAUDE.md

The message begins with the user-global file, before any project file:

Instructions from: ~/.dsh/AGENTS.md

<contents of the user-global instruction file>

So a child inherits user-level configuration — personal workflow conventions, machine-local
paths, credential-handling notes — whether or not its task has anything to do with the project,
and even when its prompt explicitly said not to load any of it.

(The block above is redacted. The real message contains the full text of the user-global file
verbatim; I have not reproduced this workspace's actual contents here.)

(b) Read by the child on its own initiative, because of (a). The injected project-root
AGENTS.md contains a startup protocol that instructs the reader to load several further
files. The child followed it:

Observation	Value
Tool calls made before opening the target artifact	10 (8 file reads + 2 unrelated bash calls)
Of those, reads of files named by the startup protocol	4 (user-preferences.md, research-memory-evolution-protocol.md, scientific-preferences.md, subtree AGENTS.md)
Of those, reads of files not named by any protocol	3 (README.md, _index.md ×2)
Skills loaded that the delegation prompt explicitly excluded	2, plus 4 reference files
Total tool calls in the run	23, no substantive deliverable; run later aborted

The causal chain is the point: (a) is a mechanism-level injection the dispatcher cannot
suppress, and (b) is the child doing its best to comply with what it was handed. Suppressing
(a) removes the trigger for (b) as well.

Why this is not only "extra tokens"

1. Role confusion. The plugin's own template (verified verbatim in lib/index.js) frames
the injection as:

"These instructions apply to work under `${scope}`. Use them as guidance when relevant; more
specific instructions take precedence. They do not override system, developer, or direct user
instructions."

It is delivered as a user-role message — the same role as the dispatcher's prompt. Real-world
AGENTS.md files commonly state precedence rules such as "Direct Human instructions prevail".
A child that reads the injected block as operator input can act on instructions the dispatcher
deliberately scoped out.

2. It contradicts the tool's own contract. The subagent tool's description says:

"Give it a complete, standalone prompt: it does not see this conversation."

The prompt is presented as the child's entire contract, but a second, undisclosed input channel
is injected alongside it.

3. The child cannot resolve this correctly. It sees its prompt and the injected message, but
not the lane it was dispatched into — so it has no basis on which to judge whether the chain
applies to it.

Why the current config surface cannot express the fix

export interface Config {
  dshHome?: string
  projectRootMarkers?: string[]
  maxBytes: number
  maxSourceBytes?: number
  instructionFileCandidates?: string[]
  localInstructionFileCandidates?: string[]
}

Every field governs which files are discovered, globally. None expresses which agents
receive them. The subagent descriptor carries no instruction-related field either:

{"version":3,"mode":"continuable","provider":"spawn",
 "label":"...","agentProvider":"...","agentModel":"...","agentReasoningEffort":"max"}

Disabling the plugin would strip workspace context from the main agent too, and the main agent
should load project governance. What is missing is per-agent scoping, not an off switch.

Prior art

Claude Code added omitClaudeMd in v2.1.271 (2026-09-14) for exactly this case:

Set to true to launch this subagent without the user, project, and local CLAUDE.md files;
managed policy files still load, except for managed subagents.

Two design details worth borrowing:

• The managed-policy carve-out. A subagent opting out of a team's coding conventions does
  not thereby opt out of organisation policy. The same distinction may be worth drawing here
  between project/user scopes and any harness- or org-managed baseline.
• It is per-agent, not global. Other agents in the session keep the normal chain.

Before that flag existed, the documented workaround was restructuring the repository so each
subagent ran from its own working directory with its own scoped AGENTS.md — i.e. solving an
agent-scoping problem with filesystem layout. Community reports describe the pain point
persisting for over a year, including measurement runs where every subagent loaded the project
CLAUDE.md regardless of task.

I found no equivalent report for DSH. The closest existing discussion is
#3285, which concerns
whether $DSH_HOME/AGENTS.md should be the user-global path — a different axis (path scoping,
not agent scoping).

Implementation lead: the primitive already exists

docs/subsystems/core.md describes scope/ as:

the scoped-registration primitive the registries and loop build per-agent scoping on

and lists scope-filtered dispatch (@deepseek-ai/dsh-scope): "agent-scoped listeners
receive only that agent."

I checked dsh-agent-instructions@0.1.6-alpha.1's lib/index.js: it does not consume
dsh-scope (no hits for dsh-scope, scopeOf, scopeTarget, withInitiator). If the
instruction baseline can be registered or dispatched per-agent, this feature may be
considerably smaller than a new subsystem. I did not trace how the baseline is prepared
relative to agent scope — that part needs a maintainer's confirmation.

Suggested shape

Any of these would resolve the reported case; the first is closest to prior art:

1. Per-agent opt-out at dispatch. A field on the subagent definition or delegation request —
   e.g. omitWorkspaceInstructions: true — suppressing the user-global and project chain for
   that child while leaving any managed/org baseline intact.
2. Per-provider declaration. Subagent providers could declare whether they inherit workspace
   context; subagent-spawn-in-process and out-of-process providers could differ.
3. Scoped candidates. If instructionFileCandidates could resolve per-agent rather than
   per-workspace, a dispatcher could supply a narrower candidate set for a child.

The decision point should be the dispatcher, not the child. The dispatcher knows the lane;
the child does not. Any design that asks the child to "determine what applies" cannot work,
because the information needed to decide is not in the child's context.

Workaround available to a dispatcher today

A dispatcher can only compensate in the prompt: declare the task class, name the exact files to
read, and tell the child not to load workspace memory, ownership-map.yaml, subtree AGENTS.md,
or the skill catalog. Doing that took the same review from 23 tool calls with no deliverable to
7 tool calls with a verdict.

It only saves turns. The injected user-role message still arrives; the child still has to be
told to ignore it; and correctness depends on every dispatcher remembering to say so. The
mechanism, not the prompt, is the thing that needs the scope.

What I did not verify

• Not verified whether dsh-scope can be applied to the instruction baseline without changing
  how the baseline is prepared per request. Stated as a lead, not a claim.
• Not measured the token cost of the injected message beyond its rendered character length (16,089
  chars), of which the project chain is a subset.
• Not tested whether out-of-process child providers (subagent-acp, subagent-codex,
  subagent-claude-code) behave differently — those children may already apply their own
  instruction policy upstream, which is itself an argument for per-provider declaration.
• Not verified against a pinned upstream commit; observed on the released
  @deepseek-ai/dsh-agent-instructions@0.1.6-alpha.1.

Reproduction

1. Create a workspace with a non-trivial AGENTS.md (a startup protocol requiring several
   memory files works well), plus CLAUDE.md and a subtree AGENTS.md.
2. Dispatch any subagent whose task needs one file and no project context. In the delegation
   prompt, state that the task is bounded read-only and that it must not load workspace memory,
   ownership-map.yaml, subtree AGENTS.md, or any skill.
3. Inspect the child's session event log. A user-role message containing the full instruction
   chain is present regardless of the prompt's instruction.
4. Count the child's tool calls spent on workspace files unrelated to the task.

In the originating case: 10 tool calls before the target artifact was opened, 23 in total,
and no deliverable.

[capitaharlock]

The no-way-to-scope claim only holds if you treat the two injections as one thing. At the orchestrator layer, per-agent scoping is absolutely possible: we compose each child's brief from that role's own prompt, the member card, and that role's memory file, not from the parent's context. A bounded child gets its brief and nothing else from us.

What we cannot do at that layer is remove the user-global file, because the CLI itself injects it on startup and exposes no flag to disable it. So the fix for the first part is in the orchestrator, and the fix for the user-global part has to happen upstream in the CLI.

[argszero]

Thanks for the write-up — the part that made it actionable for me is that you separated (a) the mechanism-level injection from (b) the child's consequent behaviour, and that you located the decision with the dispatcher.

The seam. The chain is composed inside dsh-agent-instructions' own agent/pre-step listener, and the loop dispatches that waterfall at packages/core/agent-loop/src/agent.ts:251. What the listener returns becomes both the model context and the durable log: on the first attempt of a step, agent.ts:374-378 appends every decision.messages entry as user/message. So agent/pre-step is the last point where the chain is still a decision rather than history — and a listener registered with { prepend: true } sits outside the package's own listener and sees the composed chain.

I verified that end to end before building anything (real harness, real filesystem workspace with a real .git marker, a real $DSH_HOME/AGENTS.md, and a child created through the loop's own createAgent with origin: 'subagent' / delegationDepth: 1), two arms, same fixture:

observation	control (no listener)	outermost listener removing the chain
decision kinds	agent-instructions, user	user
durable user/message kinds	agent-instructions, user	user
chain reaches deriveMessages()	yes (project and user-global)	no

On @capitaharlock's point about the user-global file. It is not a second channel arriving from somewhere else: loadBaselineInstructionSet composes one message whose head is the user-global file and whose body is the project files, all carrying source.kind === 'agent-instructions'. Removing the composed message therefore removes the user-global file in the same act — the probe's user-global string is present in the control arm's derived context and absent in the guarded arm. So that half is addressable at this layer, with no CLI flag and no repository restructuring (which is what the pre-flag Claude Code workaround amounted to).

Shipped — @argszero/cordis-plugin-instruction-scope@0.1.0 (npm, repo):

npm install @argszero/cordis-plugin-instruction-scope

- insert:
    - id: instruction-scope
      name: '@argszero/cordis-plugin-instruction-scope'
      config:
        rules:
          - match:
              origin: subagent
              delegationDepth: { gte: 1 }
            policy: omit
            reason: bounded child, no project context needed

The decision stays with the dispatcher, as you argued it must. A rule matches the lane the dispatcher chose — the durable session header (origin, delegationDepth, cwd, parentSession, isSeeded, agentPreset) plus the child's creation label — and yields keep, report, or omit. report is a real dry run: nothing moves, but the plugin records what it would have omitted, including the rendered character count of the chain, so the cost can be measured before anything is dropped. This is a scope, not an off switch — in the same fixture the root agent keeps its chain and its durable baseline intact, and only the matched lane loses it.

Evidence. 32 tests against the real packages, including the control arm above; 39 mutations of the plugin's own logic, all red, no survivors. The published artifact was then verified by installing it by name in an empty directory and running the same two-arm probe from there — removed: 1, chars: 491, chain absent from deriveMessages().

Honest boundaries — three.

1. The plugin enforces its policy per step, because the package re-composes the chain each step rather than retaining what a plugin dropped. visibleBaselineSource (dsh-agent-instructions lib/index.js:1073-1079) looks for a durable user/message whose source.baseline === true; with that message never committed, the package finds no baseline and prepares one again. The observable result is correct — nothing injected, nothing persisted — but the cost is repeated instruction discovery per step instead of reuse of a retained baseline. The managed/org carve-out you sketched is deliberately not implemented: it needs a scope distinction the harness does not have yet, and I would rather it arrive upstream as a real distinction than be faked here.
2. Suggestion 2 (per-provider declaration) is not expressible from a plugin. subagent-acp, subagent-codex and subagent-claude-code children are separate processes with their own instruction policy; whether they inherit this chain is a property of the provider, not of the lane the loop dispatches.
3. On your dsh-scope lead: I confirmed the same negative (no dsh-scope / scopeOf / scopeTarget hits in dsh-agent-instructions), and the primitive that actually carries this case is the pre-step waterfall rather than agent-scoped registration — the chain is composed inside a listener, so ordering relative to that listener is what decides who sees it. I did not pursue that route further, so I cannot add a second opinion on whether the baseline itself could be registered per-agent.

One smaller note that may matter for the upstream shape: the subagent descriptor is the right input, but it currently carries no instruction field (mode, provider, label, agentProvider, agentModel, agentReasoningEffort). A plugin reads the lane from the session header plus the subagent identity projection (through the session-projection registry, per .agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md) — so an omitWorkspaceInstructions field on the descriptor would give the same decision a durable, inspectable home, which is exactly the property a plugin-side rule lacks.