Skip to content

agents-md: an auto-paginated Read of a nested AGENTS.md no longer counts as delivering it - #96364

Merged
poteat merged 2 commits into
mainfrom
poteat/agents-md-truncated-read
Sep 24, 2026
Merged

poteat merged 2 commits into
mainfrom
poteat/agents-md-truncated-read

Conversation

@poteat

@poteat poteat commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

A Read of a nested AGENTS.md itself counts as delivering it when it names no offset or limit, so later Reads under that directory do not attach it again. But a whole-file Read of a file over the Read tool's token cap is paginated by the tool: the model gets the first page and a banner, and the result says so (truncatedByTokenCap, numLines short of totalLines). The mod marked the file delivered all the same, so the rest of the instructions never reached that loop unless the model paged through the file on its own.

The tool.call hook on Read now reads the returned record before recording delivery: a text result that is flagged truncatedByTokenCap, does not start at line 1, or returned fewer lines than the file has is a partial read, as an explicit offset or limit already was, and the file is attached whole at the next Read under its directory. A complete read, and a result with no structured record, behave as before. The tests in tests/register.test.ts cover the six cases (auto-paginated, short line range, complete, explicit limit, explicit offset, unstructured result).

Checked:

  • A project with a 600-line nested/AGENTS.md and CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=3000, claude -p --plugin-dir mods/agents-md against a scripted local Messages endpoint that Reads nested/AGENTS.md and then nested/source.ts: the first Read comes back as lines 1-190 of 603; before, the second Read attaches nothing and the file's last rule is in no request; after, the second Read carries Contents of …/nested/AGENTS.md: with the whole file. With the default cap the first Read is complete and the second attaches nothing, before and after. With a 160 KB file under the default cap the same holds, the attached text handed over as a saved file with its head, as the engine does for context that long.
  • Two of the six new tests fail with the hook's change reverted (the auto-paginated read and the short line range); all pass with it.
  • tsc -p mods/tsconfig.json, claude plugin validate mods/agents-md, git diff --check, and claude plugin test on all four mods (212 tests) under 2.1.277.

Patch by @7487, from #91870.

@poteat
poteat enabled auto-merge (rebase) September 23, 2026 13:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants