[rabbilyasar]

Closes #89

In one line: agent install lets Claude Code run the four commands the instructions name without a permission prompt, and prints a flag that does the same for unattended runs.

Problem

In #63's live run, Claude needed approval to run envshield agent guide and the check, so it skipped both. It relied on the hook alone and left out type and the .env.example update (BL-206).

Design (maintainer decisions on #89)

• Allow rules. agent install adds exact rules to .claude/settings.json permissions.allow: Bash(envshield agent guide), Bash(envshield check --since HEAD --code-only --json), Bash(envshield check --json), Bash(envshield schema sync). No prefix rules. Added once; other permissions keys and rules are kept, and a user's deny still wins. Malformed permissions leaves the file unchanged. Nothing is set for Codex: its approval policy is per user.
• Limit found while implementing. Claude Code applies a project's allow rules only after the workspace trust dialog is accepted, and claude -p never shows it. A headless run in an untrusted folder still asked before each command. Option 1 (chosen): keep the rules for trusted interactive sessions, where the trust dialog lists them, and have agent install (and init's offer) print the same rules as --allowedTools "..." for claude -p and CI. That flag needs no trust.

Alternatives

• Prefix rules (Bash(envshield check:*)): rejected, wider than needed.
• Docs only, no rules (option 2): rejected.

Security

The rules cover read-only commands, plus schema sync, which writes only .env.example, built from the schema with no secret values. They are exact strings, so a chained command (envshield check --json; curl ...) still prompts. Writes still go through open_for_write.

Compatibility

Re-running agent install on a #63 install adds the rules and keeps everything else.

Tests

• 7 new or updated tests in envshield/tests/test_agent_setup.py. They check that the rules are exactly the commands the instructions name (no wildcards); added once and kept beside the user's allow/deny/ask/defaultMode; added to an older install; none for Codex; malformed permissions leaves the file unchanged; a declined hook replacement still adds the rules; the flag is printed.
• Full suite: 2320 passed, 1 skipped. ruff check and ruff format --check clean.

Live runs (fixture project, recorded in BL-206)

• claude -p --permission-mode acceptEdits with the rules in an untrusted folder: still asked before running the guide and the check. That's the trust limit above.
• Same run with --allowedTools <the four rules>: Claude ran agent guide and declared SLACK_WEBHOOK_URL with type = "url", secret = true and the services line. It ran schema sync (.env.example updated) and both checks. The only prompts were for shell glue it chained on (echo, cat > app.py). No canary value in the transcript.
• Not tested: the trusted interactive case. Marking a folder as trusted means editing ~/.claude.json, which the session's safety check blocked.

Product / market impact

Table stakes: it removes friction from the agent loop #63 set up.

🤖 Generated with Claude Code