refactor(claude): split cloud bootstrap out of the SessionStart hook

[kyle-sexton]

Migrates the Claude Code cloud bootstrap from the SessionStart-hook layout to the split cloud-bootstrap layout, per melodic-software/claude-code-plugins docs/CLOUD-SESSIONS.md §"Plugins in sessions on this repo" (verified 2026-08-15).

No linked issue

Why

Claude Code builds its plugin/command/skill registry at process start and never re-reads it, so anything a SessionStart hook installs is invisible to the session that ran the hook. Account environments' setup scripts run the repo's committed .claude/cloud-bootstrap.sh (with CLAUDE_CODE_REMOTE=true) after clone and before the session process launches — that pre-launch call is what makes plugins live at turn one. The SessionStart hook stays registered and runs the same script per start/resume as drift repair (the environment cache can be ~7 days stale); its installs go live at the next resume.

What changed

• git mv .claude/hooks/install-plugins.sh → .claude/cloud-bootstrap.sh (history preserved; .claude/hooks/ is now empty and gone). The repo's script was named install-plugins.sh, not session-start.sh — it is the same script the SessionStart hook ran, so it is the one migrated.
• Header rewritten: the script is the repo's cloud bootstrap with two callers (pre-launch environment setup, per-session SessionStart drift repair), not "a SessionStart hook". Provisioning logic, idempotency, bash-3.2 compatibility, and the hook-output reloadSkills emission are unchanged.
• Added the CLAUDE_CODE_REMOTE=true guard the split layout expects — the previous script had none. Outside cloud sessions the script now exits immediately; trusted local machines load the declared marketplace and enabledPlugins from settings.json on their own (the script's own long-standing rationale), so the hook was only doing real work in cloud sessions anyway. Flagging it since it is the one behavioral change beyond the move.
• Repo-root fallback adjusted from /../.. to /.. for the script's new depth (one level shallower); CLAUDE_PROJECT_DIR remains the preferred root source.
• .claude/settings.json SessionStart hook (matcher startup|resume) repointed to bash "$CLAUDE_PROJECT_DIR/.claude/cloud-bootstrap.sh". No other hooks or settings touched.
• No other references existed (docs, CI, scripts were searched for both session-start.sh and install-plugins).

Verification (in a cloud session)

• bash -n: clean. shellcheck: not available in the session container.
• Two runs with CLAUDE_CODE_REMOTE=true: both idempotent no-ops — 65 enabled, 0 newly installed, ~1.2 s each.
• Run with CLAUDE_CODE_REMOTE unset: exits in ~3 ms, no output, claude plugin list state hash unchanged.
• Root-fallback check with CLAUDE_PROJECT_DIR unset, invoked from outside the repo: resolves to the repo root (not its parent) and reads .claude/settings.json correctly.

Related

• N/A

🤖 Generated with Claude Code

https://claude.ai/code/session_017ZRCysRUU7pARyJwcwg3TJ

---

Generated by Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 1m 55s —— View job

---

Code review (/review:code-review)

• Gather context (PR diff, changed files, CLAUDE.md/REVIEW.md)
• Invoke /review:code-review skill and follow its procedure
• Check for stale references to the old hook path
• Post summary review comment

Skip gate: did not apply — PR is open, not a draft, and the change (adding a CLAUDE_CODE_REMOTE guard) is a real behavioral change, not purely mechanical.

Scope: .claude/cloud-bootstrap.sh (new, via git mv), .claude/hooks/install-plugins.sh (deleted), .claude/settings.json.

Findings

None at the code-review bar (correctness/maintainability). Specifically checked and found sound:

• Path-depth math: the repo-root fallback changed from dirname/../.. to dirname/.. (.claude/cloud-bootstrap.sh#L23). The script moved from .claude/hooks/ (two levels below root) to .claude/ (one level below root), so the shallower fallback is correct.
• Body diff: the marketplace/install logic (.claude/cloud-bootstrap.sh#L29-63) is byte-for-byte identical to the deleted script apart from the cloud-bootstrap:/install-plugins: log-prefix rename — no logic drift introduced by the move.
• Guard placement: [[ "${CLAUDE_CODE_REMOTE:-}" == "true" ]] || exit 0 (.claude/cloud-bootstrap.sh#L22) sits after set -euo pipefail and correctly no-ops under set -u for an unset var.
• No stale references: searched the committed tree (git grep at HEAD) for install-plugins / hooks/install-plugins / session-start.sh — none found. .claude/settings.json#L86 is repointed to cloud-bootstrap.sh.
• Syntax: manually read through the script; no unbalanced quoting/brackets/heredoc issues.

One item I can't independently verify and am flagging only for visibility, not as a finding: the guarded early-exit means the SessionStart hook now does nothing on local/trusted sessions (previously it ran unconditionally there too). The PR's rationale — that trusted local machines already load the declared marketplace/enabledPlugins from settings.json without this script — lives in the melodic-software/claude-code-plugins repo, outside this diff, so I'm noting it as author-claimed rather than something I confirmed.

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.