A Claude Code / Codex plugin that helps you learn how to build while AI writes the code.
Python
docs: explain session restoration hook behavior
Noah Kimdea3100b9ed3
diff --git a/hooks/session_start.py b/hooks/session_start.pyindex ee77676..b1623a6 100644--- a/hooks/session_start.py+++ b/hooks/session_start.py@@ -1,4 +1,10 @@-"""Read-only SessionStart hook. No network, writes, or transcript parsing."""+"""Restore learning context when Claude Code starts or resumes a session.++Claude Code sends a JSON event on stdin. For a project with active learning notes,+we print JSON instructions telling Claude which files to read. Otherwise we stay+silent. This hook does not teach, write notes, or parse conversation transcripts.+The events that trigger it (including compaction) are configured in hooks.json.+"""import jsonfrom pathlib import Path@@ -6,32 +12,41 @@ import reimport sys+# Find the installed plugin from this script, not from the user's project folder.PLUGIN_ROOT = Path(__file__).resolve().parents[1]def profile_is_active(path):"""Check activation without copying learner notes into hook output."""+ # A linked profile could point outside the selected project's learning notes.if path.is_symlink() or not path.is_file():return Falsehas_content = Falsetry:with path.open(encoding="utf-8") as stream:+ # Scan the whole file: a paused marker can appear after a long profile.+ # Reading line by line avoids loading all its contents into memory.for line in stream:has_content = has_content or bool(line.strip())if re.fullmatch(r"Learning mode:\s*paused\s*", line, re.IGNORECASE):return Falseexcept (OSError, UnicodeError):+ # Missing, unreadable, or invalid text isn't evidence of active learning.return False# Older profiles may lack an explicit mode. Preserve their restoration behavior.return has_contentdef state_directory(cwd):+ """Find the nearest notes directory without crossing a Git project boundary."""+ # Starting in a source subdirectory should still find the project's notes.for directory in (cwd, *cwd.parents):# Prefer the new name at the nearest location; keep legacy notes in place.for name in (".vibe-wise", ".sensible-vibes"):state = directory / nameif state.exists() or state.is_symlink():+ # Stop even if this candidate is invalid. Falling back to a parent+ # could silently load a different project's learner profile.return state if state.is_dir() and not state.is_symlink() else None# A .git file is a worktree boundary too. Never borrow another repo's state.if (directory / ".git").exists():@@ -40,9 +55,12 @@ def state_directory(cwd):def restore(payload):+ """Build Claude's restoration instructions, or return None to do nothing."""if not isinstance(payload, dict) or payload.get("hook_event_name") != "SessionStart":return Noneraw_cwd = payload.get("cwd")+ # Use the event's explicit project path. A relative path would depend on where+ # the hook process happened to start and could select the wrong learning notes.if not isinstance(raw_cwd, str) or not Path(raw_cwd).is_absolute():return Nonecwd = Path(raw_cwd).resolve()@@ -51,6 +69,8 @@ def restore(payload):state = state_directory(cwd)if state is None:return None+ # Installing the plugin alone doesn't enable learning in every repository.+ # First-time onboarding happens through the Learn skill, not this hook.if not profile_is_active(state / "profile.md"):return None@@ -72,6 +92,8 @@ def restore(payload):"questions; do not repeat completed onboarding. If the profile is now ""paused, keep it paused: this hook is not an explicit Learn invocation.")+ # Claude Code adds additionalContext to the model's context. These are reading+ # instructions for Claude; the hook itself hasn't loaded the map or progress.return {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": context}}@@ -79,11 +101,14 @@ def restore(payload):def main():try:+ # This 64 KiB limit bounds the incoming event, NOT the learner's notes.+ # Oversized/truncated JSON fails parsing and takes the quiet error path.payload = json.loads(sys.stdin.read(65536))output = restore(payload)except (OSError, ValueError, TypeError, RecursionError):return # Learning should never prevent a coding session from starting.if output:+ # stdout is the hook's JSON protocol; avoid progress logs or other text.print(json.dumps(output))