@ahmed-g-gad/apothem 0.1.1

package/src/apothem/hooks/hooks.json

@@ -0,0 +1,318 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" SessionStart",
+            "timeout": 30,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" SessionStart",
+            "timeout": 30,
+            "shell": "powershell"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-header-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-header-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-dependency-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-dependency-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-eval-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-eval-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-edit.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-edit.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-edit-header-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-edit-header-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-dependency-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-dependency-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-eval-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-eval-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          }
+        ]
+      },
+      {
+        "matcher": "NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-notebookedit.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-notebookedit.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-write-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-bash.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-bash.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-bash-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-bash-plan-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-eval-guard.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-eval-guard.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-askuserquestion-recommended.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/pretooluse-askuserquestion-recommended.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PostToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/posttooluse-proactive-compaction.md\"",
+            "timeout": 10,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PostToolUse \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/posttooluse-proactive-compaction.md\"",
+            "timeout": 10,
+            "shell": "powershell"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PreCompact \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/precompact.md\"",
+            "timeout": 30,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PreCompact \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/precompact.md\"",
+            "timeout": 30,
+            "shell": "powershell"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" PostCompact \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/postcompact.md\"",
+            "timeout": 30,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" PostCompact \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/postcompact.md\"",
+            "timeout": 30,
+            "shell": "powershell"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.sh\" Stop \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/stop.md\"",
+            "timeout": 60,
+            "shell": "bash"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/lib/bootstrap.ps1\" Stop \"${CLAUDE_PLUGIN_ROOT}/src/apothem/hooks/messages/stop.md\"",
+            "timeout": 60,
+            "shell": "powershell"
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/apothem/hooks/lib/README.md

@@ -0,0 +1,39 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# hooks/lib
+
+> **Role.** Dispatcher support — the shell stubs that locate an interpreter and
+> hand off to the dispatcher, plus the shared Python helpers the hook scripts
+> import.
+
+The bootstrap stubs are the documented shell entry path; the Claude Code
+`settings.json` hook entries instead invoke an install-resolved absolute
+interpreter on `../dispatch.py` directly (the `${PYTHON_BIN}` placeholder is
+substituted at install time), so the bootstrap stubs are not on that harness's
+`settings.json` critical path.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `bootstrap.sh` / `bootstrap.ps1` | Shell bootstrap stubs — resolve the project root, source the interpreter locator, and `exec` the dispatcher. The documented shell entry path. |
+| `find-python.sh` / `find-python.ps1` | Python interpreter locators — find a real interpreter on PATH (rejecting zero-byte Store launcher shims, enforcing the version floor). |
+| `find-pwsh.sh` / `find-pwsh.ps1` | PowerShell interpreter locators. |
+| `events.py` | Single source of truth for the supported hook-event vocabulary, imported by the dispatcher and handlers. |
+| `log.py` | Shared logger factory for the hook scripts. |
+| `resolve_root.py` | Project-root resolution for the apothem ecosystem. |
+| `__init__.py` | Package marker. |
+
+## Operating in this folder
+
+- **Fail-open on the critical path.** The stubs use `set -u` (not `-euo pipefail`) and an `ERR` trap that emits a JSON diagnostic envelope and exits 0, so a missing interpreter or dispatcher never stalls the harness. Preserve every explicit diagnostic-envelope branch; `-e` would short-circuit them.
+- **Stubs are paired across `.sh` and `.ps1`.** A change to one shell family's stub is mirrored in its counterpart in the same change so behavior does not diverge by platform.
+- **Per-platform startup budgets bound the stubs:** the POSIX-bash stub carries the tightest budget; the PowerShell stub and the Windows Git-Bash/mingw64 path carry a wider budget because their interpreter startup dominates; the interpreter locator sits inside the stub budget. Keep stub work minimal — resolve, locate, `exec`; do not add per-invocation overhead.
+- **The event vocabulary lives in `events.py`** and is imported, never duplicated, by the dispatcher and handlers.
+- Shell files open with `#!/usr/bin/env bash` then the hash-form single-line SPDX license header; Python files carry the same hash-form header.
+- Validate shell changes with `shellcheck hooks/lib/*.sh` and `Invoke-ScriptAnalyzer` over the `.ps1` stubs; validate Python helpers with `python -m ruff check`, `python -m mypy`, and `python -m pytest`. Surface any unresolved decision as `TODO(clarify): ...`.
+
+## Related
+
+- [`../`](../) — the hook runtime (`dispatch.py`, handlers, `messages/`) these stubs and helpers support.
+- [`../../benchmarks/bench_hooks.py`](../../benchmarks/bench_hooks.py) — the per-event runtime benchmark whose budget the stub startup sits inside.

package/src/apothem/hooks/lib/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared helpers consumed by the hook dispatcher and per-event emitters.
+
+Modules:
+
+* ``events`` — canonical hook-event taxonomy plus per-event metadata.
+* ``log`` — structured-logging surface used across the hook pipeline.
+* ``resolve_root`` — ecosystem-root resolution from the dispatcher's
+  invocation context (``CLAUDE_PROJECT_DIR`` / ``LLM_PROJECT_DIR`` /
+  fallback heuristics).
+
+The cross-platform shell stubs (``bootstrap.sh``, ``bootstrap.ps1``,
+``find-python.sh``, ``find-python.ps1``, ``find-pwsh.sh``,
+``find-pwsh.ps1``) live in this directory as data files; they are
+invoked by the harness's ``settings.json`` ``command:`` field at
+hook-fire time, not imported as Python modules.
+"""

package/src/apothem/hooks/lib/bootstrap.ps1

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: MIT
+
+# Purpose: PowerShell bootstrap stub for apothem hook events. Resolves
+# the project root, locates a real CPython >= 3.10 via find-python.ps1,
+# then invokes hooks/dispatch.py with the event name (and optional
+# context-file relative to project root).
+# Contract: stdout passthrough; exit 0 always (fail-open) so hook failures
+# never stall the host harness; missing interpreter or dispatcher emits a JSON
+# diagnostic envelope on stdout.
+# Sibling files in hooks/lib/: bootstrap.sh (POSIX counterpart),
+# find-python.ps1 (interpreter locator this stub dot-sources),
+# find-python.sh (POSIX counterpart of the locator).
+#
+# Invocation contract (event name + optional context file are positional; the
+# event also binds via -HookEvent, with -Event retained as an alias):
+#   powershell -NoProfile -ExecutionPolicy Bypass -File `
+#     "<root>\hooks\lib\bootstrap.ps1" <event> [<context-file>]
+#
+# Root discovery order:
+#   1. $env:CLAUDE_PROJECT_DIR if it points at a directory containing hooks\.
+#   2. $env:LLM_PROJECT_DIR (vendor-neutral alias) if it points at a
+#      directory containing hooks\.
+#   3. Upward walk from $PWD looking for hooks\dispatch.py.
+#   4. The directory two levels above this script (i.e. $HOME\.claude when
+#      this lives at $HOME\.claude\hooks\lib\bootstrap.ps1).
+#   5. $HOME\.claude as final fallback (Claude Code harness root).
+
+[CmdletBinding()]
+param(
+    # Renamed away from the PowerShell automatic Event variable (populated
+    # inside event/job scriptblocks) for collision-safety, and to match the
+    # POSIX bootstrap.sh's neutral `event`. The -Event alias preserves the
+    # documented flag form; the canonical hooks.json invocation passes the
+    # event positionally, which binds here regardless of the parameter name.
+    [Parameter(Mandatory = $true)]
+    [Alias('Event')]
+    [string]$HookEvent,
+    [Parameter(Mandatory = $false)][string]$ContextFile
+)
+
+# Why 'Continue' (not 'Stop'): the dispatch contract is fail-open — any
+# blocking error must surface as a JSON envelope on stdout with exit 0 so
+# the host harness never stalls. 'Stop' would short-circuit the explicit
+# diagnostic-envelope branches below before they can render. The trap on
+# the next line catches truly unexpected exceptions and routes them
+# through the same envelope path.
+$ErrorActionPreference = 'Continue'
+
+function Write-DiagnosticEnvelope {
+    param([string]$Message)
+    $payload = @{ systemMessage = $Message } | ConvertTo-Json -Compress
+    Write-Output $payload
+}
+
+trap {
+    # The JSON envelope is the hook-runtime contract and goes to STDOUT
+    # (matching bootstrap.sh and this stub's stated stdout contract); stderr
+    # is reserved for the human-readable diagnostic line only. The script line
+    # number mirrors bootstrap.sh's `at line $LINENO` for canonical-pair
+    # diagnostic parity; the exception message is the platform-available detail.
+    $line = $_.InvocationInfo.ScriptLineNumber
+    $message = "hook bootstrap: unexpected error at line ${line}: $($_.Exception.Message)"
+    Write-DiagnosticEnvelope -Message $message
+    [Console]::Error.WriteLine($message)
+    exit 0
+}
+
+# --- Resolve project root ----------------------------------------------------
+$root = $env:CLAUDE_PROJECT_DIR
+if (-not $root -or -not (Test-Path -LiteralPath (Join-Path $root 'hooks'))) {
+    $root = $env:LLM_PROJECT_DIR
+}
+if (-not $root -or -not (Test-Path -LiteralPath (Join-Path $root 'hooks'))) {
+    $cursor = $PWD.Path
+    $root = $null
+    while ($cursor) {
+        if (Test-Path -LiteralPath (Join-Path $cursor 'hooks\dispatch.py')) {
+            $root = $cursor
+            break
+        }
+        $parent = Split-Path -Parent $cursor
+        if (-not $parent -or $parent -eq $cursor) { break }
+        $cursor = $parent
+    }
+}
+if (-not $root) {
+    $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+    $candidate = Resolve-Path (Join-Path $scriptDir '..\..') -ErrorAction SilentlyContinue
+    if ($candidate -and (Test-Path -LiteralPath (Join-Path $candidate.Path 'hooks\dispatch.py'))) {
+        $root = $candidate.Path
+    }
+}
+if (-not $root) {
+    $root = Join-Path $HOME '.claude'
+}
+
+# --- Locate Python via the locator stub --------------------------------------
+$locator = Join-Path $root 'hooks\lib\find-python.ps1'
+if (-not (Test-Path -LiteralPath $locator)) {
+    Write-DiagnosticEnvelope -Message ("hook {0} skipped: locator stub missing at {1}" -f $HookEvent, $locator)
+    exit 0
+}
+. $locator
+
+$py = $null
+try {
+    $py = Find-RealPython
+} catch {
+    Write-DiagnosticEnvelope -Message ("hook {0} skipped: locator raised {1}" -f $HookEvent, $_.Exception.Message)
+    exit 0
+}
+if (-not $py) {
+    Write-DiagnosticEnvelope -Message ("hook {0} skipped: no Python interpreter found" -f $HookEvent)
+    exit 0
+}
+
+$dispatch = Join-Path $root 'hooks\dispatch.py'
+if (-not (Test-Path -LiteralPath $dispatch)) {
+    Write-DiagnosticEnvelope -Message ("hook {0} skipped: dispatch missing at {1}" -f $HookEvent, $dispatch)
+    exit 0
+}
+
+# --- Hand off to dispatch.py -------------------------------------------------
+if ($ContextFile) {
+    & $py $dispatch --event-name $HookEvent --context-file $ContextFile
+} else {
+    & $py $dispatch --event-name $HookEvent
+}
+exit $LASTEXITCODE

package/src/apothem/hooks/lib/bootstrap.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+
+# Purpose: POSIX bootstrap stub for apothem hook events. Resolves the
+# project root, locates a real CPython >= 3.10 via find-python.sh, then
+# execs hooks/dispatch.py with the event name (and optional context-file
+# relative to project root).
+# Contract: stdin/stdout passthrough; exit 0 always (fail-open) so hook
+# failures never stall the host harness; missing interpreter or dispatcher
+# emits a JSON diagnostic envelope on stdout.
+# Sibling files in hooks/lib/: bootstrap.ps1 (PowerShell counterpart),
+# find-python.sh (interpreter locator this stub sources), find-python.ps1
+# (PowerShell counterpart of the locator).
+#
+# Root discovery order:
+#   1. $CLAUDE_PROJECT_DIR if it points at a directory containing hooks/.
+#   2. $LLM_PROJECT_DIR (vendor-neutral alias) if it points at a directory
+#      containing hooks/.
+#   3. Upward walk from $PWD looking for hooks/dispatch.py.
+#   4. The directory two levels above this script (i.e. $HOME/.claude when
+#      this lives at $HOME/.claude/hooks/lib/bootstrap.sh).
+#   5. $HOME/.claude as final fallback (Claude Code harness root).
+
+# Why `-u` only (not `-euo pipefail`): the dispatch contract is fail-open —
+# any blocking error must surface as a JSON envelope on stdout with exit 0
+# so the host harness never stalls. `-e` would short-circuit the explicit
+# diagnostic-envelope branches below; `pipefail` is unused since no
+# pipelines run in this script. `-u` catches typos in variable names,
+# which is the one failure mode worth aborting on.
+set -u
+
+# Trap unexpected errors: emit a JSON envelope and exit 0 so the hook
+# runtime sees a valid envelope rather than an unhandled non-zero exit.
+trap 'printf "{\"systemMessage\":\"hook bootstrap: unexpected error at line %s\"}\n" "${LINENO}"; exit 0' ERR
+
+event="${1:-}"
+context_file="${2:-}"
+
+if [ -z "$event" ]; then
+    printf '{"systemMessage":"hook bootstrap: missing event name"}\n'
+    exit 0
+fi
+
+# --- Resolve project root ----------------------------------------------------
+root="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$root" ] || [ ! -d "$root/hooks" ]; then
+    root="${LLM_PROJECT_DIR:-}"
+fi
+if [ -z "$root" ] || [ ! -d "$root/hooks" ]; then
+    cursor="$PWD"
+    root=""
+    while [ -n "$cursor" ]; do
+        if [ -f "$cursor/hooks/dispatch.py" ]; then
+            root="$cursor"
+            break
+        fi
+        parent="$(dirname "$cursor")"
+        [ "$parent" = "$cursor" ] && break
+        cursor="$parent"
+    done
+fi
+if [ -z "$root" ]; then
+    script_dir="$(cd "$(dirname "$0")" && pwd)"
+    candidate="$(cd "$script_dir/../.." && pwd)"
+    if [ -f "$candidate/hooks/dispatch.py" ]; then
+        root="$candidate"
+    fi
+fi
+[ -z "$root" ] && root="$HOME/.claude"
+
+# --- Locate Python via the locator stub --------------------------------------
+locator="$root/hooks/lib/find-python.sh"
+if [ ! -f "$locator" ]; then
+    printf '{"systemMessage":"hook %s skipped: locator stub missing at %s"}\n' \
+        "$event" "$locator"
+    exit 0
+fi
+# shellcheck source=find-python.sh disable=SC1091
+. "$locator"
+
+# Guard the command substitution so the ERR trap does NOT fire on the
+# expected no-interpreter path. `if ! winner=$(...)` consumes the locator's
+# non-zero exit as a tested condition rather than an uncaught error, so a
+# host with no real CPython sees the intended "no Python interpreter found"
+# envelope, not the trap's "unexpected error at line N" line.
+if ! py="$(find_real_python 2>/dev/null)" || [ -z "$py" ]; then
+    printf '{"systemMessage":"hook %s skipped: no Python interpreter found"}\n' "$event"
+    exit 0
+fi
+
+dispatch="$root/hooks/dispatch.py"
+if [ ! -f "$dispatch" ]; then
+    printf '{"systemMessage":"hook %s skipped: dispatch missing at %s"}\n' \
+        "$event" "$dispatch"
+    exit 0
+fi
+
+# --- Hand off to dispatch.py -------------------------------------------------
+if [ -n "$context_file" ]; then
+    exec "$py" "$dispatch" --event-name "$event" --context-file "$context_file"
+else
+    exec "$py" "$dispatch" --event-name "$event"
+fi

package/src/apothem/hooks/lib/events.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+
+"""Single source of truth for the supported hook-event vocabulary.
+
+Both ``hooks/dispatch.py`` and ``hooks/emit_hook_context.py`` import
+their event-vocabulary sets from this module. Future event additions
+land here only; both consumers re-derive at import time.
+
+Two sets are exposed:
+
+* ``SUPPORTED_EVENTS`` — the whitelist of every hook event the
+  dispatcher accepts. Adding an event here makes it routable; removing
+  it forces a ``ValueError`` on dispatch attempt. Events listed here
+  that are not yet wired in a harness settings file are accepted for
+  forward compatibility — the dispatcher routes them the moment a
+  settings entry materializes.
+
+* ``HOOK_SPECIFIC_OUTPUT_EVENTS`` — the subset of ``SUPPORTED_EVENTS``
+  whose envelope schema accepts the ``hookSpecificOutput`` shape.
+  Events outside this subset (currently ``PreCompact`` and
+  ``PostCompact``) fail strict schema validation on that shape and
+  must use the top-level ``systemMessage`` field instead.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+SUPPORTED_EVENTS: Final[frozenset[str]] = frozenset(
+    {
+        "SessionStart",
+        "PreCompact",
+        "PostCompact",
+        "Stop",
+        "PreToolUse",
+        "PostToolUse",
+        "UserPromptSubmit",
+        "Notification",
+    }
+)
+
+HOOK_SPECIFIC_OUTPUT_EVENTS: Final[frozenset[str]] = frozenset(
+    {
+        "SessionStart",
+        "Stop",
+        "PreToolUse",
+        "PostToolUse",
+        "UserPromptSubmit",
+        "Notification",
+    }
+)