From 07ba85de6a7af0805001ea48088157c961f8da75 Mon Sep 17 00:00:00 2001 From: Julian Lechner Date: Wed, 16 Sep 2026 19:18:26 +0200 Subject: [PATCH] docs(hooks): distinguish registered hooks from optional utilities --- docs/hooks.md | 18 +++++++++++++++--- shared/hooks/README.md | 6 ++++-- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/hooks.md b/docs/hooks.md index 0166f26..cdd6423 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -1,7 +1,19 @@ # Hooks -Deterministic safety and validation hooks live in `shared/hooks/scripts/`. The flashbang entry points live directly in `shared/hooks/`. The command safety hook rejects obvious destructive commands outside the current development workspace. The session validation hook checks repository-local generated inputs. The post-change hook is an optional verification entry point. +Hook scripts and optional utilities live in `shared/hooks/scripts/`. The flashbang entry points live directly in `shared/hooks/`. Shipping a script does not automatically register it as a hook. -The build includes the hooks and their client-specific registration in each payload. Installation places them beside the generated client files. The scripts do not grant permissions, bypass approvals, or replace client permission systems. +The adapters register these events: -The PowerShell and Bash hook variants are registered only for the Codex and Claude `Stop` events. They run after the main agent finishes responding, not during tool calls, thinking, permission requests, or notifications. The default flash lasts about 500 milliseconds. The Windows command deliberately omits `-WindowStyle Hidden`, which can hide or minimize the shared terminal. The PowerShell hook creates a low-opacity click-through overlay without activating another window. The Bash hook creates the equivalent temporary overlay through Python's standard `tkinter` module, uses `xrandr` for multi-monitor bounds when available, and does not reactivate the terminal. It falls back to `notify-send` in headless or minimal environments. Hooks are intentionally not executed during build or doctor. +| Client | Event | Action | +| --- | --- | --- | +| Codex and Claude | `Stop` | Run the finish notification (`flashbang`). | +| Claude | `PreCompact` | Append an event and UTC timestamp to `.ai-session/telemetry.jsonl` under the installed configuration root. | +| Claude | `SessionStart` | Print a short pointer if `.ai-session/state.json` exists under that root. | + +The session-state hooks do not create a task summary or restore conversation state. Their paths are relative to the installed configuration root, not the current project. The scripts do not grant permissions, bypass approvals, or replace client permission systems. + +The flashbang runs on `Stop`, after the main agent finishes responding. The default flash lasts about 500 milliseconds. The Windows command omits `-WindowStyle Hidden`, which can hide or minimize the shared terminal. The PowerShell hook creates a low-opacity click-through overlay without activating another window. The Bash hook uses Python's `tkinter`, uses `xrandr` for multi-monitor bounds when available, and falls back to `notify-send` when the overlay is unavailable. + +`Validate-CommandSafety`/`validate-command-safety.sh` and `Invoke-PostChangeVerification`/`invoke-post-change-verification.sh` are unregistered utilities. The former checks command text for selected dangerous patterns and outside-workspace paths; it is not a complete security boundary. The latter explicitly runs the repository build when invoked; it is not an automatic requirement after each change. + +`Test-SessionConfig`/`test-session-config.sh` checks required repository inputs and is called by the build. Build and doctor do not execute the registered notification or session-state hooks. Claude's status line is a separate `statusLine` command, not a hook event. diff --git a/shared/hooks/README.md b/shared/hooks/README.md index 9babcd9..0e4699d 100644 --- a/shared/hooks/README.md +++ b/shared/hooks/README.md @@ -1,5 +1,7 @@ # Hooks -Hooks are conservative entry points shared by clients. They validate obvious command hazards, check repository-local configuration inputs, and provide an optional post-change verification command. They do not bypass client permission prompts or grant access. +This directory contains registered hooks and optional utilities. They do not bypass client permission prompts or grant access. -Only the `Stop` hook (`flashbang`) is registered in the generated client configuration. `Validate-CommandSafety`/`validate-command-safety.sh` and `Invoke-PostChangeVerification`/`invoke-post-change-verification.sh` are utility scripts, not active hooks; nothing in this repository invokes them automatically. Wire one up as a client-native `PreToolUse`/equivalent hook yourself if you want it enforced, and do not assume it runs otherwise. +Both clients register `Stop` (`flashbang`) for finish notifications. Claude also registers `PreCompact` (`Record-Compact`/`record-compact.sh`) and `SessionStart` (`Show-SessionStatePointer`/`show-session-state-pointer.sh`). These use `.ai-session/` under the installed configuration root: the first records a compaction timestamp, and the second points to an existing `state.json`. They do not create a task summary. + +`Validate-CommandSafety`/`validate-command-safety.sh` and `Invoke-PostChangeVerification`/`invoke-post-change-verification.sh` are not registered or invoked automatically. The safety utility checks selected command-text patterns; the verification utility runs the repository build only when explicitly invoked. `Test-SessionConfig`/`test-session-config.sh` checks repository inputs during a build.