Document agent.maxToolResultBytes and how the agent recovers when a conversation outgrows the model's context window

[DavidCockerill]

⊙ Problem

The built-in agent no longer stores tool results in full, pages read_file, and retries once when a conversation outgrows the model's context window. None of that is documented, including the new agent.maxToolResultBytes setting (Cap the agent's tool results and page its file reads, so one large read no longer ends the session (harper#3117), for agent: no cap on tool-result size — one large read kills the session (harper#3068)).

❓ Your call: badged v5.4.0 to match Document agent.maxTokens, and that a cut-off or empty agent reply ends the run error (#712); it follows the code PR's milestone if that changes.

Refs HarperFast/harper#3068

💡 Solution

• reference/configuration/options.md: maxToolResultBytes in the agent example and option list (default, range, startup fallback, page size), and in the list of keys set_agent_config can change.
• reference/operations-api/operations.md: a new section, When a conversation outgrows the model's context window. It covers the cap, read_file's cursor, and the single retry, with its limits: best effort, the fallback-candidate case, and recovering a session broken by an earlier version. Also set_agent_config's new key and its 400, and that a run keeps the cap it started with.
• release-notes/v5-lincoln/5.4.md: a Built-in Agent entry.

❓ Your call: whichever of this PR and #712 merges second keeps both new keys in the three lists and a single ## Built-in Agent heading in the 5.4 notes.

✅ Verification

Two cross-model review rounds (Codex + Gemini + Harper adjudication) checked every claim against the code PR. They caught overclaims about paging and recovery, which are corrected here, and a page-budget gap that is fixed in the code PR. prettier --check passes on the changed files.

_{🤖 Generated by Claude (Anthropic); posted via @DavidCockerill.}

Related PRs: #671 independent, #676 independent, #683 independent, #691 independent, #697 independent, #709 overlaps (5.4 release notes; rebase conflict only), #712 overlaps (same agent option list, set_agent_config key lists and 5.4 Built-in Agent heading), #713 independent, #710 independent, #707 independent
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; blocked=cursor-composer(not-installed); declined=cursor-grok,cursor-kimi,cursor-muse; rounds=2; full=1 @ 5207085}

_{Review-Attention: skim ~2m (decisions: retry-scope, fix-layer-for-page-fit) @ 5207085}

[gemini-code-assist]

Code Review

This pull request updates the documentation and release notes for version 5.4.0 to introduce the maxToolResultBytes configuration option, which caps and pages agent tool results to prevent conversations from exceeding the model's context window. The review feedback suggests improving the phrasing of how tool results are cut for better readability and adding a version badge to the set_agent_config section to properly document the API change.

[gemini-code-assist]

The phrasing "cuts to 2 KiB every result over 2 KiB" is slightly awkward. Rephrasing it to "cuts every result over 2 KiB to 2 KiB" improves readability and flow.

[gemini-code-assist]

Since set_agent_config is an existing API surface and we are introducing a new configuration key (maxToolResultBytes) to its accepted parameters, we should include a component directly under the heading to denote this behavior change.

References

1. When documenting behavior changes to an existing API surface (e.g., adding new fields to a response), use . Ensure it is placed standalone under headings rather than mid-sentence.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-720

This preview will update automatically when you push new commits.