Skip to content

Commit 5005d50

Browse files
committed
docs(tools[hook]): restore 'Why no set_hook?' design rationale
Hoist the page-level intro the mechanical split dropped. Original prose lives at 970b000:docs/tools/hooks.md:9-22; the per-tool pages inherit tool-scoped Use/Avoid blocks from autodoc but cannot carry area-level design rationale explaining WHY the surface is read-only. Content restored explains: - tmux servers outlive the MCP process. - FastMCP lifespan teardown runs only on graceful SIGTERM/SIGINT; kill -9, OOM-kill, and C-extension-fault crashes bypass it. - Three candidate future paths (tmux-side client-detached meta-hook, LIBTMUX_SAFETY=destructive gating, one-shot run_hook) are explicitly out of scope until one is implemented.
1 parent 5d65d88 commit 5005d50

1 file changed

Lines changed: 9 additions & 1 deletion

File tree

docs/tools/hook/index.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
# Hook tools
22

3-
Hook introspection — enumerate and inspect tmux hook bindings at each scope.
3+
tmux hooks let you attach commands to lifecycle events — `pane-exited`, `session-renamed`, `command-error`, and so on. libtmux-mcp exposes **read-only** hook introspection so agents can audit what hooks the human user has configured before running automation that might trigger them.
4+
5+
## Why no `set_hook`?
6+
7+
Write-hooks are deliberately not exposed. tmux servers outlive the MCP process, and FastMCP's `lifespan` teardown runs only on graceful SIGTERM/SIGINT — it's bypassed on `kill -9`, OOM-kill, and C-extension-fault crashes. Any cleanup registry in Python could be silently bypassed, leaking agent-installed shell hooks into the user's persistent tmux server where they would fire forever. Three plausible future paths exist (a tmux-side `client-detached` meta-hook for self-cleanup, requiring `LIBTMUX_SAFETY=destructive`, or exposing one-shot `run_hook` only); none is in scope.
8+
9+
Until one of those paths is implemented, the surface here is visibility only.
10+
11+
## Inspect
412

513
::::{grid} 1 2 2 3
614
:gutter: 2 2 3 3

0 commit comments

Comments
 (0)