timer.1: document how to run hooks selectivelyHEADmain

Hooks are all-or-nothing per user: a file is installed or it is not, and
there is no per-run flag. That the gate belongs inside the hook, and
what it has to gate on, was only discoverable by reading the source.

A hook inherits the environment timer was run with and is handed the -c
comment as $3, so three gates are available: an environment variable for
explicit opt-in, a +tag in the comment (free if you already pass -c, and
still visible to timer --stats), or the session itself via $1 and $2 --
countdowns over ten minutes, say -- which needs nothing remembered.

Also records the asymmetry that is easy to get wrong: gate on_start
only. A hook that undoes something must run unconditionally in on_done
and on_quit, or a session ending without the gate set leaves
notifications paused or music stopped. Restore paths are harmless when
there was nothing to restore.

The shipped on_start now points at the new section, so the trick is
visible from the file someone is already editing.

Claude-Session: https://claude.ai/code/session_01APLBs8RB1FcUaC4viVkzbP

0 files changed, 0 insertions, 0 deletions