Skip to content

docs: name every reserved sandbox_env key, and guard the list - #936

Open
tend-agent wants to merge 2 commits into
mainfrom
docs/sandbox-env-reserved-keys
Open

docs: name every reserved sandbox_env key, and guard the list#936
tend-agent wants to merge 2 commits into
mainfrom
docs/sandbox-env-reserved-keys

Conversation

@tend-agent

Copy link
Copy Markdown
Collaborator

Problem

docs/tend.example.yaml describes the sandbox_env reject list as "(proxy routing, CA trust, dummy credentials, PATH)". RESERVED_SANDBOX_ENV in generator/src/tend/config.py holds 20 names, and six of them fall outside that parenthetical: HOME, XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_STATE_HOME — plus CLAUDE_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 init refuses it, and the refusal is a hard ClickException rather than a warning. XDG_CACHE_HOME is 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-parity pre-commit hook: every name in RESERVED_SANDBOX_ENV must appear backticked somewhere in docs/tend.example.yaml. The hook already keeps config.py, proxy/setup-sandbox.sh, and the AGENT_ENV_FILE heredoc aligned; the docs were the one copy nothing checked. docs/tend.example.yaml joins the hook's files: 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.yaml is a mirror maintained by the sync-install-tend-references hook; 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.

@tend-agent tend-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .pre-commit-config.yaml Outdated
Comment thread docs/tend.example.yaml Outdated
Comment thread plugins/install-tend/skills/install-tend/references/tend.example.yaml Outdated
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant