[NO-TICKET] Tell agents what to offer when a hosted builder blocks the CLI outright

[mariojgt]

No ticket.

What changed

AGENT-INSTALL.md gains a subsection, When the platform blocks the CLI outright, inside "When your tool will not run this CLI". It covers hosted builders that refuse any third-party CLI that contacts an outside service, and give the person neither a terminal nor a way to approve it. The agent stops, as before, and offers three choices:

• Run setup on a copy of the project outside the builder. Offered only when the builder can export the project or sync it with git. It runs without PATCHSTACK_ENVIRONMENT=sandbox, and .patchstackrc.local.json stays behind.
• Add only the Patchstack Connector, using a site ID from the dashboard and the existing "Plain HTML sites" steps. It says plainly that this means no package checks, no build steps and no runtime protection.
• Stop.

It also says what to do with a package already installed for the attempt (keep it for the first choice, offer to remove it otherwise) and how to report the result: as setup that did not run, not as an install. The Rules list now points to the new subsection.

New field-test persona field-test/personas/base44.md: a synthetic hosted builder that installs packages but refuses third-party CLIs outright, with no approval and no terminal. field-test/README.md lists it and says when to run it.

Why

On such a builder, the existing handoff section has nothing to offer. All three of its options (run it with !, approve it once, add an allow rule) need a terminal or an approval step the person does not have. Agents in that position stop correctly, then improvise the next step. The improvised advice is roughly right but mixes things up. For example, it tells the person to add the hosted-builder sandbox label while running setup on their own machine, and it doesn't say what the widget-only route leaves out.

Fix

The "copy outside the builder" choice explains what happens when the builder's own install or build cannot reach Patchstack. Hook scans fail open (src/build-hook.ts), so the app still builds. The one exception is bun install, where the postinstall scan is not recognised as a hook and fails the install. The doc says to remove that one script in that case.

The persona enforces the block in its own text, the same way restricted-cli does. The right outcome is a clean handoff, which the scorecard cannot score as green, so its rounds are judged by the report (REFUSED COMMANDS and USER MESSAGE) rather than the scorecard. The meta block and the README both say this.

Verified

• npm test: 4279 passed, 7 skipped. This includes the persona-composition test, which now covers base44.md (its provenance block never reaches the agent), and the permission-handoff test.
• npm run build and npm run capabilities:check: capabilities.json is up to date, with no vocabulary change.

Outstanding gate

AGENT-INSTALL.md ships in the tarball, so this needs runs after the release that carries it:

node field-test/run.mjs --persona base44 --rounds 3
node field-test/run.mjs --persona hostile --rounds 3

Read the base44 reports against the new subsection. A red scorecard there is expected.

Out of scope, worth a follow-up

The README describes the widget as a "Report a vulnerability" button once a site is claimed. Agents repeat that when they offer the widget-only route, where a fresh dashboard site may not show a report form at all. That wording needs its own check against the widget's current defaults.

Docs: this is the docs change. The install prompt, README.md and GETTING-STARTED.md are untouched.

🤖 Generated with Claude Code

[mariojgt]

/review

[coderbuds]

Documentation clearly guides handling of blocked CLIs in hosted builders.

🎯 Quality: 95% Elite · 📦 Size: Medium

📈 This month: Your 173rd PR — above team average · Averaging Excellent

_{See how your team is trending →}