Repository navigation
feat: add experimental Session Hooks lab - #22
Conversation
Three independent Claude Code hooks, Python stdlib only: - session_title_nudge (UserPromptSubmit): remind the model to retitle the session with 2-4 keywords when its main thread moves, at most once per interval; never renames anything itself. - archive_readiness_nudge (Stop): require one archive-check line judging the whole session at the end of every final answer; never archives. - needs_me_surface (SessionStart + UserPromptSubmit): inject unchecked items of one "needs me" checklist with per-session fingerprint dedup, pagination, and a four-bucket accounting rule; read-only, fails to UNKNOWN instead of a false empty list. Bilingual READMEs, example settings and checklist, synthetic-stdin tests wired into lab CI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Install: never overwrite an existing needs-me checklist or symlink; re-running the install snippet is now safe. - needs_me_surface: SessionStart persists a fresh cursor, so later pages are no longer silently dropped after a session resumes. - session_title_nudge: stale-state cleanup is best effort per file and runs after the reminder is printed, so a concurrent delete can no longer swallow and suppress a nudge. Same hardening in needs_me_surface. - Regression tests for all three (fail on the previous code). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 24ae45b76c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| for task in payload.get("background_tasks") or []: | ||
| if isinstance(task, dict) and task.get("status") in _ACTIVE: | ||
| return {"decision": "block", "reason": _msg(RUNNING)} |
There was a problem hiding this comment.
When the session has a scheduled wakeup but no background task, this loop accepts Archive check: ready, so the user can be told the session is safe to archive even though session-scoped work is still pending. Claude Code's Stop input schema provides session_crons specifically alongside background_tasks to distinguish a completed session from one waiting to wake up; inspect that array before accepting the ready verdict.
AGENTS.md reference: AGENTS.md:L10-L10
Useful? React with 👍 / 👎.
| data = json.loads(sys.stdin.read() or "{}") | ||
| if not isinstance(data, dict): | ||
| return | ||
| sid = str(data.get("session_id") or "").strip() |
There was a problem hiding this comment.
When a user previously named a session with /rename or --name without discussing that action in the conversation, this hook discards the session_title field and gives the model no reliable way to follow its instruction to ask before renaming. The UserPromptSubmit schema supplies session_title whenever a custom title exists, so the hook should use it to suppress or qualify the nudge; otherwise a manually chosen title can be overwritten without confirmation.
AGENTS.md reference: AGENTS.md:L10-L10
Useful? React with 👍 / 👎.
What
Adds an experimental Session Hooks lab (
labs/session-hooks/) with three standard-library-only Claude Code hooks:Bilingual READMEs, example settings/checklist (synthetic data), and 20 tests. Main README, CHANGELOG (Unreleased) and lab CI wired.
Review
cpcould overwrite an existing checklist; resume dropped later pages; concurrent cleanup could swallow the title nudge) → fixed with regression tests in 24ae45b → second pass SHIP../scripts/verify.shpasses; 20/20 lab tests pass.Not verified
Not exercised inside a live Claude Code host in this PR (the hooks are generalized from versions in daily use).
background_tasksin the Stop payload may not exist on every Claude Code version — documented in the README.🤖 Generated with Claude Code