Document agent.maxTokens, and that a cut-off or empty agent reply ends the run error

[DavidCockerill]

⊙ Problem

HarperFast/harper#3064 changes two things operators see:

• It adds agent.maxTokens, an output-token cap sent with every agent model request.
• A model reply that did not finish (cut off at the cap or the context window, stopped by the content filter or a refusal, an unparsable tool call, or an empty reply) now ends the run error instead of completed, and nothing from it is recorded.

The reference pages still describe completed as any run that ended without throwing, and they don't list the new key.

❓ Your call: requirement. This documents a user-facing config key and a status change that pollers key on, so it is needed whenever the core PR merges. Same page structure as #708.

💡 Solution

• reference/configuration/options.md:
  • adds maxTokens to the agent example, its option bullet and the list of keys set_agent_config can change;
  • the bullet covers the default, what a cut-off reply means, when raising the cap won't help (a filled context window), the risk of exceeding a model's own output limit, and what each backend sent before.
• reference/operations-api/operations.md:
  • the status table's completed row now says "a final answer";
  • a new paragraph lists which unfinished replies end error and says nothing from them is recorded;
  • set_agent_config accepts maxTokens and rejects a non-positive-integer;
  • the in-flight-settings bullet adds maxTokens and says a paused run resumed by approve_agent_action picks up the current settings, which was already true for every listed setting.

❓ Your call: dated v5.4.0, not a 5.3 patch. agent.maxTokens (harper#3064) and agent.httpFetch (harper#3011) are 5.4 features on main, and neither is on the v5.3 release branch. So this PR also re-dates httpFetch's three v5.3.2 markers, which #708 published: its option bullet, its section badge and the redirect-hop sentence. It also adds both features to a Built-in Agent section of the 5.4 release notes.

✅ Verification

Route (d): docs only, not observable end-to-end. Each claim was checked against the core branch: rejectTurn in agent/loop.ts, setAgentConfig in agent/operations.ts, DEFAULT_CONFIG/mergeConfig in agent/agent.ts, and the backends' previous DEFAULT_MAX_TOKENS handling. The core PR's live smoke observed the documented behavior: the statuses and lastError text, the 400 on an over-limit model, the 400 on maxTokens: 0, and a live patch applying from the next run. prettier --check passes on both files.

Refs HarperFast/harper#3039, Refs #674

_{🤖 Generated by Claude Opus 5.5 (Claude Code); posted via @DavidCockerill.}

Related PRs: #671 independent (its agent mention is about APM agents), #676 independent, #683 independent, #691 independent, #697 independent, #709 independent, #710 independent, #707 independent (shared reference pages, different sections), #713 independent (deploy-from-CI pages; shares operations.md, not the agent section)
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=1 @ d78dd4f}

_{Review-Attention: skim ~2m (decisions: default-16384-cap, mixed-tool-call-reply, approve-resume-uses-live-config, rebadge-httpfetch) @ d78dd4f}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

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-712

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-712

This preview will update automatically when you push new commits.