@codeyam/codeyam-cli 0.1.0-staging.62d4615 → 0.1.0-staging.73a4bf4

package/codeyam-cli/templates/{codeyam:memory.md → codeyam-memory.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:memory
+name: codeyam-memory
 autoApprove: true
 description: |
   Generate and maintain Claude Rules for your codebase based on thorough analysis.
@@ -13,19 +13,14 @@ This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that
 
 ## Core Principle: Document Confusion, Not Information
 
-**Good rules** explain things that are NOT obvious from reading the code:
+**Valuable rules** capture knowledge that reading the code alone wouldn't reveal:
 
 - Historical context (why code evolved this way)
 - Hidden relationships (files that must change together)
 - Gotchas that caused bugs
 - Non-obvious conventions
 
-**Bad rules** document things Claude can easily ascertain:
-
-- What functions do (Claude can read the code)
-- Type definitions (Claude can see them)
-- Directory structure (Claude can explore it)
-- Basic patterns (Claude knows common patterns)
+Skip documenting things Claude can determine by reading code: function signatures, type definitions, directory structure, and common patterns.
 
 ## When to Use This Skill
 
@@ -41,7 +36,9 @@ Check if this is the first time running memory.
 
 ### 1A. Add Documentation Section to CLAUDE.md
 
-If CLAUDE.md doesn't contain a "When Confused / With Mistakes" section, add close to the top:
+If CLAUDE.md already contains a "Documenting Confusion / Mistakes" section, skip this step entirely.
+
+Otherwise, add **only** the section below — do not modify or add any other content to CLAUDE.md. If CLAUDE.md doesn't exist, create it with just a `# Project` heading followed by this section:
 
 ```markdown
 ## Continuous Documentation
@@ -61,6 +58,8 @@ It is very important to document any tribal knowledge, complex architectural dec
 Please see `.codeyam/rules/instructions.md` for guidance.
 ```
 
+**Important:** Do not add project descriptions, architecture summaries, or any other content to CLAUDE.md. Only add the exact section above.
+
 ### 1B. Verify Instructions File
 
 Check that `.codeyam/rules/instructions.md` exists (it should be created during `codeyam init`). If missing, copy it from `codeyam-cli/templates/rules-instructions.md`.
@@ -275,7 +274,7 @@ Before generating each rule, verify it passes these tests:
 
 **2. Code-derivable check**: Read the files the rule will cover. Could the rule's content be determined by reading those files alone?
 
-- If YES → rule probably not needed (Claude can read the code)
+- If YES → the code is its own documentation — prefer keeping rules for non-derivable insights
 - If NO (historical context, edge cases, non-obvious behavior) → rule is valuable
 
 **3. Prevention check**: Would this rule have prevented one of the confusion commits you found?
@@ -301,7 +300,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 - Not code-derivable: Code doesn't explain why boundary checking matters
 - Prevention: Would prevent future prefix-matching bugs
 
-**❌ Bad rule** (fails tests):
+**Compare with a weaker alternative** (fails the checks):
 
 ```markdown
 ## Running Tests
@@ -309,9 +308,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
 ```
 
-- No confusion evidence (no commits showing people struggled with this)
-- Code-derivable: Anyone can see `jest.config.ts` exists
-- Doesn't prevent any confusion
+- No confusion evidence, code-derivable, and wouldn't prevent future mistakes
 
 ### 5B. Rule File Guidelines
 
@@ -319,17 +316,13 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
    - Rule for `src/api/` → `.claude/rules/src/api/architecture.md`
    - Rule for testing patterns → `.claude/rules/testing-patterns.md`
 
-2. **Paths must be specific**
-   - Good: `paths: ['src/api/**/*.ts']`
-   - Bad: `paths: ['**/*.ts']` (too broad, wastes context)
+2. **Paths must be specific** — use `paths: ['src/api/**/*.ts']` rather than `'**/*.ts'` (too broad wastes context)
 
 3. **Content should explain "why" not just "what"**
    - Focus on the reasoning, history, or gotcha
    - Be concise - every word costs context
 
-4. **Timestamp must be current**
-   - Use ISO 8601 format: `2026-01-27T15:30:00Z`
-   - This enables the pre-commit hook enforcement
+4. **Audit dates live in `.claude/codeyam-rule-state.json`** (managed by `codeyam memory touch`). Keep rule frontmatter limited to `paths`.
 
 ### Rule Template
 
@@ -337,7 +330,6 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
 ---
 paths:
   - 'specific/path/**/*.ts'
-timestamp: [CURRENT_ISO_TIMESTAMP]
 ---
 
 ## [Clear, Descriptive Title]
@@ -374,7 +366,7 @@ After generating rules based on your analysis and user answers:
 5. **Remind the user** to commit the new rules:
    ```
    git add .claude/rules/ .codeyam/rules/
-   git commit -m "Add rules for Claude Code (generated via /codeyam:memory)"
+   git commit -m "Add rules for Claude Code (generated via /codeyam-memory)"
    ```
 
 ---
@@ -394,11 +386,11 @@ After generating rules based on your analysis and user answers:
 The pre-commit hook **blocks commits** when:
 
 - Code files matching a rule's `paths` are modified
-- The rule's `timestamp` is older than the code changes
+- The rule's `lastAuditedAt` in `.claude/codeyam-rule-state.json` is older than the code changes
 
 To proceed:
 
 1. Review the flagged rule(s)
 2. Update content if needed
-3. Update the `timestamp` to current time
+3. Run `codeyam memory touch` to mark rules as audited in `.claude/codeyam-rule-state.json`
 4. Stage and commit

package/codeyam-cli/templates/{codeyam:new-rule.md → codeyam-new-rule.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:new-rule
+name: codeyam-new-rule
 autoApprove: true
 description: |
   Create a new Claude Rule for documenting codebase patterns.

package/codeyam-cli/templates/{codeyam:setup.md → codeyam-setup.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:setup
+name: codeyam-setup
 autoApprove: true
 description: |
   Use this skill when the user asks to "setup CodeYam" or needs to configure CodeYam for their project.
@@ -52,6 +52,18 @@ codeyam validate-mock .codeyam/universal-mocks/{path-to-your-mock}
 
 ## Setup Workflow
 
+### Step 0: Ensure Simulation Infrastructure
+
+Before configuring the dev server or mocks, ensure the simulation infrastructure is installed.
+
+```bash
+codeyam setup-simulations
+```
+
+This is **idempotent** — if already set up, each step is detected and skipped. On first run it installs analyzer dependencies, Playwright chromium, and creates baseline entities (several minutes). Subsequent runs complete in seconds.
+
+If it fails with "No web applications found", the project doesn't support simulations — inform the user and stop.
+
 ### Step 1: Configure Webapp Start Command
 
 **ACTION 1:** Read configuration files:

package/codeyam-cli/templates/{codeyam:sim.md → codeyam-sim.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:sim
+name: codeyam-sim
 autoApprove: true
 description: |
   Use this skill to create interactive simulations of components and functions using CodeYam's analysis.

package/codeyam-cli/templates/{codeyam:test.md → codeyam-test.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:test
+name: codeyam-test
 autoApprove: true
 description: |
   Use this skill to write comprehensive unit and integration tests using CodeYam's mock generation.

package/codeyam-cli/templates/{codeyam:verify.md → codeyam-verify.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:verify
+name: codeyam-verify
 autoApprove: true
 description: |
   Use this skill after making code changes that impact application functionality.

package/codeyam-cli/templates/rule-notification-hook.py

@@ -7,10 +7,11 @@ in /tmp/claude-rule-markers/ when they create or update rules.
 This hook checks for those files on each user message, prints them to stdout
 (which Claude sees as injected context), and deletes them.
 
-Supports three notification files (legacy combined + split agents):
+Supports four notification files (legacy combined + split agents):
 - rule-notification.md (legacy/backward-compat)
 - rule-notification-stale.md (stale rules agent)
 - rule-notification-conversation.md (conversation review agent)
+- rule-notification-interruption.md (interruption review agent)
 """
 
 import os
@@ -21,6 +22,7 @@ NOTIFICATION_FILES = [
     'rule-notification.md',
     'rule-notification-stale.md',
     'rule-notification-conversation.md',
+    'rule-notification-interruption.md',
 ]
 
 

package/codeyam-cli/templates/rule-reflection-hook.py

@@ -2,11 +2,13 @@
 """
 Rule reflection hook for Claude Code.
 
-Two responsibilities, now split into independent agents:
-1. Check for stale rules (files changed since rule was last reviewed) and prompt review
-2. Review conversation for confusion signals (mistakes, corrections, interruptions)
+Handles two hook events:
+1. Stop — Reviews completed turns for stale rules and conversation confusion signals
+2. UserPromptSubmit — Detects user interruptions (Escape/Ctrl+C) by checking if the
+   Stop hook's marker file is stale, then spawns a rule-reflection agent focused on
+   the interruption signal
 
-Each fires as a separate `claude -p` invocation so the LLM can focus on one task at a time.
+Each review fires as a separate `claude -p` invocation so the LLM can focus on one task at a time.
 Stays silent if there's nothing to review.
 
 Prompt text lives in templates/prompts/*.txt (single source of truth shared with TypeScript tests).
@@ -16,6 +18,7 @@ import json
 import os
 import subprocess
 import sys
+from datetime import datetime
 from pathlib import Path
 
 MIN_USER_TURNS = 3  # Minimum user turns before checking for confusion
@@ -117,6 +120,33 @@ def read_rule_content(rule_name):
     return text
 
 
+def load_memory_settings():
+    """
+    Load memory settings from .codeyam/config.json.
+    Returns dict with safe defaults when absent or malformed.
+    """
+    defaults = {
+        'conversationReflection': True,
+        'ruleMaintenance': True,
+        'promptModel': 'haiku',
+    }
+    try:
+        project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+        config_path = os.path.join(project_dir, '.codeyam', 'config.json')
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        memory = config.get('memory', {})
+        if not isinstance(memory, dict):
+            return defaults
+        return {
+            'conversationReflection': memory.get('conversationReflection', True),
+            'ruleMaintenance': memory.get('ruleMaintenance', True),
+            'promptModel': memory.get('promptModel', 'haiku'),
+        }
+    except (IOError, json.JSONDecodeError, KeyError):
+        return defaults
+
+
 def get_stale_rules():
     """
     Run `codeyam memory status` and parse the output to find stale rules.
@@ -154,8 +184,8 @@ def get_stale_rules():
                 # Look for the next few lines for details
                 for j in range(i + 1, min(i + 4, len(lines))):
                     detail = lines[j].strip()
-                    if detail.startswith('Rule timestamp:'):
-                        rule_info['rule_timestamp'] = detail.replace('Rule timestamp:', '').strip()
+                    if detail.startswith('Last audited:'):
+                        rule_info['last_audited'] = detail.replace('Last audited:', '').strip()
                     elif detail.startswith('Newest file:'):
                         rule_info['newest_file'] = detail.replace('Newest file:', '').strip()
                     elif detail.startswith('File modified:'):
@@ -250,6 +280,28 @@ def get_conversation_context(transcript_path, last_line):
     return user_turn_count, conversation_snippets, modified_files, current_line_count
 
 
+def has_assistant_messages(transcript_path, start_line):
+    """
+    Check if there are any assistant messages in the transcript after start_line.
+    Used to confirm Claude actually started responding before treating a gap as an interruption.
+    """
+    try:
+        with open(transcript_path, 'r') as f:
+            all_lines = f.readlines()
+    except IOError:
+        return False
+
+    for line in all_lines[start_line:]:
+        try:
+            obj = json.loads(line)
+            if obj.get('type') == 'assistant':
+                return True
+        except (json.JSONDecodeError, KeyError):
+            continue
+
+    return False
+
+
 def build_stale_rules_context(stale_rules):
     """Build context content for stale rules review."""
     parts = []
@@ -261,7 +313,7 @@ def build_stale_rules_context(stale_rules):
     parts.append("For each rule, review the rule content and the diff of changes, then:")
     parts.append("1. Determine if the rule content needs updating based on the code changes")
     parts.append("2. Update the rule if needed")
-    parts.append("3. ALWAYS update the timestamp (run `codeyam memory touch`)\n")
+    parts.append("3. ALWAYS run `codeyam memory touch` to mark rules as audited\n")
 
     for rule in stale_rules:
         parts.append(f"### {rule['name']}")
@@ -273,8 +325,8 @@ def build_stale_rules_context(stale_rules):
             parts.append(f"  Changed file: {rule['newest_file']}")
         if rule.get('file_modified'):
             parts.append(f"  File modified: {rule['file_modified']}")
-        if rule.get('rule_timestamp'):
-            parts.append(f"  Rule timestamp: {rule['rule_timestamp']}")
+        if rule.get('last_audited'):
+            parts.append(f"  Last audited: {rule['last_audited']}")
         if rule.get('diff'):
             parts.append(f"  Changes:")
             for line in rule['diff'].split('\n'):
@@ -314,7 +366,41 @@ def build_conversation_context(conversation_snippets, modified_files):
     return '\n'.join(parts)
 
 
-def spawn_claude_agent(prompt, log_file, project_dir):
+def build_interruption_context(conversation_snippets, follow_up_prompt, modified_files):
+    """Build context content for an interrupted session review."""
+    parts = []
+    parts.append("## Interruption Review\n")
+    parts.append(
+        "The user interrupted Claude mid-response — a strong signal of confusion or misunderstanding. "
+        "Review the interrupted conversation and the user's follow-up to identify rule-worthy learnings.\n"
+    )
+
+    # Load guidance from shared template file
+    guidance = (PROMPTS_DIR / 'conversation-guidance.txt').read_text()
+    parts.append(guidance)
+
+    if modified_files:
+        parts.append("Files modified this session:")
+        for file_path, tool_name in sorted(modified_files):
+            parts.append(f"- {file_path} ({tool_name})")
+        parts.append("")
+
+    parts.append("### Session transcript\n")
+    summary_lines = []
+    for snippet in conversation_snippets:
+        role = snippet['role']
+        content = snippet['content'].replace('\n', ' ')
+        summary_lines.append(f"[{role}]: {content}")
+    parts.append('\n'.join(summary_lines))
+
+    parts.append("")
+    parts.append("### User's follow-up after interruption\n")
+    parts.append(follow_up_prompt)
+
+    return '\n'.join(parts)
+
+
+def spawn_claude_agent(prompt, log_file, project_dir, model='haiku'):
     """Spawn a detached claude -p agent as a background process."""
     try:
         log_fh = open(log_file, 'w')
@@ -322,7 +408,8 @@ def spawn_claude_agent(prompt, log_file, project_dir):
         env['CODEYAM_RULE_AGENT'] = '1'
         subprocess.Popen(
             ['claude', '-p', prompt,
-             '--model', 'haiku',
+             '--model', model,
+             '--no-session-persistence',
              '--output-format', 'stream-json', '--verbose',
              '--allowedTools', 'Read,Edit,Write,Bash,Glob,Grep'],
             cwd=project_dir,
@@ -335,21 +422,43 @@ def spawn_claude_agent(prompt, log_file, project_dir):
         pass  # claude CLI not available, skip silently
 
 
-def main():
-    # Read hook input from stdin
-    try:
-        hook_input = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return
+def read_marker(marker_file):
+    """
+    Read marker file. Returns (last_line, written_by_stop).
+    Format: "<line_count>" or "<line_count> stop" — the suffix distinguishes
+    whether the Stop hook wrote this marker (normal completion) vs the
+    UserPromptSubmit handler (interruption detection).
+    """
+    if marker_file.exists():
+        try:
+            text = marker_file.read_text().strip()
+            parts = text.split()
+            line_count = int(parts[0])
+            was_stop = len(parts) > 1 and parts[1] == 'stop'
+            return line_count, was_stop
+        except (ValueError, IOError):
+            pass
+    return 0, False
+
+
+def write_marker(marker_file, line_count, source='submit'):
+    """Write marker with source tag. source is 'stop' or 'submit'."""
+    marker_file.write_text(f'{line_count} {source}')
+
+
+def handle_stop(hook_input):
+    """
+    Handle the Stop hook event.
+    Reviews completed turns for stale rules and conversation confusion signals.
+
+    Important: the fast work (transcript parsing, marker update, conversation
+    agent spawn) runs first. The slow `get_stale_rules()` call (~10s) runs last
+    so the hook timeout doesn't kill us before the critical work is done.
+    """
+    settings = load_memory_settings()
 
     session_id = hook_input.get('session_id', '')
     transcript_path = hook_input.get('transcript_path', '')
-    stop_hook_active = hook_input.get('stop_hook_active', False)
-
-    # Prevent infinite loops — stop_hook_active covers same-process recursion,
-    # env var covers spawned subagent sessions triggering the hook on exit
-    if stop_hook_active or os.environ.get('CODEYAM_RULE_AGENT'):
-        return
 
     if not session_id or not transcript_path:
         return
@@ -358,58 +467,23 @@ def main():
     marker_dir.mkdir(exist_ok=True)
     marker_file = marker_dir / f'{session_id}.marker'
 
-    # Read last checked line
-    last_line = 0
-    if marker_file.exists():
-        try:
-            last_line = int(marker_file.read_text().strip())
-        except (ValueError, IOError):
-            last_line = 0
+    last_line, _ = read_marker(marker_file)
 
-    # Check for stale rules
-    stale_rules = get_stale_rules()
-
-    # Get conversation context
+    # Fast: parse transcript for conversation context
     user_turn_count, conversation_snippets, modified_files, current_line_count = get_conversation_context(
         transcript_path, last_line
     )
 
-    # Determine what to include in review
-    has_stale_rules = len(stale_rules) > 0
-    has_conversation = len(conversation_snippets) > 0
-
-    # Only fire if there's something to review
-    if not has_stale_rules and not has_conversation:
-        return
-
-    # Update marker
-    marker_file.write_text(str(current_line_count))
+    # Update marker immediately so UserPromptSubmit knows Stop ran,
+    # even if we get killed during the slow stale rules check below
+    write_marker(marker_file, current_line_count, 'stop')
 
     project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
-
-    # Unique suffix per invocation so each Stop produces a distinct transcript
-    from datetime import datetime
     invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
     invocation_id = f'{session_id}-{invocation_ts}'
 
-    # Spawn independent agent for stale rules review
-    if has_stale_rules:
-        stale_context = build_stale_rules_context(stale_rules)
-        stale_context_file = marker_dir / f'{invocation_id}-stale.context'
-        stale_context_file.write_text(stale_context)
-
-        stale_log_file = marker_dir / f'{invocation_id}-stale.log'
-        stale_notification_file = marker_dir / 'rule-notification-stale.md'
-        stale_prompt = load_prompt_template(
-            'stale-rules-prompt.txt',
-            CONTEXT_FILE=str(stale_context_file),
-            NOTIFICATION_FILE=str(stale_notification_file),
-            PROJECT_DIR=project_dir,
-        )
-        spawn_claude_agent(stale_prompt, stale_log_file, project_dir)
-
-    # Spawn independent agent for conversation review
-    if has_conversation:
+    # Fast: spawn conversation review agent first (if enabled)
+    if settings['conversationReflection'] and len(conversation_snippets) > 0:
         conv_context = build_conversation_context(conversation_snippets, modified_files)
         conv_context_file = marker_dir / f'{invocation_id}-conversation.context'
         conv_context_file.write_text(conv_context)
@@ -422,7 +496,132 @@ def main():
             NOTIFICATION_FILE=str(conv_notification_file),
             PROJECT_DIR=project_dir,
         )
-        spawn_claude_agent(conv_prompt, conv_log_file, project_dir)
+        spawn_claude_agent(conv_prompt, conv_log_file, project_dir, model=settings['promptModel'])
+
+    # Slow (~10s): check for stale rules last — if the hook timeout kills us
+    # here, the conversation agent and marker are already handled
+    if settings['ruleMaintenance']:
+        stale_rules = get_stale_rules()
+
+        if len(stale_rules) > 0:
+            stale_context = build_stale_rules_context(stale_rules)
+            stale_context_file = marker_dir / f'{invocation_id}-stale.context'
+            stale_context_file.write_text(stale_context)
+
+            stale_log_file = marker_dir / f'{invocation_id}-stale.log'
+            stale_notification_file = marker_dir / 'rule-notification-stale.md'
+            stale_prompt = load_prompt_template(
+                'stale-rules-prompt.txt',
+                CONTEXT_FILE=str(stale_context_file),
+                NOTIFICATION_FILE=str(stale_notification_file),
+                PROJECT_DIR=project_dir,
+            )
+            spawn_claude_agent(stale_prompt, stale_log_file, project_dir, model=settings['promptModel'])
+
+
+def handle_user_prompt_submit(hook_input):
+    """
+    Handle the UserPromptSubmit hook event.
+    Detects whether the previous turn was interrupted by checking if the Stop hook's
+    marker file is stale (transcript has lines beyond the marker). If so, spawns a
+    rule-reflection agent focused on the interruption.
+    """
+    settings = load_memory_settings()
+
+    # Interruption detection is part of conversation reflection
+    if not settings['conversationReflection']:
+        return
+
+    session_id = hook_input.get('session_id', '')
+    transcript_path = hook_input.get('transcript_path', '')
+    follow_up_prompt = hook_input.get('prompt', '')
+
+    if not session_id or not transcript_path:
+        return
+
+    marker_dir = Path('/tmp/claude-rule-markers')
+    marker_dir.mkdir(exist_ok=True)
+    marker_file = marker_dir / f'{session_id}.marker'
+
+    last_line, was_stop = read_marker(marker_file)
+
+    # If the Stop hook already ran for the previous turn, this is a normal
+    # completion — not an interruption. The Stop hook tags the marker with
+    # 'stop' when it writes it.
+    if was_stop:
+        return
+
+    # Count current transcript lines
+    try:
+        with open(transcript_path, 'r') as f:
+            current_line_count = sum(1 for _ in f)
+    except IOError:
+        return
+
+    # Quick exit: if nothing new since the marker, definitely no interruption
+    if current_line_count <= last_line:
+        return
+
+    # Verify Claude actually started responding in the unprocessed lines.
+    # Guards against false positives on first prompt (no assistant yet) or
+    # if the user hit Escape before Claude produced any output.
+    if not has_assistant_messages(transcript_path, last_line):
+        return
+
+    # Interruption detected! Build context and spawn agent.
+    _, conversation_snippets, modified_files, _ = get_conversation_context(
+        transcript_path, last_line
+    )
+
+    if not conversation_snippets:
+        return
+
+    # Update marker so we don't re-process these lines
+    write_marker(marker_file, current_line_count, 'submit')
+
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+
+    invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
+    invocation_id = f'{session_id}-{invocation_ts}'
+
+    interruption_context = build_interruption_context(
+        conversation_snippets, follow_up_prompt, modified_files
+    )
+    context_file = marker_dir / f'{invocation_id}-interruption.context'
+    context_file.write_text(interruption_context)
+
+    log_file = marker_dir / f'{invocation_id}-interruption.log'
+    notification_file = marker_dir / 'rule-notification-interruption.md'
+    prompt = load_prompt_template(
+        'interruption-prompt.txt',
+        CONTEXT_FILE=str(context_file),
+        NOTIFICATION_FILE=str(notification_file),
+        PROJECT_DIR=project_dir,
+    )
+    spawn_claude_agent(prompt, log_file, project_dir, model=settings['promptModel'])
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+
+    stop_hook_active = hook_input.get('stop_hook_active', False)
+
+    # Prevent infinite loops — stop_hook_active covers same-process recursion,
+    # env var covers spawned subagent sessions triggering the hook on exit
+    if stop_hook_active or os.environ.get('CODEYAM_RULE_AGENT'):
+        return
+
+    # Detect event type: UserPromptSubmit has a 'prompt' field, Stop does not
+    is_user_prompt = 'prompt' in hook_input
+    if is_user_prompt:
+        handle_user_prompt_submit(hook_input)
+    else:
+        handle_stop(hook_input)
+
 
 if __name__ == '__main__':
     main()