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

1 files changed, 6 insertions, 1 deletions

diff --git a/hooks/on_start b/hooks/on_start
index fa38f7c..95b9377 100755
--- a/hooks/on_start
+++ b/hooks/on_start
@@ -30,7 +30,12 @@ fi
 
 # --- focus mode ----------------------------------------------------------
 # Countdowns only: a stopwatch has no end, and silencing notifications
-# indefinitely is not what you want. If the process is killed with -9
+# indefinitely is not what you want. To run this ad-hoc rather than on
+# every countdown, gate it -- on an env var, on a +tag in $3, or on the
+# duration in $2. See "Running hooks selectively" in timer(1). Gate here
+# only, never in on_done/on_quit: those must always restore.
+#
+#     [ -n "$TTYM_FOCUS" ] || exit 0 If the process is killed with -9
 # nothing restores these; recover with `dunstctl set-paused false`.
 if [ "$mode" = countdown ]; then
 	command -v dunstctl  > /dev/null 2>&1 && dunstctl set-paused true