Skip to content

Make the Stop hook impossible to regret installing #11

Description

@amrit110

backcheck install puts a Stop hook in the critical path of every Claude Code session. That is
where the tool earns its keep, and also where a bad decision costs the most: a hook that blocks
on honest work, or blocks twice in a row, is worse than no hook at all.

Current behaviour: on finding unsupported claims it returns decision: "block" with the reasons,
unless stop_hook_active is set (which would risk a loop). Panics are caught, a missing
transcript is tolerated, and any failure degrades to "say nothing and let the turn finish".

Ways it could be better:

  • Configurable thresholds — a .backcheck.toml choosing what blocks vs. what only
    warns. Some teams will want contradicted to block and qualified to stay quiet.
  • Per-claim suppression — a way to say "this project has no test suite, stop telling me"
    without uninstalling entirely
  • A hard time budget — the hook should abandon analysis rather than ever delay a turn.
    A very large transcript on a slow disk is the case to worry about.
  • backcheck doctor — confirm the hook is installed correctly, the binary is on PATH,
    and show what it would have said about the last session
  • Statusline integration — a compact verdict in the Claude Code statusline instead of a
    block, for people who want the signal without the interruption
  • SessionEnd as an alternative to Stop, for reporting without ever blocking

Data that would help

If you install the hook and it blocks on something that was actually fine, that is a bug worth
reporting — see #6. Real examples of unnecessary blocks are the fastest way to
tune the thresholds, and they will shape whatever configuration format lands here.

Rule that must hold

Whatever changes: never break a session. Any malformed input, missing file, timeout, or
internal error must end with the turn completing normally. That property is worth more than any
feature on this list.

Metadata

Metadata

Assignees

No one assigned

    Labels

    accuracyVerdict correctnessenhancementNew feature or requesthelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions