[FEATURE]: Load AGENTS.md progressively via read-tool plugin context

[opencode-agent]

Summary

Implement progressive path-scoped AGENTS.md loading for V2 when the read tool successfully reads a file, using plugin-owned discovery plus Core System Context admission.

Decision

This should be implemented via V2 plugin seams, but plugins should not directly write raw synthetic user messages for authoritative instructions.

Expected shape:

1. A tool.after / tool.settled hook fires after a local tool succeeds.
2. A read-tool plugin observes successful read(file) calls, resolves the canonical file path, discovers applicable AGENTS.md files near that file, and records newly discovered instruction files in plugin-owned session state.
3. A session-scoped context contribution hook exposes those discovered instructions as a normal SystemContext.Source for that sessionID.
4. SessionContextEpoch.prepare(...) compares the source snapshot at the next safe provider-turn boundary and emits a durable ContextUpdated / Session.Message.System when new instructions become effective.
5. Provider adapters lower that chronological system message appropriately:
   • native Anthropic mid-conversation role: "system" when supported and placement is legal;
   • escaped user fallback for unsupported providers/models/placements.

Needed plugin/core seams

• tool.after / tool.settled hook payload with at least:
  • sessionID
  • effective agent
  • tool name
  • decoded input
  • structured output/result
  • resolved/canonical resources when the tool has filesystem targets
• Session-scoped System Context contribution hook, because discovered instructions depend on sessionID, not just Location.

Expected behavior

• On successful read(file), walk from project root to the file directory and find applicable AGENTS.md files.
• Deduplicate already discovered/admitted instruction files per session.
• Do not mark instructions as loaded unless they are actually admitted to model context.
• Preserve ordering/scope semantics for global, upward project, and newly discovered path-local instructions.
• Do not mutate the top-level system prompt for ordinary mid-epoch updates; only epoch replacement should rebuild the baseline.

Follow-ups to verify while implementing

• Replace hardcoded Anthropic native mid-conversation system support checks, currently tied to claude-opus-4-8, with route/provider capability metadata.
• Double-check Anthropic cache behavior for explicit block cache_control vs top-level automatic caching; current explicit block markers are valid, but the capability should be intentional and documented.
• Coordinate with the broader V2 tool plugin architecture work in [FEATURE]: Build V2 tool plugin architecture #34489.

Source

Design discussion in Discord: https://discord.com/channels/1391832426048651334/1521953168899182612

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• The title does not start with [FEATURE]: as required for feature requests
• The issue does not use the Feature Request template (missing the verification checkbox confirming the feature hasn't been suggested before)

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

---

This issue might be a duplicate of or closely related to existing issues. Please check:

• fix(read): image/pdf reads mark instructions as loaded without emitting system-reminder #33823: Directly related — read tool marks instructions as loaded without emitting system-reminder, which overlaps with the progressive loading and deduplication mechanism described here
• [FEATURE]: Incrementally update AGENTS.md to improve input cache hit rate #29584: [FEATURE]: Incrementally update AGENTS.md to improve input cache hit rate — tracks a related incremental/progressive loading concern for AGENTS.md

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.

[opencode-agent]

Reopening: this was auto-closed by issue compliance automation, but the author is now exempt under the team/opencode-agent automation guard.

[opencode-agent]

Updated from today’s Discord design discussion: Kit is taking this, and the intended V2 shape is plugin-owned discovery after read plus session-scoped System Context contribution, with Core Context Epoch admission rather than raw synthetic message insertion.