AGENTS.md reminder runs after the first mutating tool call

[fancyboi999]

What version of Kimi Code is running?

0.38.0

The same sequencing is present on current main at 2102c43dcec8ab09936f29695a5433efb9948b51.

Which open platform/subscription were you using?

Kimi Code. This report is model- and provider-independent because it concerns tool-execution ordering in agent-core-v2.

Which model were you using?

kimi-k3 — the tool lifecycle issue itself is model-independent.

What platform is your computer?

Darwin 25.5.0 arm64 arm

What issue are you seeing?

The AGENTS.md discovery reminder introduced by #2545 is registered on onDidExecuteTool. For mutating tools such as Edit, Write, and Bash, the target operation has therefore already completed before Kimi discovers an uninjected nested AGENTS.md and tells the model to read it.

This makes the reminder text — “Read them before making changes in those directories” — impossible to satisfy for the first mutating call in a newly touched subtree.

Current ordering:

Edit / Write / Bash executes
  -> tool result is finalized
  -> onDidExecuteTool runs
  -> nested AGENTS.md is discovered
  -> reminder is queued for the model

Source evidence at the fixed main SHA:

• agentsMdReminder registers on onDidExecuteTool
• probeAndRemind discovers and schedules the reminder
• finalizeToolResult invokes the hook after receiving the tool result

This is a correctness/policy-ordering issue rather than a security-boundary report: AGENTS.md is model guidance, while permissions and sandboxing remain the enforcement boundary.

What steps can reproduce the bug?

Create a repository like this:

repo/
├── AGENTS.md
└── packages/
    └── api/
        ├── AGENTS.md       # “Do not modify generated.ts.”
        └── generated.ts

1. Start Kimi Code from repo/, so packages/api/AGENTS.md is outside the initial root-to-cwd instruction chain.
2. Make the first operation in that subtree an Edit or Write against packages/api/generated.ts, without reading another file in packages/api/ first.
3. Observe that the mutation succeeds.
4. Only after execution does the AGENTS.md reminder become model-visible.

This does not depend on model behavior: it can be reproduced at the executor/integration-test level by making Write the first tool call into the nested subtree and asserting both filesystem state and reminder delivery order.

Bash has an additional blind spot. Target extraction only recognizes directory-listing commands (ls, tree, find, dir, exa, eza, lsd):

• LISTING_COMMANDS
• non-listing commands are skipped

For example, a first-touch mutation such as the following does not identify packages/api as a reminder target:

sed -i 's/old/new/' packages/api/generated.ts

Dynamic and compound path forms are intentionally skipped as well, so Bash-only workflows may receive no reminder at all.

What is the expected behavior?

Before the first mutating tool call affects a subtree covered by an uninjected AGENTS.md, Kimi should make the relevant instructions model-visible or prevent that call and ask the model to read the instruction file before retrying.

Possible behavior contracts include:

1. Preflight Edit and Write using their already-resolved file accesses. If an unseen nested AGENTS.md is found, veto the current call with an actionable result and allow the model to read and retry.
2. Keep the current post-execution reminder for read-only discovery tools (Read, Glob, Grep).
3. Define an explicit policy for Bash: expand conservative literal mutation-target detection, or document that Bash-only mutations cannot receive this guarantee.
4. Add a regression test proving that the first Edit/Write cannot modify a nested subtree before its newly discovered instructions become visible.

Additional information

The existing implementation already handles many difficult edges well: per-agent deduplication, restore/resume seeding, concurrent discovery, instruction-file change announcements, symlinks, Windows paths, and not-yet-created directories. This report is intentionally limited to the remaining pre-mutation ordering gap.

For comparison, Claude Code documents that nested CLAUDE.md files are loaded on demand when it reads files in those subdirectories. Codex documents only project-root-to-cwd discovery and does not claim child-on-access enforcement. The issue here is therefore not that Kimi must copy another product; it is that Kimi's own reminder promises “before making changes” while its hook runs after the first change.

• Claude Code: how CLAUDE.md files load
• Codex: AGENTS.md discovery
• Related implementation: feat(agent-core-v2): add AGENTS.md discovery reminder #2545
• Related project-navigation report: Agent 子 Agent 无法自动感知项目导航文件（AGENTS.md / .cursor/rules/），导致与 Claude Code 相比任务成功率差距 #489