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.
• reference/configuration/options.md, Filesystem scopes: the key-material rule now says read_file refuses a page that holds a PEM private key or starts inside one, since read_file returns pages rather than whole files.
• 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, #714 independent, #722 independent, #724 independent, #725 independent, #727 overlaps (same agent option list, set_agent_config lists and 5.4 Built-in Agent notes), #729 independent, #717 overlaps (merged; this branch edits its key-material sentence for paged reads), #728 independent, #715 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=3; full=2 @ 902c970}

_{Review-Attention: skim ~2m (decisions: cursor-guarantee-fix-layer, pem-claim-wording) @ 902c970}

[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.

[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.

[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.

[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.

[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.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.