docs(claude-code-hooks): #30/#31 — task-notification-as-prompt + kind-scoped staleness tracker - #283
Merged
daymade merged 1 commit intoAug 12, 2026
Conversation
3 tasks
…ped staleness tracker New pitfalls folded in from live incidental discoveries on a private hooks repo this session (per user's explicit "沉淀本 session 的新发现" scope), not synthesized on request: #30 — a UserPromptSubmit hook fired on a background subagent's own task-notification arriving, not on any human keystroke; the transcript JSONL distinguishes the two internally (origin.kind: "human" vs "task-notification") but that metadata never reaches the hook's stdin (verified against the live official docs: session_id/transcript_path/cwd/permission_mode/hook_event_name/ prompt_id/prompt, nothing more). SKILL.md's pre-existing "UserPromptSubmit only ever sees user input" claim gets a precise footnote, not a rewrite — the core argument (can't see the model's own current-turn output) still holds. #31 — a compounding-artifact staleness tracker keyed on file *kind* re-flags files nobody touched this round, and a written justification can't clear it because the mechanism only compares timestamps against a kind, never reads the justification prose. An independent fresh-context review (dispatched to re-derive, not just read, the three evidentiary claims from primary sources — official docs via its own WebFetch, transcript shape via its own JSONL parse, tracker ledger via its own file read) found every specific factual claim accurate, but caught two real bugs in #30's prescribed Fix before merge, both independently re-verified here before applying: - the gate condition required promptSource == "typed" in addition to origin.kind == "human", which silently rejects genuine human input arriving mid-turn (promptSource: "queued") — confirmed against a real message in this session's own transcript; fixed to gate on origin.kind alone. - the fix told readers to look up prompt_id in the transcript JSONL — that literal string occurs 0 times across 1745 records; the field is promptId there (camelCase), while the hook's own stdin JSON carries prompt_id (snake_case) — the same twin-blind-spot shape pitfall #20 already warns about on a different field pair. quick_validate passed; full regression audit (compare/classify/verify) passed against the pre-session git-ref baseline, 1 pre-existing candidate (the SKILL.md sentence split), reviewed as preserved_or_moved; security_scan passed, marker refreshed. Manual PII pass on the new content: no absolute paths, no names, no session IDs, no secrets. Independent-review.md persisted to the private PKM knowledge repo (skill-reviews/claude-code-hooks/), per skill-creator discipline #5. daymade-claude-code suite bumped 1.42.0 -> 1.43.0 in marketplace.json. (A second, unrelated piece of work — the macos-watchdog v1.0.0 skill release — was previously bundled into this branch as a parallel-session sweep-in from a shared checkout. It has been split out to its own branch/commit/PR (feat/macos-watchdog, PR #284), unreviewed by me, so this PR now contains only content I've verified.) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CudYBXrK5WyCiKoB2ugbAx
daymade
force-pushed
the
docs/hooks-pitfalls-30-31-task-notification-and-kind-tracker
branch
from
August 12, 2026 03:59
75dd541 to
405dc91
Compare
daymade
deleted the
docs/hooks-pitfalls-30-31-task-notification-and-kind-tracker
branch
August 12, 2026 04:02
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
daymade-claude-codev1.42.0 → v1.43.0): two new pitfall entries inreferences/hook_pitfalls.md, folded in from live incidental discoveries on a private hooks repo this session (not synthesized on request):UserPromptSubmitfires on a background subagent's own task-notification arriving, not just on a human keystroke; the transcript JSONL distinguishes the two internally (origin.kind: "human"vs"task-notification") but that metadata never reaches the hook's stdin. SKILL.md's pre-existing "UserPromptSubmitonly ever sees user input" claim gets a precise footnote (not a rewrite) pointing at the exception.promptSource == "typed", which silently rejects genuine human input arriving mid-turn (promptSource: "queued") — fixed to gate onorigin.kindalone.prompt_idin the transcript JSONL — that string occurs 0 times there; the field ispromptId(camelCase) in the transcript, vsprompt_id(snake_case) in the hook's own stdin JSON.quick_validate+ full regression audit (compare/classify/verify against the pre-session baseline) +security_scanall pass. All CI checks green.skill-reviews/claude-code-hooks/), per skill-creator discipline Add Trail of Bits Security Skills to Related Resources #5 — the review happened and survives past this conversation.Resolved: branch no longer carries unrelated content
An earlier revision of this branch briefly carried a second, unrelated, already-staged piece of work found sitting in a shared checkout's index when the branch was created (the
macos-watchdogv1.0.0 skill release, from a concurrent session). That has since been split out to its own branch/commit/PR — #284 — and this branch was force-pushed to drop it. This PR now contains only theclaude-code-hookscontent described above, which I've reviewed and verified myself. PR #284 remains unmerged and is explicitly flagged there as not reviewed by me.Test plan
quick_validateondaymade-claude-code/claude-code-hooks— passedaudit_skill_regressioncompare/classify/verify againstgit-ref:1c71e5437f79f61e664a5613829984583cd7d9e0— 1 pre-existing candidate, classifiedpreserved_or_moved, verify passedsecurity_scan— passed, marker refreshed🤖 Generated with Claude Code
https://claude.ai/code/session_01CudYBXrK5WyCiKoB2ugbAx