docs: name every reserved sandbox_env key, and guard the list - #936
docs: name every reserved sandbox_env key, and guard the list#936tend-agent wants to merge 2 commits into
Conversation
tend-agent
left a comment
There was a problem hiding this comment.
Two things on the new guard leg and the list it checks.
The documented set is matched over the whole of docs/tend.example.yaml, not the sandbox_env bullet, so two of the twenty names are already satisfied by an unrelated section — ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN appear backticked in the auth guidance further up the file (the claude_oauth_secret/anthropic_api_key_secret discussion). Deleting either from the reserved-key list keeps the hook green, which is the exact drift the leg exists to catch, and the failure text ("NOT named in docs/tend.example.yaml's sandbox_env list") claims more than the check does. Scoping the search to the bullet fixes it — I confirmed the scoped form reports no problems against the current tree and does flag both names when they're removed from the list.
CLAUDE_CODE_REMOTE is grouped under "dummy credentials", but it's CLAUDE_CODE_REMOTE=1 in the AGENT_ENV_FILE heredoc — a prompt-suppression flag, not a credential (the PR description says as much). It's reserved for the same reason as the rest, so no change to the set; just the wrong bucket to teach a reader.
The docs/ file and its plugins/install-tend/.../references/ mirror are byte-identical and sync-install-tend-references enforces that, so the second suggestion has to be applied to both or the hook fails the next commit.
…CLAUDE_CODE_REMOTE The documented set was matched file-wide, so ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN were satisfied by the auth section further up the file — deleting either from the sandbox_env list kept the hook green, which is the drift the leg exists to catch. Anchor on the bullet and stop at the next top-level entry. CLAUDE_CODE_REMOTE=1 suppresses interactive prompts rather than standing in for a credential; give it its own group in both the docs file and its byte-identical references/ mirror.
Problem
docs/tend.example.yamldescribes thesandbox_envreject list as "(proxy routing, CA trust, dummy credentials, PATH)".RESERVED_SANDBOX_ENVingenerator/src/tend/config.pyholds 20 names, and six of them fall outside that parenthetical:HOME,XDG_CONFIG_HOME,XDG_CACHE_HOME,XDG_DATA_HOME,XDG_STATE_HOME— plusCLAUDE_CODE_REMOTE, which isn't a credential.The docs are the only place an adopter meets this set before hitting it. A name reserved in code but missing from the summary reads as settable until
initrefuses it, and the refusal is a hardClickExceptionrather than a warning.XDG_CACHE_HOMEis a realistic thing to want to set.Solution
Replace the parenthetical with the actual set, grouped by what each group protects.
The list would have drifted again on the next reserved key, so this also adds a fourth leg to the existing
sandbox-env-reserved-paritypre-commit hook: every name inRESERVED_SANDBOX_ENVmust appear backticked somewhere indocs/tend.example.yaml. The hook already keepsconfig.py,proxy/setup-sandbox.sh, and theAGENT_ENV_FILEheredoc aligned; the docs were the one copy nothing checked.docs/tend.example.yamljoins the hook'sfiles:pattern so an edit there re-runs it.Testing
Ran the hook body against the working tree — no problems reported across all four legs, and the same script reports the three lowercase proxy spellings as undocumented when the summary keeps them implicit ("and their lowercase spellings"), which is what drove listing every name individually rather than by family.
plugins/install-tend/skills/install-tend/references/tend.example.yamlis a mirror maintained by thesync-install-tend-referenceshook; it's updated in the same commit so the hook has nothing to re-stage. Generator suite: 385 passed. No generated workflow changes — this touches documentation and a lint guard only.