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

2 files changed, 61 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
diff --git a/timer.1 b/timer.1
index e7850f9..1dc79ea 100644
--- a/timer.1
+++ b/timer.1
@@ -315,6 +315,61 @@ Hooks are executed with
 so a script needs a
 .B #!
 line like any other.
+.SS Running hooks selectively
+A hook is either installed or not; there is no per\-run flag. Ad\-hoc
+behaviour is arranged inside the hook instead, which sees two things it
+can decide on: it inherits the environment
+.B timer
+was run with, and it is handed the
+.B \-c
+comment as
+.BR $3 .
+.PP
+Gate on an environment variable, for an explicit opt\-in:
+.PP
+.RS
+.nf
+[ \-n "$TTYM_FOCUS" ] || exit 0
+.fi
+.RE
+.PP
+.RS
+.nf
+timer 25m                 # hook does nothing
+TTYM_FOCUS=1 timer 25m    # hook acts
+.fi
+.RE
+.PP
+Gate on a tag in the comment, which costs nothing extra if you already
+pass
+.B \-c
+and leaves the tag visible to
+.BR "timer \-\-stats" :
+.PP
+.RS
+.nf
+case $3 in *+focus*) ;; *) exit 0 ;; esac
+.fi
+.RE
+.PP
+Or gate on the session itself, so nothing has to be remembered \(em here,
+countdowns of ten minutes or more:
+.PP
+.RS
+.nf
+[ "$1" = countdown ] && [ "$2" \-ge 600 ] || exit 0
+.fi
+.RE
+.PP
+Put the gate on
+.B on_start
+only. A hook that undoes something \(em restoring notifications, resuming
+music \(em must run unconditionally in
+.B on_done
+and
+.BR on_quit ,
+or a session that ends without the gate being set leaves the change in
+place. Restore paths are harmless when there was nothing to restore.
 .SS Examples
 Three commented, working examples ship with the source and are installed
 to