Support directory-scoped AGENTS.md instructions

[jonathanKingston]

Directory-scoped AGENTS.md files activate the root-to-nearest instruction chain when prompts or tools reference a path. First edits into a new scope are deferred once so the agent sees its guidance before writing. Trust, canonical path boundaries, nested checkout/generated-directory exclusions, file-size and prompt budgets remain enforced. Settings shows active, scoped and duplicate sources and reports incomplete inventories.

Turn-time discovery reads only referenced ancestor scopes, memoized within the turn. It caches missing files, invalidates discovery after file-tool changes to AGENTS.md, and starts fresh next turn. Already-injected instructions remain fixed for that turn. Settings retains its bounded full inventory. A repeatable real-activation benchmark over 10,000 directories measured 596–773 ms before and 5–14 ms after on this macOS host; these are local measurements, not platform-wide guarantees. The strategy and benchmark are committed.

This branch incorporates #2597 to order API changes: PR activity uses v4 and nested-instruction metadata uses v5. Merge #2597 first.

Validation:

• Full static checks passed; combined typecheck, formatting, dead-code and E2E syntax passed after protocol reconciliation.
• Protocol comparison against Show PR comments, reviews, and individual CI checks #2597 passes (v4 → v5).
• Full combined unit suite passed with one file worker: 8,802 passed, 7 skipped, 0 failed. Parallel runs hit different unrelated two-second hook subprocess timeouts; the affected hook suites passed unchanged in isolation. No assertions or timeout limits were relaxed.
• Both focused Electron specs passed on the combined branch: nested instructions and PR activity. Screenshots were inspected; nested coverage includes active/scoped rows, duplicate labeling and truncation.

Closes #1354

Latest integration validation: merged main through 92d2330cb, fixed same-millisecond activation ordering with a monotonic sequence, and verified the frozen-clock regression fails before the fix and passes afterward. The complete pnpm run check passed: 8,845 tests, 7 skipped, zero failures. Build and the focused nested-instruction Electron eval passed again; screenshot inspected.

[github-actions]

Merge conflict needs a human

main advanced and screenshot conflicts were resolved automatically, but these non-screenshot files conflict and can't be auto-merged. Resolve them by hand (merge or rebase main):

• src/main/services/agent-service.ts

[jonathanKingston]

Review outcome: directory-scoped AGENTS.md is meaningful, but this draft changes instruction discovery, trust, symlink and prompt-budget behavior across 16 files and 1,130 lines, is conflicting, and still had full-suite timing failures. Keeping it as a draft for focused security/instruction-precedence review; not approved for merge in this sweep.

[jonathanKingston]

Review: directory-scoped AGENTS.md instructions

Verdict: changes needed. CI has never run on this head, so I ran the gate locally on f631a03 and it passes. The blockers are a runtime-cost problem in the discovery cache and a rebase (191 commits behind, one mechanical conflict), not broken code.

Validation on the head

Check	Result
pnpm run typecheck	pass
pnpm run lint	pass
prettier --check on the 15 changed files (this branch predates oxfmt)	pass
pnpm run check:dead-code	pass
pnpm run check:oracle	pass (229 specs live, 15 invariants hold)
pnpm run check:e2e-syntax	pass
pnpm test -- project-instructions agent-service agent-system-prompt settings-sources context-estimate	93/93 pass (after rebuilding node-pty for Linux; the initial load failures were environmental)
pnpm run check:screenshots	228 stale, an artefact of the 191-commit gap
WebdriverIO spec	not run, no Electron binary in this sandbox
Dry merge with origin/main	one conflict: src/main/services/agent-service.ts at the buildSystemPrompt call, where main inserted the invokedAgent block from #1860. Nothing this PR touches was moved into a package, and main has had no nested-instruction work in this area since the merge base.

Blocking

1. A tree walk in front of nearly every file tool call. NESTED_DISCOVERY_CACHE_MS = 1_000 (project-instructions.ts:34) means activateNestedInstructionSources (:536) re-walks up to 10,000 directories with sequential readdir awaits on every read_file, list_dir, search_code, write_file and the other mapped tools (agent-service.ts:377-388, wrapper at :1672-1701) whenever more than a second has passed since the previous call. The same walk runs on every composer context estimate (context-estimate.ts:60 now passes the draft) and on every Settings open (refreshNestedDiscovery: true in register-handlers.ts). On a large monorepo an agent reading 30 files in a turn pays 30 multi-thousand-readdir walks. Discover once per turn, or key the cache on something that changes (mtime, a watcher), rather than a 1s TTL.

2. Rebase and get CI on the head before this leaves draft. The conflict resolution is mechanical.

Security

• Nested files inherit workspace trust with no per-file gate. Once the root is trusted, any directory without a .git (vendored trees, examples, fixtures) can contribute system-prompt text. The agent can also write_file a nested AGENTS.md and have it injected on the next read under that directory within the same turn. The trust="untrusted" envelope applies, so this extends the existing surface rather than adding a new class, but there is no transcript signal when agent-service.ts:1688 appends to the leading system message mid-turn; the only visibility is Settings → Sources, for the latest turn, in process memory. Please emit a transcript notice when a block is injected.
• Symlink, traversal, NUL and out-of-root handling look correct and are tested: symlinked directories are never walked, a symlinked AGENTS.md must realpath inside the canonical root (:124-153), context paths are realpath-checked via an existing ancestor (:232-257). Bounds (depth 16, 10k dirs, 200 files, 32KB per file, 8 files / 64KB active) are sensible, but truncation is silent: alphabetical DFS stops at the caps, so an AGENTS.md in a later-sorted tree is never applied and nothing reports it. Log it and mark it in Sources. .gitignore is not honoured; the skip list is hardcoded.

Non-blocking

• Mutating the leading system message mid-turn invalidates provider prompt-cache prefixes on every activation and bypasses the budget computed by prepareAgentHistory (up to +64KB).
• The deferred edit (agent-service.ts:1695-1699) returns a success-shaped string; if the model does not retry, or maxSteps is hit, the edit silently never happens.
• docs/user/project-instructions.md overclaims: activation only happens for the ten built-in tools in INSTRUCTION_CONTEXT_PATH_FIELDS; run_shell writes, ACP agents and explore or todo-worker subagent reads do not trigger it. Narrow the wording.
• deduplicateSources (:301-316) drops a nested file whose content equals the root file from the Sources list entirely.
• lastNestedActivationByProjectRoot is keyed per project root, so concurrent threads in one project overwrite each other's "active this turn" state.

No as casts beyond as const in tests, no suppressions, no exported type predicates, no object-literal casts. The e2e spec and its reference PNG are present and the oracle sees the spec.

---

Generated by Claude Code

[jonathanKingston]

Pushed four commits. e0933bb merges main (the one conflict at the system-prompt build keeps #1860's invokedAgent block ahead of this PR's buildSystemPromptWithMetadata call; no dependency changes). 965ca10 replaces the 1-second cache with a per-turn memo: the system-prompt build seeds one walk, every activateNestedInstructionSources in that turn reuses the memoised promise, the composer's context:estimate uses a shared 30 s cache, Settings still forces a reload, and any edit tool touching an AGENTS.md invalidates the memo so the next file tool re-walks; it also emits one _Loaded directory-scoped instructions from ..._ line per activation, buffered so it lands after the tool result rather than between a tool call and its result. 68a5bc4 records discovery truncation (discoveryTruncated on project rows, a console.warn, and a note in Sources) and keeps content-duplicate nested files listed with a "duplicate" badge instead of dropping them, while keying the "active this turn" record per thread. 4be167d narrows the user doc to the tools in INSTRUCTION_CONTEXT_PATH_FIELDS and documents the once-per-turn discovery. Full format check, typecheck, lint, dead-code, oracle, e2e-syntax and 139 targeted tests pass on the merged tree. The new badge and truncation note have DOM unit coverage but no new e2e screenshot, since that would change the committed reference PNG; worth a follow-up visual spec.

---

Generated by Claude Code

[github-actions]

🖥️ PR preview

• Marketing site
• Browser demo
  Interactive, with a mocked backend — jump to a scenario:
• Builds a cupcake site
• Agent-proposed edits open the Changes panel
• Markdown list indentation
• Responsive composer footer
• Subagent display visual reference
• Subagent stays ungrouped beside reading tools
• Semantic search subagent markdown
• Light-theme approval with a bright accent
• Light-theme syntax, fills, and selection
• Grouped outside-sandbox command approval
• Remote desktop discovered-port list with one selected
• Settings scroll + sticky footer geometry
• Per-model reasoning / temperature / top-p
• Thread switch hydration notice
• Thread switch hydration failure
• Chat layout styling
  _{Static demo of the renderer against a mock API — the browser pane, terminal, and all main-process IPC are stubbed, so it never proves main-process behaviour. Rebuilt whenever a push changes the demo bundle; these links go live once the queued deploy lands, shortly after this comment. Removed when the PR closes.}

[jonathanKingston]

Readiness review: per-turn memoization avoids repeated discovery on every tool, but the first look of every turn still performs a fresh serial tree walk (up to 10,000 directories), bypassing the 30-second discovery cache. I am holding this draft for a large-repository turn-start latency measurement and an agreed invalidation/indexing strategy; the existing focused correctness tests do not establish that cost.

[jonathanKingston]

Current audit: the latest precheck failure is an npm-registry socket timeout during pnpm audit, not a demonstrated source regression. That does not make the PR ready: it is 26 commits behind main, and the substantive large-repository blocker remains unchanged — the first nested-instruction lookup each turn can serially walk up to 10,000 directories without a measured latency budget or agreed indexing/invalidation design.

Keep draft and avoid spending CI on a rebase until that design/evidence exists. #1354 already tracks the feature, so no new issue is needed; the next useful work is the bounded large-repository benchmark/investigation recorded here.

[copse-release-bot]

Reference screenshots ready for review

Review GitHub’s image diffs in screenshot PR #2621.
Merge it (or enable auto-merge) to apply the accepted PNGs to codex/nested-agents-instructions.

Rendered for 6e10d3c76be7 by CI run 34304241845; the immutable artifact is reference-screenshot-candidates-34304241845.

If this source branch moves, a later successful render closes the stale review PR and replaces this link.