#372 pip uninstall doberman-core strands hook entries, causing 'doberman: command not found' on every tool call

[Anonymous]

Originally created by: QY-25123

Problem

doberman setup / doberman install-hooks wires Claude Code's settings.json (project
.claude/settings.json and/or global ~/.claude/settings.json) with PreToolUse,
PostToolUse, and SessionStart hooks that shell out directly to the doberman binary, e.g.:

{ "type": "command", "command": "doberman hook pre" }

pip uninstall doberman-core removes the binary from PATH but has no mechanism to also strip
those hook entries — pip has no supported post-uninstall hook for arbitrary cleanup. The result:
every subsequent tool call in Claude Code tries to run doberman hook pre/post/
session-summary, the shell can't find it, and Claude Code reports command not found on
every single tool call, indefinitely, until the stale entries are removed by hand.

The documented fix (doberman uninstall-hooks) only works if you remember to run it before
uninstalling the package — once the binary is gone, so is the only command that can clean up
after it, and nothing warns the user this order matters.

Repro

1. pip install doberman-core
2. doberman setup (or doberman install-hooks)
3. pip uninstall doberman-core (without first running doberman uninstall-hooks)
4. Any subsequent Claude Code tool call fails with doberman: command not found — permanently,
   since the hook entries are still in settings.json.

Proposal

• Docs (minimal fix): call out prominently in README.md and docs/SETUP.md that
  doberman uninstall-hooks must be run before pip uninstall doberman-core, since there is
  no way to automate cleanup after the package is gone.
• CLI (self-healing fix): have doberman install-hooks/doberman setup detect and offer to
  clean up orphaned Doberman hook entries left behind by a prior broken uninstall (e.g. entries
  whose command matches the doberman hook */doberman session-summary pattern but resolve to
  nothing on PATH), so re-installing repairs the settings file automatically instead of
  requiring manual editing.
• Optionally, doberman doctor could detect this state (hook entries present, binary healthy)
  and flag drift proactively, though that doesn't help once the binary itself is gone — the real
  gap is purely in ordering/cleanup on uninstall.

Related to [#250] (which is about gating a new doberman uninstall command behind auth) but
distinct: this is about the existing, undocumented ordering requirement between
doberman uninstall-hooks and pip uninstall, which currently has no guardrail and no clear
warning.

Security considerations

• Any self-healing cleanup in install-hooks must only ever remove Doberman's own previously
  written entries (already the existing behavior of uninstall-hooks) — never touch other tools'
  hooks, per the existing "leaves your other hooks intact" guarantee.
• This is a UX/reliability bug, not a security weakening: closing this gap does not loosen any
  guardrail, so it doesn't need to go through the raise-only/policy-drift path.

Suggested tests

• install-hooks run against a settings.json containing stale/orphaned Doberman hook entries
  (simulating a prior uninstall-without-cleanup) repairs them without touching unrelated hooks.
• Doc lint/snapshot (or manual review) confirms the uninstall-ordering warning is present in
  README.md/docs/SETUP.md.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed

[Anonymous]

Originally posted by: fu351

Status after today's merges: the docs half shipped in [#373] and the gated doberman uninstall command shipped in [#375], both yours. Thanks again for a bug report that arrived with its own fix plan attached.

What stays open here is the third piece of your proposal, the self-healing path: install-hooks/setup detecting orphaned doberman hook * entries left by a broken uninstall and offering to clean them up, plus doctor flagging the state. Relabeling this issue to that remainder. It's well-shaped follow-up work, and nobody knows this surface better than you right now.