From 67168b6eabd953279924e28ba52ec2310c2d5391 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 20 Jun 2026 07:54:52 +0000
Subject: [PATCH] Add Claude Code on the web SessionStart hook for cargo
 warm-up

Web (cloud) sessions start from a fresh clone, so dependencies and the
build cache are cold. This adds a cloud-only SessionStart hook that warms
the Rust workspace before Claude starts working, so `cargo test`,
`cargo clippy`, and `cargo fmt` are immediately usable.

- .claude/hooks/session-start.sh: guarded on CLAUDE_CODE_REMOTE (no-op on
  local checkouts); runs `cargo fetch --locked` then
  `cargo build --workspace --all-targets`; logs verbose cargo output to a
  temp file to keep session context clean; best-effort so a transient
  failure never blocks session startup.
- .claude/settings.json: registers the hook on startup|resume.
- REUSE.toml: cover .claude/** under MPL-2.0 (settings.json carries no
  inline SPDX header; the shell script has one).

Only the pre-installed cargo toolchain is exercised; the optional
Idris2/Zig recipes are not required for the Rust test/lint path and are
intentionally omitted.

Validated in a cloud session: hook exits 0, local-skip is a no-op,
`cargo clippy --workspace` and the integration tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017nyxs8RgqZa72PzrTu3L75
---
 .claude/hooks/session-start.sh | 43 ++++++++++++++++++++++++++++++++++
 .claude/settings.json          | 15 ++++++++++++
 REUSE.toml                     |  1 +
 3 files changed, 59 insertions(+)
 create mode 100755 .claude/hooks/session-start.sh
 create mode 100644 .claude/settings.json

diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh
new file mode 100755
index 0000000..1fd69d9
--- /dev/null
+++ b/.claude/hooks/session-start.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# SessionStart hook for Claude Code on the web (cloud sessions).
+#
+# Prefetches workspace dependencies and warms the Rust build cache so that
+# `cargo test`, `cargo clippy`, and `cargo fmt` are ready immediately when a
+# cloud session starts. Local sessions are skipped — your own machine already
+# has the toolchain and dependencies, and this hook runs everywhere by design.
+#
+# Only the Rust toolchain (cargo) is exercised here: it is pre-installed in
+# cloud sessions and drives the canonical `cargo test` suite. The optional
+# Idris2/Zig pieces (idris-check, zig-build) are not pre-installed and are not
+# required for the Rust test/lint path, so they are intentionally left out.
+#
+# Docs: https://code.claude.com/docs/en/claude-code-on-the-web
+set -euo pipefail
+
+# Cloud-only: do nothing on local checkouts.
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$ROOT" || exit 0
+
+# Keep verbose cargo output out of the session context; log to a temp file.
+LOG="${TMPDIR:-/tmp}/vcl-ut-session-start.log"
+echo "[vcl-ut] Warming Rust workspace (cargo fetch + build --all-targets). Log: $LOG"
+
+# 1. Fetch all workspace dependencies. Cargo.lock is authoritative; fall back to
+#    an unlocked fetch if the lockfile is ever out of date. Idempotent and fast
+#    once the registry cache is populated.
+cargo fetch --locked >"$LOG" 2>&1 || cargo fetch >>"$LOG" 2>&1 || true
+
+# 2. Warm the build cache for every target (lib + bins + tests + benches) so the
+#    first `cargo test` / `cargo clippy` the agent runs is near-instant. Best
+#    effort: a transient failure here must not block the session from starting.
+cargo build --workspace --all-targets >>"$LOG" 2>&1 || true
+
+echo "[vcl-ut] Workspace ready."
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..ea39e04
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/REUSE.toml b/REUSE.toml
index 579aca8..3958fd6 100644
--- a/REUSE.toml
+++ b/REUSE.toml
@@ -86,6 +86,7 @@ SPDX-License-Identifier = "MPL-2.0"
 
 [[annotations]]
 path = [
+  ".claude/**",
   ".devcontainer/**",
   ".github/**",
   ".machine_readable/**",