Current behavior
InstructionDiscovery walks AGENTS.md from the session directory up to the canonical project root and stops (plus the global ~/.config/opencode/AGENTS.md). Directories between the project root and the user's home are never consulted.
Proposal
Continue the upward walk past the project root, stopping at $HOME (inclusive). No other changes: same nearest-to-farthest stacking, same admission/rendering, same global file.
Why
It enables the in-between zone that neither per-project nor global config can express today: a ~/code/AGENTS.md applying shared conventions to every project under ~/code/ ("always bun, never npm", house lint rules, etc.). Users arriving from Claude Code and pi already expect ancestor context files above the repo to apply — both walk to the filesystem root.
Prior art
| CLI |
Upward walk boundary |
| Claude Code |
filesystem root |
| pi |
filesystem root |
| grok / Codex / Copilot CLI |
git root |
| Hermes |
git root; outside a repo, cwd only (explicit anti-leak stance) |
| opencode v2 today |
project root |
Stopping at $HOME rather than / keeps shared/world-writable ancestors (/tmp, mounts, CI scratch dirs) out of sessions rooted there, at the cost of one boundary rule.
Mechanics
After the instruction-discovery refactor (#41629), discovery reads a static candidate list (one AGENTS.md path per ancestor directory) with one file-watch per candidate. This proposal is: extend the chain's stop from project root to $HOME — a different stop argument and a slightly longer watch list. Small diff, fully testable with the existing harness.
Non-goals
Downward/nested discovery (VS Code useNestedAgentsMdFiles-style) is separate — the lazy read-tool path (SessionInstructions) already covers subtree context during a session.
Current behavior
InstructionDiscoverywalksAGENTS.mdfrom the session directory up to the canonical project root and stops (plus the global~/.config/opencode/AGENTS.md). Directories between the project root and the user's home are never consulted.Proposal
Continue the upward walk past the project root, stopping at $HOME (inclusive). No other changes: same nearest-to-farthest stacking, same admission/rendering, same global file.
Why
It enables the in-between zone that neither per-project nor global config can express today: a
~/code/AGENTS.mdapplying shared conventions to every project under~/code/("always bun, never npm", house lint rules, etc.). Users arriving from Claude Code and pi already expect ancestor context files above the repo to apply — both walk to the filesystem root.Prior art
Stopping at $HOME rather than
/keeps shared/world-writable ancestors (/tmp, mounts, CI scratch dirs) out of sessions rooted there, at the cost of one boundary rule.Mechanics
After the instruction-discovery refactor (#41629), discovery reads a static candidate list (one
AGENTS.mdpath per ancestor directory) with one file-watch per candidate. This proposal is: extend the chain's stop from project root to $HOME — a differentstopargument and a slightly longer watch list. Small diff, fully testable with the existing harness.Non-goals
Downward/nested discovery (VS Code
useNestedAgentsMdFiles-style) is separate — the lazy read-tool path (SessionInstructions) already covers subtree context during a session.