Create hooks intelligence process: scan CC issues/releases and monitor ecosystem repos

[edmondscommerce]

Overview

We need a repeatable process for keeping an up-to-date, accurate knowledge base of how the Claude Code hook system works — including undocumented behaviour, schema changes, best practices, and what the broader ecosystem is doing.

Motivation: Issue #23 (sessionStart advisories not reaching Claude) was discovered through direct experimentation. A systematic intelligence-gathering process would have caught this earlier — the upstream issue was filed by others long before we hit it.

What to Monitor

1. Claude Code GitHub Issues (anthropics/claude-code)

Search for hook-related issues regularly:

• Label: hooks, hook
• Keywords: hooks, PreToolUse, PostToolUse, SessionStart, systemMessage, additionalContext, hookSpecificOutput
• Focus on: bugs, behaviour changes, schema clarifications, undocumented fields

Key issues already found:

• #15203 — Warn rules only shown to user, not Claude AI (exactly hit by us in SessionStart/lifecycle handler content visible to human only, not to Claude AI #23)
• #10373 — SessionStart hooks not working for new conversations
• #15344 — SessionStart systemMessage not shown in VS Code

2. Claude Code Releases (anthropics/claude-code)

Scan each release changelog for hook-related changes:

• New fields added to hook response schema
• Behaviour changes for existing fields
• New event types
• Breaking changes to existing hook contracts
• New hook configuration options

3. Ecosystem Repos to Monitor

• hookify — mentioned in [BUG] Hookify warn rules don't educate Claude AI - messages only shown to user anthropics/claude-code#15203, implementing hooks patterns worth studying
• hookify-plus — extended version, possibly more advanced patterns
• claude-code-hooks-mastery — appeared in search results, likely documents best practices
• claude-mem (docs.claude-mem.ai/hooks-architecture) — hooks architecture documentation
• Any other repos with significant hooks implementations

4. Official Documentation

Monitor for changes at:

• docs.claude.com/en/docs/claude-code/hooks
• code.claude.com/docs/en/hooks
• Anthropic blog posts about Claude Code

Process Design

Option A: Periodic Research Skill

A /hooks-research skill that, when run:

1. Queries gh api for new issues in anthropics/claude-code matching hook keywords since last run
2. Queries gh api for new releases in anthropics/claude-code since last run
3. Fetches README/docs from ecosystem repos
4. Summarises findings and flags anything relevant to this daemon
5. Suggests updates to our knowledge base documents

Option B: Knowledge Base Documents

Static documents in CLAUDE/HooksKnowledge/ that are updated manually when research is done:

• KNOWN_BEHAVIOUR.md — documented + observed hook behaviour (including undocumented)
• SCHEMA.md — current hook response schema with field descriptions
• ECOSYSTEM.md — index of relevant external repos and what they do
• OPEN_UPSTREAM_ISSUES.md — upstream Claude Code issues relevant to this daemon
• CHANGELOG_NOTES.md — hook-relevant notes from each Claude Code release

Option C: Both

Automated skill for discovery + structured knowledge base for storage.

Knowledge Gaps to Fill Now

From issue #23 investigation, we know:

• systemMessage = human terminal only
• additionalContext (in hookSpecificOutput) = Claude's context window
• These are documented but not prominently

What we still don't know:

• Full list of supported fields for each event type
• Whether additionalContext concatenation order is guaranteed
• What changed in Claude Code 2.1.0 regarding SessionStart context injection
• Whether additionalContext works for ALL event types or just some
• Exact behaviour of exit code 2 (stderr → Claude)

Proposed Next Steps

1. Create CLAUDE/HooksKnowledge/ directory with initial documents
2. Define the research skill specification
3. Do a one-time deep scan of anthropics/claude-code issues and recent releases
4. Document findings
5. Set a reminder cadence (e.g. monthly) to run the research skill

Related

• Issue SessionStart/lifecycle handler content visible to human only, not to Claude AI #23 — sessionStart advisories not reaching Claude
• CLAUDE/ARCHITECTURE.md — current hooks architecture docs
• CLAUDE/Code/HooksSystem.md — hooks system documentation