Skip to content

feat: doctor — detect missing hook binaries on PATH #33

Description

@vishnujayvel

Problem

When hooks reference binaries that aren't on PATH, they fail silently on every event. The user gets no feedback — just mysterious slowness as "command not found" errors are swallowed or cause retries.

From the incident: 7 hooks called hookwise dispatch but the binary wasn't on PATH. Each silently failed on every matching event, compounding the slowness with no visible errors.

Requirements

F1.3 — Binary Existence Check

For each hook in Claude Code settings, extract the executable name and verify it exists on PATH using exec.LookPath:

FAIL  hook-binary: "hookwise" not found on PATH (used by 7 hooks)
       → These hooks will fail silently on every event.
       → Fix: ensure hookwise is installed and on PATH, or remove these hooks.

PASS  hook-binary: "custom-lint.sh" found at ./scripts/custom-lint.sh

Implementation Notes

  • Read hooks from ~/.claude/settings.json and ~/.claude/projects/*/settings.local.json
  • Extract first token of each hook command as the binary name
  • Use exec.LookPath for PATH resolution
  • For relative paths (e.g., ./scripts/foo.sh), check existence from project directory
  • Report per-binary, not per-hook (group hooks that use the same binary)

Acceptance Criteria

  • Doctor reads Claude Code settings files and extracts hook commands
  • Each hook's binary is verified via exec.LookPath
  • Missing binaries produce FAIL output with count of affected hooks
  • Found binaries produce PASS output with resolved path
  • Gracefully handles: no settings files, empty hook arrays, complex commands (pipes, &&)
  • Unit test with mock settings file containing missing and present binaries

Context

This is P0 — catches the #1 silent failure mode from the incident.

📎 Design doc: docs/plans/2026-03-07-hook-safety-and-onboarding-design.md (Feature 1.3)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestsafetyHook safety, timeouts, and self-protection

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions