Document agent.configScope and the agent's filesystem scopes, including what every scope refuses

[DavidCockerill]

⊙ Problem

HarperFast/harper#3041 narrows the built-in agent's read-only config filesystem scope from the whole Harper root to the config file. It also adds agent.configScope, and makes the agent's filesystem tools refuse key material in every scope. The reference still says read_file covers "the log and configuration directories", and it documents neither the new key nor the refusal rules. Refs HarperFast/harper#3041 · Refs #674 · Feature PR: HarperFast/harper#3098

❓ Your call: Is a docs change warranted? Yes as specified: an operator judging the agent's privilege boundary reads these two pages, and both would be wrong after the code PR lands.

💡 Solution

• reference/configuration/options.md:
  • Adds the configScope option.
  • Notes that componentsScope accepts absolute paths and, with httpFetch and configScope, is read at startup only.
  • Adds a Filesystem scopes section: a table of the three scopes, what changed from the old directory-wide config, and how configScope replaces the default.
  • The section also states exactly what every scope refuses (key directories, key file names, PEM private-key text), and what is not caught: armorless keys, and non-PEM secrets in the config file.
• release-notes/v5-lincoln/5.4.md: an Agent entry for the narrowed default, configScope, and the refusal rules.
• reference/operations-api/operations.md:
  • The privilege-boundary bullet says what read_file reaches by default, what it reached before v5.4.0, and that widened scopes reach further.
  • set_agent_config lists componentsScope and configScope as rejected with a 400.

❓ Your call: Before merging, reconcile with #712 (Document agent.maxTokens…): it edits the same agent option list and the set_agent_config accepted/rejected keys.

❓ Your call: The badges say v5.4.0, because the code PR lands on main (milestone v5.4) with no 5.3.x cherry-pick. The section badge is type="changed", because the config scope existed and was narrowed.

❓ Your call: It adds a 5.4.md release-notes entry, because the narrowed default changes what an existing agent can read on upgrade.

✅ Verification

• Every claim was checked against the code branch. Three review rounds, each adjudicated by the Harper-domain pass, verified each claim against the implementation (agent/agent.ts resolveScopes, agent/tools/fsTools.ts resolveScoped, agent/operations.ts) and its unit tests.
• Prettier passes with the shared @harperfast/code-guidelines config.

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

Related PRs: #712 overlaps (same agent option list and set_agent_config accepted/rejected keys; reconcile on rebase), #709 overlaps (both add a 5.4.md release-notes section; textual), #671 overlaps (agent wording near the privilege-boundary bullets; textual), #676 independent, #683 independent, #691 independent, #697 independent, #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=3; full=1 @ 2f14755}

_{Review-Attention: skim ~2m (decisions: configscope-replaces-default, release-notes-placement, scopes-section-home, tail-edge-precision) @ 2f14755}

[gemini-code-assist]

Code Review

This pull request updates the documentation and release notes for version 5.4.0 to reflect security-focused changes to the agent's filesystem scopes. Specifically, it documents the new configScope option, details how the default config scope is now restricted to the configuration file itself rather than its parent directory, and outlines how the agent refuses access to sensitive key directories, key files, and PEM private keys. It also specifies that componentsScope and configScope are read at startup only and cannot be modified at runtime. The review feedback suggests refactoring a dense security warning in the operations API documentation into shorter, distinct sentences to improve readability and ensure critical risks are easily scannable.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

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

This preview will update automatically when you push new commits.

[kriszyp]

_{🤖 Reviewed with Codex}

[kriszyp]

Could we fix the core tail_file boundary before promising that a file ending partway through a PEM private key is refused? Its implementation scans only the final 1 MiB plus 64 bytes for the BEGIN marker. If a PEM block in a non-key-named file such as log.txt starts earlier and continues to EOF, tail_file can return trailing base64 key text. This is a code-trace finding; I did not execute a test. A focused check is such a file with BEGIN more than 1 MiB before EOF: tail_file should refuse it. Please make core fail closed for that case, or state the actual limit here and in the release note.