Skip to content

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.py
index 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 json
from pathlib import Path
@@ -6,32 +12,41 @@ import re
import 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 False
has_content = False
try:
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 False
except (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_content
def 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 / name
if 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 None
raw_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 None
cwd = 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))