docs(guides): rework agent-install.md — marketplace-first install, disclosure-first trust framing#66
Merged
Merged
Conversation
…sclosure-first trust framing
Rewrites the agent install runbook based on four rounds of live refusal
testing against Sonnet 5 in Claude Code:
- Install is now a pick-your-environment table, routing Claude Code /
Codex / Gemini CLI through their own plugin managers (marketplace add,
then plugin install) — the consent path agents accept readily.
- Removes the agent-directed reassurance preamble. Tested repeatedly:
language that preempts suspicion ("carries no authority", "nothing asks
you to relax your safeguards") pattern-matches to manipulation and
triggers refusals; boring factual copy does not.
- Adds a "What the plugin installs" inventory (skill, MCP server, three
hooks with one-line behaviors, ZERO_PATH_AUTOADD / ZERO_PLUGIN_AUTOUPDATE
opt-outs, source links). Undisclosed shell-rc edits and background
auto-update were what agents dug through the repo to find and then
flagged; disclosing them up front turns that investigation into a read.
- Anchors provenance on the npm package next to the GitHub org, since
"official"-prefixed org names alone draw impersonation suspicion.
- Replaces the chained-trust skill-file line ("authoritative … follow it")
with a parity framing.
- Claude Chat / Cowork routing collapses to a table row pointing at
zero.xyz/install/claude.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
An unauthenticated POST to an API endpoint reads as a telemetry beacon to reviewing agents and draws flags; the request-agent-access web form remains for humans. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
zero.xyz/install.md (which proxies this file) was refusal-tested over four rounds against Sonnet 5 in Claude Code, iterating the copy after each run. Two structural lessons drove this rewrite:
What changed
marketplace add→plugin install; commands verified against each CLI's current docs). Sonnet stated unprompted that it's comfortable with this path because it goes through the harness's own consent UI. npm and the shell fallback remain, ending inzero init.ZERO_PATH_AUTOADD=0/ZERO_PLUGIN_AUTOUPDATE=0opt-outs, and source links.guides/claude-ai.md.whoamipre-check,--finishpolls / safe to re-run, unattendedagent register+agent claim.Deliberately dropped
install-prompt.ts), where it's a principal's instruction rather than a page directing the agent.Docs-only; nothing the plugin ships changed, so no version bump.
Observed result (round 4)
No refusal. Sonnet fetched, summarized accurately, verified npm + repo on its own, and proceeded to a single consent question (about the auto-update default). Remaining friction is outside this file: staging's bot protection 403s non-browser UAs on /install.md, and the auto-update-by-default product question.
🤖 Generated with Claude Code