System-reminder baked into same content array as the real user message

[jilian-dsh]

Background

I'm a regular DSH user; these notes come from debugging on my own machine with an AI assistant.

Issue: <system-reminder> injection is baked into the same content array as the real user message

agent-instructions bakes the <system-reminder> block into the very same content array of a user/message event as the real user text (same event, same array). Plugins that process user messages therefore cannot simply test "does the event contain an injected block" and skip the whole event — the real user text would be dropped together with the injection. They have to implement their own stripping (we do: remove the system-reminder blocks, then process the remainder; only skip when nothing is left).

Suggestion

Document the injection shape (block markers, position in content), or provide an official convention for stripping it, so plugin authors don't each reinvent the same filter.

Local verification

Bug observed live (a whole message dropped → guard state never updated); fix verified by unit tests on the strip function and an integration test with a mixed content array.

[argszero]

Good report — I verified the injection shape against rc.2 (HEAD b150a55), and the source tells a slightly different (and more hopeful) story than "same event, same array". The gap you hit is real, but it is a documentation gap, not a shape bug.

1. At rc.2, injections are SEPARATE user/message events, not merged into the real user text.

• agent-instructions emits its own user/message event whose entire content is the system-reminder frame; the event carries source.kind == 'agent-instructions' (packages/context/agent-instructions/src/index.ts:212-221 — the compose function builds a fresh message; state.ts:81-93 workspaceContextMessage/workspaceContextHook).
• tool-skill does the same with source.kind == 'skill-catalog' (packages/skill/tool-skill/src/index.ts:256-306 renderCatalogMessage).
• The session surface projects each user/message event verbatim as its own message — deriveEventMessage returns event.data unchanged and never merges two events into one content array (packages/core/session/src/surface.ts:74-98).
• A real user message carries source.kind == 'user' (packages/llm/llm/src/message.ts:101).

So the discriminator plugin authors need already exists: message.source.kind — 'user' vs 'agent-instructions' vs 'skill-catalog' (plus any other plugin's own marker). A plugin can skip an event by checking the source kind instead of text-stripping, and never risk dropping the real user text.

2. Why this is invisible: the contract is undocumented.

The framing-is-caller-owned decision and the "consumers that need the distinction read the durable event log (source, meta)" guidance live in an internal agent note (.agents/notes/implemented/simplification/2026-07-20-unwrap-injected-content-envelopes.md), not in public docs. source.kind appears only incidentally in docs/subsystems/session-title.md; system-reminder only in docs/subsystems/skills.md for the skill-catalog case. There is no plugin-facing page that says "user/message events carry a source.kind; here is the table". Your strip-filter was a rational thing to build given that vacuum — and it is exactly the kind of per-plugin reinvention that a documented contract would remove.

3. Actionable suggestions

• Document the contract in one public place (a short "processing user/message events" section — discriminator table for source.kind, note that framing is caller-owned and content projects verbatim, pointer to meta for model-hidden state). docs/subsystems/session-title.md or the events doc would be the natural home.
• Optionally ship a tiny public helper alongside it (e.g. isInjectedContextMessage(message) / a stripInjectedBlocks util) so plugin authors don't each implement the filter — this matches what you already unit-tested.
• If you genuinely observe the merge in a durable event (same event, both blocks in one content array) rather than in the model-facing transcript, share the version + one redacted event JSON — rc.2 does not produce that shape, so it would point to a different producer or a newer build.

Your local verification (guard state update, strip function unit tests) is the right instinct — with source.kind you can keep the guard logic and delete the text-stripping entirely.