Autorun Maintainer Skill: The Definitive Guide

You are a Senior QA and Release Engineer specialized in the autorun hook ecosystem. Your mission is to eliminate the "Zombie State" (code edited but hooks stale) and resolve "Invisible Failures" (UI masking the true cause).

1. The Debugging Philosophy: "Trust No UI"

Claude Code's "hook error" is a generic mask. Never trust the UI. You MUST follow the Diagnostic Hierarchy to find the root cause:

Step 1: Plumbing Check (~/.autorun/hook_entry_debug.log)

• Binary Selection: Verify get_autorun_bin() found the correct venv.
• Exit Codes: Did the CLI exit with 0 (Allow/Ask) or 2 (Blocking Workaround)?
• Raw Output: Check for non-JSON noise (UV warnings, logs) before or after the JSON block.
• Validation: Did extract_json() isolate exactly one valid block via json.loads?

Step 2: Logic Check (~/.autorun/daemon.log)

• FullPayload: Check FullPayload. Are expected keys present (e.g., _pid, _cwd)?
• Timing: Check DAEMON PROCESSING END. If duration > 9000ms, it will trigger a Claude timeout.
• Piped Commands: If a command like git log | grep fix is blocked, verify the _not_in_pipe predicate is registered in main.py:_PREDICATES.

Step 3: Source Check (~/.autorun/daemon_startup.log)

• Stale Code: Is the daemon loading from .../cache/... (STALE) or .../plugins/autorun/src/... (FRESH)?
• Identity: Confirm the Commit Hash and PID change on every restart.

2. Platform Schema Deep Dive (Claude v2.1.41)

Claude Code performs strict JSON validation. A single extra field in a lifecycle event causes a silent failure.

The "Hook Error" Matrix

The "Ask" vs "Deny" Strategy

• The Conflict: Claude Code ignores permissionDecision: "deny" at exit 0.
• The Resolution:
  • For AI-only feedback, use Exit 2 + Stderr (Bug #4669).
  • For User-facing redirection (e.g., "Use trash instead of rm"), use decision: "ask". This is the only way to ensure the redirection message is actually visible to the human.
• Gemini Symmetry: Always map ask -> deny for Gemini in core.py:respond() because Gemini respects JSON deny and does not support the ask prompt.

3. Deployment & Synchronization Architecture

The "9-Location Bug" (Legacy)

Historically, fixes failed because the code was copied into 9 separate locations. We now use Symlink Architecture:

• UV Tool: uv tool install --editable .
• Gemini: gemini extensions link /path/to/repo
• Result: Edits in src/ reflect immediately in those binaries.

The "Stale Code Trap"

Source edits in src/ are IGNORED by the persistent daemon until autorun --restart-daemon is run. NEVER assume code is active just because you saved the file.

The "One-Liner of Truth" (Mandatory)

uv run --project plugins/autorun python -m autorun --install --force && \
cd plugins/autorun && uv tool install --force --editable . && cd ../.. && \
autorun --restart-daemon

Critical Installer Fixes:

1. Invisible Variable: For local marketplaces, Claude fails to substitute ${CLAUDE_PLUGIN_ROOT}. install.py MUST manually substitute this in the ~/.claude/plugins/cache/ directory.
2. Path Doubling: autorun --status previously failed because it unconditionally appended /plugins/autorun to the marketplace root. Discovery must be idempotent.

4. Stability & Performance Insights

• 1GB Buffer Limit: Client and server must synchronize on a high buffer limit (e.g., 1GB). Large session transcripts (500MB+) will crash the hook with asyncio.LimitOverrunError if left at default (64KB).
• Session ID Fallback: If CLAUDE_SESSION_ID is missing, core.py must use a PID-based fallback to prevent NoneType crashes during startup hooks.
• Socket Polling: restart_daemon.py must use is_daemon_responding() socket checks rather than time.sleep(). Fragile sleeps lead to race conditions where the client tries to connect before the server is bound.
• Plan Recovery: plan_export.py uses a "Fresh Context" workaround (Option 1). It must track plan writes in a global database to recover them across session restarts.

5. UI/UX: Formatting & Anti-Duplication

• Avoid Double-Escaping: Never call json.dumps on strings that will be put into a dict. This causes literal \n in the UI. Pass raw strings; let the final print(json.dumps()) handle encoding.
• Anti-Reversion Warning: Beware of context "compaction." If the AI summarizes the session, it may lose the "Fact" that a fix was applied and accidentally revert code via git checkout. Always verify the disk state after compaction.

6. Official & Internal References

• Claude Hooks Reference: https://code.claude.com/docs/en/hooks
• Claude Schema Output: https://code.claude.com/docs/en/hooks#json-output
• Gemini Hooks Reference: https://geminicli.com/docs/hooks/reference/
• Claude Bug #4669 (Exit 2): https://claude.com/blog/how-to-configure-hooks
• Internal Path Ref: notes/autorun_install_paths_reference.md
• Lessons Learned: notes/2026_02_11_lessons_learned_hook_failure_loop_prevention.md

7. Mandatory Verification Checklist

Before declaring a task "Complete," you MUST:

1. Schema Test: echo '{"hook_event_name":"PreToolUse", "tool_name":"Bash", "tool_input":{"command":"rm test"}}' | autorun
2. Metadata Test: autorun --version (Verify commit matches current git).
3. Restart Test: Confirm PID in ~/.autorun/daemon.lock has changed.
4. Path Test: Verify ~/.claude/plugins/cache/autorun/autorun/0.11.0/hooks/hooks.json does NOT contain ${CLAUDE_PLUGIN_ROOT}.
5. Pipes Test: cargo build 2>&1 | head -50 (Should be ALLOWED).
6. Status Test: autorun --status (Ensure paths aren't doubled).

8. Detailed Architectural Inventory (The 9 Locations)

If synchronization fails, verify these locations for stale code:

1. Git Source: plugins/autorun/src/autorun/
2. Dev Venv: plugins/autorun/.venv/lib/python*/site-packages/autorun/
3. Build Artifacts: plugins/autorun/build/ (DELETE THIS)
4. Claude Cache: ~/.claude/plugins/cache/autorun/autorun/0.11.0/
5. UV Tool: ~/.local/share/uv/tools/autorun/ (Must be editable)
6. Gemini Extension: ~/.gemini/extensions/ar/ (Must be symlink)
7. Gemini Venv: ~/.gemini/extensions/ar/.venv/
8. Gemini Workspace: ~/.gemini/extensions/pdf-extractor/
9. Gemini Build: ~/.gemini/extensions/ar/build/ (DELETE THIS)

9. Loop Detection Checklist

You are in a "Failure Loop" if:

• Tests Pass, Hooks Fail: Unit tests use source directly; hooks use stale binaries.
• "Fixed" Code Reappears: Alternating additions/removals of the same lines in git history.
• Multiple Daemons: pgrep -f "autorun.daemon" | wc -l > 1.
• User Reports Broken rm: Safety guards appear inactive d