Add SessionStart hook to install Swift toolchain for Claude Code on the web #295

Summary

Add a SessionStart hook so Claude Code on the web sessions can run swift build, swift test, swift-format, swiftlint, etc. without manual setup. Sessions today start without a Swift toolchain, so any code-validation step the agent attempts fails immediately.

Proposed approach

Two new files under .claude/:

• .claude/hooks/session-start.sh — install Swift + project tooling. Guarded by CLAUDE_CODE_REMOTE=true so it's a no-op for local sessions.
• .claude/settings.json — register the hook for the SessionStart event.

The script should:

1. Install Swift's runtime apt deps on Ubuntu 24.04 (libcurl4-openssl-dev, libxml2-dev, libz3-dev, libstdc++-13-dev, etc.). Tolerate failures from unrelated third-party PPAs (apt-get update -qq || true).
2. Download the Swift 6.1 toolchain (matches Package.swift's swift-tools-version: 6.1) from https://download.swift.org/swift-6.1-release/ubuntu2404/swift-6.1-RELEASE/swift-6.1-RELEASE-ubuntu24.04.tar.gz into ~/.swift/.
3. Install mise and run mise install against the existing mise.toml to fetch swift-format 602.0.0, swiftlint 0.62.2, periphery 3.7.4, swift-openapi-generator 1.10.3.
4. Persist PATH (Swift bin + ~/.local/bin) and the mise env into $CLAUDE_ENV_FILE so they're visible to the session.
5. Be idempotent — skip apt/Swift/mise installs when already present.

Open questions

• Sync vs. async hook: synchronous guarantees tools are ready before the agent can run anything (no race), but adds ~2–4 min to first-time session startup (cached after that). Async swaps the trade-off. Recommendation: start synchronous.
• Swift version pinning: the hook should use 6.1 to match swift-tools-version. CI tests against 6.1/6.2/6.3 — agent sessions only need one.

Reference implementation

A working draft was prototyped in this branch's history (commit 36f52f8, since reverted in abf43b9) on PR for #256. It validated the apt step locally; the Swift download and mise install couldn't be exercised in the prototyping sandbox because download.swift.org was on a host allowlist denylist there. The actual web sandbox is expected to permit it.

Acceptance criteria

• New web session starts with swift --version returning Swift 6.1.
• swift build, swift test, swift-format, swiftlint, periphery, swift run swift-openapi-generator all resolvable on PATH.
• Hook is a no-op on local (non-remote) sessions.
• Re-running the hook after a cached install completes in seconds, not minutes.