jeo-code 0.12.21 → 0.12.23

package/CHANGELOG.md

@@ -9,6 +9,28 @@ The README mirrors the latest 5 entries — regenerate with `bun run changelog:s
 
 ## [Unreleased]
 
+## [0.12.23] - 2026-11-06
+
+### Added
+- **`pre-prompt` and `turn-end` hook events** - `pre-prompt` runs once per typed prompt before the model sees it (Claude `UserPromptSubmit`): stdout text, or JSON `hookSpecificOutput.additionalContext` / `additionalContext` / `context`, is appended to the prompt message as a `[pre-prompt hook context]` block; the prompt card, history title and turn-end payload keep the user's own words. `turn-end` runs once per finished turn (Claude `Stop`) with `prompt`, `response` (also `last_assistant_message` / `assistant_output`), `done`, `steps` and `model`. Both are advisory (non-zero exit, timeout or abort prints a notice, never blocks; default timeouts 10 s / 30 s), skipped for `$skill` runs and messenger-literal sessions, and an `agy/` model skips `pre-prompt` (the official CLI owns its prompt) but runs `turn-end`.
+- **User hook registry `~/.jeo/hooks.json`** - a hooks-only file (same shape as `.jeo/hooks.json`, follows `JEO_CONFIG_DIR`) for tools that install hooks, such as jeo-skills' OpenSpace prompt routing (`route-hooks.py install --host jeo`) and knowledge-pipeline ingesters, kept apart from `config.json` so credentials are never rewritten. It runs without `hooks.enabled: true`, ahead of configured hooks, and survives a project `.jeo/hooks.json` replacing the `config.json` list. Sandboxed sessions skip it. Entries with an unknown event, a missing `run` or a bad `timeoutMs` are dropped instead of failing the whole batch.
+- **Structured `pre-tool` decisions** - a `pre-tool` hook that exits 0 may print `{"hookSpecificOutput":{"permissionDecision":"deny"|"ask","permissionDecisionReason":"…"}}` (also `decision: "block"` or `continue: false`) to veto the call; `ask` counts as deny because jeo has no hook approval prompt. `additionalContext` is appended to that tool's result. Plain stdout stays ignored.
+- **Claude-protocol payload fields** - every host-session hook payload now carries `hook_event_name`, `session_id` and `cwd`, and tool events add `tool_name` / `tool_input`, beside the existing `event` / `tool` / `args`, so Claude Code and Codex hook scripts run unmodified. Sandboxed hooks keep the previous payload and never see the host `cwd` or session id.
+
+### Changed
+- **`hooks.enabled` is now an explicit kill switch** - `"hooks": { "enabled": false }` in `config.json` disables every hook, registry included. Left unset it still disables `config.json` and project hooks (a repo cannot enable its own hooks) but no longer silences the user registry. A project `.jeo/hooks.json` with `"enabled": false` opts that project out of everything.
+
+## [0.12.22] - 2026-11-04
+
+### Fixed
+- **`jeo update` never changes other packages in the shared bun global** - before running any installer it checks the shared bun global (`$BUN_INSTALL` or `~/.bun`, `install/global`): if its `package.json` lists dependencies other than `jeo-code` and `bun.lock` is missing or does not cover all of them, the update is refused with exit 1, no file is changed, and the uncovered dependencies are named (`--json`: `installed:false` and an `error` mentioning the lockfile). After the install it compares the installed version of every other top-level dependency with the pre-install state; any difference fails the update and prints `name old -> new` plus the exact `bun install -g name@old` commands (never run). A clean update prints `shared global unchanged: N packages (...)`. `--json` gains `externalChanges` and `preflight` only when a shared global with other packages was inspected.
+- **`--allow-unlocked-global`** - skips only the lockfile refusal; the postflight comparison still runs.
+- **The npm fallback no longer creates stale second copies** - `npm install -g` is a fallback only when the active `jeo` lies under npm's global root; for a bun-global or unknown install a failed update ends with manual commands instead.
+
+### Added
+- **`jeo doctor` shared install section** (human and `--json` `sharedInstall`, read-only, warnings only): `bun.lock` status (missing, incomplete with the uncovered dependencies, or ok), every `jeo` on PATH in PATH order with its version and a stale flag, leftovers (`package.json.*backup*` files and possible orphan packages), and the five largest packages plus the total size within a time and entry cap.
+- **`bun run verify:shared-global`** - replays both updaters against an isolated copy of the real global: `jeo update` leaves every other package untouched, `jeopi update` leaves `jeo-code` untouched, and losing `bun.lock` is refused without a single package-manager call.
+
 ## [0.12.21] - 2026-11-04
 
 ### Fixed
@@ -2724,7 +2746,9 @@ _Initial release._
 ### Added
 - Initial jeo-code agent and CLI.
 
-[Unreleased]: https://github.com/akillness/jeo-code/compare/v0.12.21...HEAD
+[Unreleased]: https://github.com/akillness/jeo-code/compare/v0.12.23...HEAD
+[0.12.23]: https://github.com/akillness/jeo-code/releases/tag/v0.12.23
+[0.12.22]: https://github.com/akillness/jeo-code/compare/v0.12.21...v0.12.22
 [0.12.21]: https://github.com/akillness/jeo-code/releases/tag/v0.12.21
 [0.12.20]: https://github.com/akillness/jeo-code/releases/tag/v0.12.20
 [0.12.19]: https://github.com/akillness/jeo-code/releases/tag/v0.12.19

package/README.ja.md

@@ -218,6 +218,19 @@ jeo ultragoal
 
 非ゼロ終了したフックの出力はモデルが読むツール結果に付加され(バッチ内で重複排除)、フックが赤のまま `done` を呼ぶとフック名付きでプッシュバックされます。
 
+### プロンプト・ターンフックとユーザーレジストリ
+
+ツールループのイベントに加えて、ターンごとに 1 回発火するイベントが 2 つあります:
+
+| イベント | タイミング | ペイロード(stdin JSON) | フック出力 |
+| -------- | ---------- | ---------------------- | ---------- |
+| `pre-prompt` | 入力したプロンプトをモデルが見る前 | `{event, hook_event_name: "UserPromptSubmit", session_id, cwd, prompt}` | stdout のテキスト、または JSON の `hookSpecificOutput.additionalContext` / `additionalContext` / `context` が `[pre-prompt hook context]` ブロックとしてプロンプトメッセージの末尾に付加されます(プロンプトカードと履歴タイトルにはユーザー自身の言葉だけが残ります) |
+| `turn-end` | 最終返信の直後 | `{event, hook_event_name: "Stop", session_id, cwd, prompt, response, last_assistant_message, done, steps, model}` | 無視 |
+
+どちらも助言(advisory)扱いです: 非ゼロ終了・タイムアウト・中断は通知を出すだけでプロンプトをブロックしません(既定タイムアウト 10 秒 / 30 秒)。`$skill` 実行とメッセンジャー literal セッションはスキップされ、`agy/` モデルでは公式 CLI がプロンプトを管理するため `pre-prompt` はスキップされ、`turn-end` は実行されます。`pre-tool` フックは exit 0 で `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"…"}}` を出力して拒否(`ask` は deny 扱い)したり、`additionalContext` を出力してそのツール結果に付加したりできます。通常の stdout は引き続き無視されます。すべてのペイロードに `hook_event_name`、`session_id`、`cwd`(ツールイベントは `tool_name`/`tool_input` も)が含まれるため、Claude Code / Codex のフックスクリプトをそのまま使えます — ホストセッションのみで、サンドボックスのフックは従来のペイロードを受け取ります。
+
+**ユーザーレジストリ.** `~/.jeo/hooks.json`(`.jeo/hooks.json` と同形式、`JEO_CONFIG_DIR` に従う)は、jeo-skills のプロンプトルーティングやナレッジパイプラインのようにフックを代わりに設置するツール向けのフック専用ファイルで、認証情報が書き換えられないよう `config.json` から分離されています。優先順位: `config.json` の `"hooks": { "enabled": false }` はすべてを無効にし、プロジェクト `.jeo/hooks.json` の `"enabled": false` はそのプロジェクトだけを除外し、それ以外は `hooks.enabled: true` なしでレジストリが設定済みフックより先に実行されます。プロジェクト自身の `hooks` リストは `config.json` のリストだけを置き換えレジストリは置き換えず、プロジェクト / `config.json` のフックは従来どおり `hooks.enabled: true` のときだけ実行されます。サンドボックスセッションはレジストリをスキップします。
+
 ## メモリフロー
 
 `jeo` は `.jeo/memory/` 配下に **ローカルファースト・蒸留されたプロジェクトメモリ** を保持します(リモートバックエンドなし、ネイティブ依存ゼロ)。過去のセッションは [OKF](docs/okf_mem/) コンセプトバンドルへ蒸留され、次のセッションは関連性の高い予算内のスライスだけをシステムプロンプトへ再注入します — 指示ではなく DATA として堅牢化されます。`JEO_NO_MEMORY=1` ですべて無効化。
@@ -447,10 +460,10 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.23]** (2026-11-06)
+- **[0.12.22]** (2026-11-04)
 - **[0.12.21]** (2026-11-04)
 - **[0.12.20]** (2026-11-04)
-- **[0.12.19]** (2026-11-04)
-- **[0.12.18]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -272,6 +272,19 @@ jeo ultragoal                                      # 5. 최종 증거 기반 종
 
 비정상 종료한 훅의 출력은 모델이 읽는 도구 결과에 첨부되고(배치 내 중복 제거), 훅이 빨간 채로 `done`을 부르면 훅 이름과 함께 푸시백됩니다.
 
+### 프롬프트·턴 훅과 사용자 레지스트리
+
+도구 루프 이벤트 외에 턴마다 한 번씩 발생하는 이벤트가 둘 더 있습니다:
+
+| 이벤트 | 시점 | 페이로드(stdin JSON) | 훅 출력 |
+| ------ | ---- | -------------------- | ------- |
+| `pre-prompt` | 입력한 프롬프트를 모델이 보기 전 | `{event, hook_event_name: "UserPromptSubmit", session_id, cwd, prompt}` | stdout 텍스트 또는 JSON `hookSpecificOutput.additionalContext` / `additionalContext` / `context`가 `[pre-prompt hook context]` 블록으로 프롬프트 메시지 뒤에 붙습니다(프롬프트 카드와 히스토리 제목에는 사용자가 쓴 말만 남음) |
+| `turn-end` | 최종 답변 직후 | `{event, hook_event_name: "Stop", session_id, cwd, prompt, response, last_assistant_message, done, steps, model}` | 무시 |
+
+둘 다 권고(advisory)용입니다: 비정상 종료·타임아웃·중단은 알림만 출력하고 프롬프트를 막지 않습니다(기본 타임아웃 10초 / 30초). `$skill` 실행과 메신저 literal 세션은 건너뛰며, `agy/` 모델은 공식 CLI가 프롬프트를 소유하므로 `pre-prompt`는 건너뛰고 `turn-end`는 실행됩니다. `pre-tool` 훅은 exit 0으로 `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"…"}}`를 출력해 거부(`ask`는 deny로 처리)하거나 `additionalContext`를 출력해 해당 도구 결과에 덧붙일 수 있으며, 일반 stdout은 계속 무시됩니다. 모든 페이로드에 `hook_event_name`, `session_id`, `cwd`(도구 이벤트는 `tool_name`/`tool_input` 추가)가 들어 있어 Claude Code / Codex 훅 스크립트를 수정 없이 쓸 수 있습니다 — 호스트 세션 한정이며 샌드박스 훅은 기존 페이로드를 받습니다.
+
+**사용자 레지스트리.** `~/.jeo/hooks.json`(`.jeo/hooks.json`과 같은 형식, `JEO_CONFIG_DIR`을 따름)은 jeo-skills의 프롬프트 라우팅·지식 파이프라인처럼 훅을 대신 설치하는 도구를 위한 훅 전용 파일이며, 자격 증명이 다시 쓰이지 않도록 `config.json`과 분리되어 있습니다. 우선순위: `config.json`의 `"hooks": { "enabled": false }`는 모든 훅을 끄고, 프로젝트 `.jeo/hooks.json`의 `"enabled": false`는 그 프로젝트만 제외하며, 그 외에는 `hooks.enabled: true` 없이도 레지스트리가 설정된 훅보다 먼저 실행됩니다. 프로젝트 자체 `hooks` 목록은 `config.json` 목록만 대체하고 레지스트리는 대체하지 않으며, 프로젝트 / `config.json` 훅은 여전히 `hooks.enabled: true`일 때만 실행됩니다. 샌드박스 세션은 레지스트리를 건너뜁니다.
+
 ## 메모리 흐름
 
 `jeo`는 `.jeo/memory/` 아래에 **로컬 우선·증류된 프로젝트 메모리**를 둡니다(원격 백엔드 없음, 네이티브 의존성 0). 지난 세션은 [OKF](docs/okf_mem/) 개념 번들로 증류되고, 다음 세션은 관련성 높은 예산 한도 내 일부만 시스템 프롬프트로 다시 주입합니다 — 지시가 아닌 DATA로 강화 처리됩니다. `JEO_NO_MEMORY=1`로 전체 비활성화.
@@ -502,10 +515,10 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.23]** (2026-11-06)
+- **[0.12.22]** (2026-11-04)
 - **[0.12.21]** (2026-11-04)
 - **[0.12.20]** (2026-11-04)
-- **[0.12.19]** (2026-11-04)
-- **[0.12.18]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -275,6 +275,19 @@ Enable hooks once globally (`"hooks": { "enabled": true }` in `~/.jeo/config.jso
 
 Non-zero hook output is appended to the tool result the model reads (deduped per batch); a still-red hook triggers a `done` pushback naming the hook.
 
+### Prompt and turn hooks, and the user registry
+
+Two more events fire once per turn, beside the tool-loop events:
+
+| Event | When | Payload (stdin JSON) | Hook output |
+| ----- | ---- | -------------------- | ----------- |
+| `pre-prompt` | before the model sees a typed prompt | `{event, hook_event_name: "UserPromptSubmit", session_id, cwd, prompt}` | stdout text, or JSON `hookSpecificOutput.additionalContext` / `additionalContext` / `context`, is appended to the prompt message as a `[pre-prompt hook context]` block (the prompt card and history title keep your own words) |
+| `turn-end` | after the final reply | `{event, hook_event_name: "Stop", session_id, cwd, prompt, response, last_assistant_message, done, steps, model}` | ignored |
+
+Both are advisory: a non-zero exit, timeout or abort prints a notice and never blocks the prompt (default timeouts 10 s / 30 s). `$skill` runs and messenger-literal sessions skip them; `pre-prompt` is skipped for an `agy/` model (the official CLI owns its prompt) while `turn-end` still runs. A `pre-tool` hook may also exit 0 and print `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"…"}}` to veto (`ask` counts as deny) or `additionalContext` to append to that tool's result; plain stdout stays ignored. Every payload also carries `hook_event_name`, `session_id` and `cwd` (tool events add `tool_name`/`tool_input`), so Claude Code / Codex hook scripts run unmodified — host sessions only; sandboxed hooks get the legacy payload.
+
+**User registry.** `~/.jeo/hooks.json` (same shape as `.jeo/hooks.json`; follows `JEO_CONFIG_DIR`) is a hooks-only file for tools that install hooks for you, such as jeo-skills' prompt routing and knowledge pipeline, kept apart from `config.json` so credentials are never rewritten. Precedence: `"hooks": { "enabled": false }` in `config.json` disables everything; a project `.jeo/hooks.json` with `"enabled": false` opts that project out; otherwise the registry runs, with no `hooks.enabled: true` needed, ahead of configured hooks. A project's own `hooks` list still replaces the `config.json` list, never the registry, and project / `config.json` hooks still run only with `hooks.enabled: true`. Sandboxed sessions skip the registry.
+
 ## Memory flow
 
 `jeo` keeps a **local-first, distilled project memory** under `.jeo/memory/` (no remote backend, zero native deps). Past sessions are distilled into an [OKF](docs/okf_mem/) concept bundle, and the next session injects only the relevant, budget-bounded slice back into the system prompt — hardened as DATA, never as instructions. Disable everything with `JEO_NO_MEMORY=1`.
@@ -491,10 +504,10 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.23]** (2026-11-06)
+- **[0.12.22]** (2026-11-04)
 - **[0.12.21]** (2026-11-04)
 - **[0.12.20]** (2026-11-04)
-- **[0.12.19]** (2026-11-04)
-- **[0.12.18]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -218,6 +218,19 @@ jeo ultragoal
 
 非零退出钩子的输出会附加到模型读取的工具结果中(批内去重)；钩子未通过就调用 `done` 会收到带钩子名称的回推。
 
+### 提示与回合钩子,以及用户注册表
+
+除工具循环事件外,每个回合还会触发两个事件:
+
+| 事件 | 时机 | 载荷(stdin JSON) | 钩子输出 |
+| ---- | ---- | ---------------- | -------- |
+| `pre-prompt` | 模型看到所输入提示之前 | `{event, hook_event_name: "UserPromptSubmit", session_id, cwd, prompt}` | stdout 文本,或 JSON 的 `hookSpecificOutput.additionalContext` / `additionalContext` / `context`,会以 `[pre-prompt hook context]` 块的形式追加到提示消息末尾(提示卡片和历史标题只保留你自己的话) |
+| `turn-end` | 最终回复之后 | `{event, hook_event_name: "Stop", session_id, cwd, prompt, response, last_assistant_message, done, steps, model}` | 忽略 |
+
+两者都是建议性的:非零退出、超时或中止只会打印通知,绝不阻止提示(默认超时 10 秒 / 30 秒)。`$skill` 运行和消息机器人 literal 会话会跳过它们;`agy/` 模型因官方 CLI 自行管理提示而跳过 `pre-prompt`,但仍运行 `turn-end`。`pre-tool` 钩子也可以 exit 0 并输出 `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"…"}}` 来否决(`ask` 视为 deny),或输出 `additionalContext` 追加到该工具的结果;普通 stdout 仍被忽略。所有载荷还带有 `hook_event_name`、`session_id` 和 `cwd`(工具事件另有 `tool_name`/`tool_input`),因此 Claude Code / Codex 的钩子脚本无需修改即可运行 —— 仅限主机会话;沙箱内的钩子收到旧版载荷。
+
+**用户注册表。** `~/.jeo/hooks.json`(与 `.jeo/hooks.json` 格式相同,遵循 `JEO_CONFIG_DIR`)是供代你安装钩子的工具(如 jeo-skills 的提示路由和知识管道)使用的仅含钩子的文件,与 `config.json` 分离,因此凭据不会被重写。优先级:`config.json` 中的 `"hooks": { "enabled": false }` 会禁用一切;项目 `.jeo/hooks.json` 中的 `"enabled": false` 仅让该项目退出;否则注册表无需 `hooks.enabled: true` 即可运行,并排在已配置钩子之前。项目自己的 `hooks` 列表仍然只替换 `config.json` 的列表,绝不替换注册表,且项目 / `config.json` 钩子仍然只在 `hooks.enabled: true` 时运行。沙箱会话会跳过注册表。
+
 ## 内存流程
 
 `jeo` 在 `.jeo/memory/` 下保存 **本地优先、蒸馏后的项目内存**(无远程后端,零原生依赖)。过往会话被蒸馏为 [OKF](docs/okf_mem/) 概念包,下一次会话仅把相关的、受预算约束的切片重新注入系统提示 —— 作为 DATA 而非指令加固。用 `JEO_NO_MEMORY=1` 完全禁用。
@@ -445,10 +458,10 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.23]** (2026-11-06)
+- **[0.12.22]** (2026-11-04)
 - **[0.12.21]** (2026-11-04)
 - **[0.12.20]** (2026-11-04)
-- **[0.12.19]** (2026-11-04)
-- **[0.12.18]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.12.21",
+  "version": "0.12.23",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
 
@@ -57,6 +57,7 @@
     "verify:sandbox": "bun scripts/verify-sandbox-isolation.ts",
     "verify:browser": "bun scripts/verify-browser.ts",
     "verify:discord": "bun scripts/verify-discord-integration.ts",
+    "verify:shared-global": "bun scripts/verify-shared-global-isolation.ts",
     "verify:tmux": "bash scripts/tmux-verify.sh",
     "dev:link": "bun scripts/dev-link.ts link",
     "dev:doctor": "bun scripts/dev-link.ts doctor"

package/src/agent/AGENTS.md

@@ -26,7 +26,7 @@ The core runtime loop, tool registry, session management, and state persistence
 | `config-schema.ts` | Brief description of purpose |
 | `context-files.ts` | Brief description of purpose |
 | `engine.ts` | Brief description of purpose |
-| `hooks.ts` | Brief description of purpose |
+| `hooks.ts` | Command-hook runtime: `loadHooks` (user registry `~/.jeo/hooks.json` ⊕ `config.json`/project `.jeo/hooks.json`, with the `hooks.enabled=false` kill switch and project `enabled:false` opt-out; the registry is skipped in sandboxed sessions), `runPreToolHooks` (veto by exit code or structured `permissionDecision`, `additionalContext` passthrough), `runPostTurnHooksForBatch`, `runPostImplementationHooks`, and the per-turn `runPrePromptHooks` (context injected by `commands/launch.ts` into the prompt message) / `runTurnEndHooks` (final reply to ingesters); payloads follow the Claude hook protocol on the host (`hook_event_name`, `session_id`, `cwd`, `tool_name`/`tool_input`) and stay legacy-shaped in a sandbox |
 | `json.ts` | Brief description of purpose |
 | `loop.ts` | The primary execution loop orchestrating model calls and tool execution |
 | `loop-guards.ts` | Intermediate-judgment classification (gjc ultragoal-guard parity): named `GuardState` taxonomy, `GUARD_LIMITS` thresholds, and pure classifiers (`verifierCores`/`isVerificationSignal` — recognizes wrapped verifiers such as `cd x && bun test`, env/`timeout`/`uv run`/`rtk` prefixes and `2>&1`, never pipes or `;` — `repeatHint`, `classifyDoneGate` incl. `done_stale_verification`, and `formatRejectedCompletion`, which keeps the last candidate answer under an `UNVERIFIED` marker when corrections are exhausted) consumed by `engine.ts` |

package/src/agent/config-schema.ts

@@ -45,7 +45,7 @@ const HookConfigSchema = z.object({
   hooks: z
     .array(
       z.object({
-        event: z.enum(["pre-tool", "post-turn", "post-implementation"]),
+        event: z.enum(["pre-tool", "post-turn", "post-implementation", "pre-prompt", "turn-end"]),
         match: z
           .object({
             tool: z.string().optional(),

package/src/agent/engine.ts

@@ -1411,6 +1411,9 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
               // an unchanged recently-modified file is hashed on both sides or neither.
               mutationMayHaveOccurred = before.ok ? workspaceSnapshotChanged(before, await takeSnapshot(before.startedAtMs)) : true;
             }
+            // A pre-tool hook's structured `additionalContext` rides along with the result
+            // so the model sees it next to the output it concerns.
+            if (preHookResult.context) output = `${output}\n\n[pre-tool hook context]\n${preHookResult.context}`;
           }
         }
       }

package/src/agent/hooks.ts

@@ -22,8 +22,8 @@ export function withSandboxExecution<T>(scope: SandboxExecutionScope, run: () =>
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { resolvePosixTool } from "../util/posix-tools";
-import { readGlobalConfig } from "./state";
-import type { HookConfig } from "./state";
+import { readGlobalConfig, userHooksPath } from "./state";
+import type { HookConfig, HookEntry, HookEvent } from "./state";
 
 interface HookRunResult {
   stdout: string;
@@ -57,6 +57,23 @@ type LocalHooks =
 const localHooksCache = new Map<string, { mtimeMs: number; size: number; result: LocalHooks }>();
 const LOCAL_HOOKS_CACHE_CAP = 32;
 
+const HOOK_EVENTS: ReadonlySet<string> = new Set<HookEvent>(["pre-tool", "post-turn", "post-implementation", "pre-prompt", "turn-end"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Hook files are written by installers as well as by hand: drop entries that cannot run
+ *  (unknown event, missing command, bad timeout) instead of letting one poison the batch. */
+function isHookEntry(value: unknown): value is HookEntry {
+  if (!isRecord(value)) return false;
+  if (typeof value.event !== "string" || !HOOK_EVENTS.has(value.event)) return false;
+  if (typeof value.run !== "string" || !value.run.trim()) return false;
+  if (value.timeoutMs !== undefined && !(typeof value.timeoutMs === "number" && value.timeoutMs > 0)) return false;
+  if (value.match !== undefined && !isRecord(value.match)) return false;
+  return true;
+}
+
 async function readLocalHooks(localPath: string): Promise<LocalHooks> {
   let st: { mtimeMs: number; size: number };
   try {
@@ -72,7 +89,7 @@ async function readLocalHooks(localPath: string): Promise<LocalHooks> {
     const parsed = JSON.parse(await fs.readFile(localPath, "utf-8"));
     if (parsed && typeof parsed === "object") {
       if (parsed.enabled === false) result = { kind: "disabled" };
-      else if (Array.isArray(parsed.hooks)) result = { kind: "hooks", hooks: parsed.hooks };
+      else if (Array.isArray(parsed.hooks)) result = { kind: "hooks", hooks: parsed.hooks.filter(isHookEntry) };
     }
   } catch {
     // Missing/invalid local file → fall back to the global config hooks.
@@ -85,35 +102,66 @@ async function readLocalHooks(localPath: string): Promise<LocalHooks> {
   return result;
 }
 
-export async function loadHooks(cwd: string, signal?: AbortSignal): Promise<NonNullable<HookConfig["hooks"]>> {
-  const config = await readGlobalConfig();
-  if (!config.hooks?.enabled) {
-    return [];
+/**
+ * A sandboxed session reads the project hook file through the supervisor so the host
+ * never trusts workspace content it did not mediate. Same outcome shape as
+ * `readLocalHooks`.
+ */
+async function readSandboxLocalHooks(sandbox: SandboxExecutionScope, cwd: string, signal?: AbortSignal): Promise<LocalHooks> {
+  const result = await sandbox.supervisor.exec(["bun", "-e", "const file=Bun.file('.jeo/hooks.json');let value={};try{if(await file.exists())value=await file.json()}catch{}process.stdout.write(JSON.stringify(value));"], { cwd, signal: signal ?? sandbox.signal });
+  if (!result.success || result.exitCode !== 0) throw new Error(`Sandbox project hook configuration read failed (exit code ${result.exitCode ?? "unavailable"}): ${result.error || result.output}`);
+  let local: unknown;
+  try { local = JSON.parse(result.stdout ?? result.output); }
+  catch { throw new Error("Malformed sandbox project hook configuration"); }
+  if (isRecord(local)) {
+    if (local.enabled === false) return { kind: "disabled" };
+    if (Array.isArray(local.hooks)) return { kind: "hooks", hooks: local.hooks.filter(isHookEntry) };
   }
+  return { kind: "fallback" };
+}
+
+/**
+ * Effective hook list, in run order: user registry (`userHooksPath()`) first, then the
+ * configured list.
+ *
+ * Precedence, strongest first:
+ *  1. `config.hooks.enabled === false` — global kill switch; nothing runs.
+ *  2. Project `.jeo/hooks.json` with `enabled: false` — project opt-out; nothing runs.
+ *  3. The user registry runs unless it opts itself out (`enabled: false`). It is
+ *     user-owned and installer-managed, so it does NOT need `config.hooks.enabled: true`.
+ *  4. `config.hooks.hooks` / the project `.jeo/hooks.json` list run only when
+ *     `config.hooks.enabled === true` (so an untrusted repo cannot enable its own hooks);
+ *     the project list replaces the config list, as before, but never the user registry.
+ *
+ * Sandboxed sessions skip the user registry: its commands live on the host and cannot
+ * run inside the sandbox.
+ */
+export async function loadHooks(cwd: string, signal?: AbortSignal): Promise<HookEntry[]> {
+  const config = await readGlobalConfig();
+  if (config.hooks?.enabled === false) return [];
 
   const sandbox = currentSandboxExecution();
-  if (sandbox) {
-    const result = await sandbox.supervisor.exec(["bun", "-e", "const file=Bun.file('.jeo/hooks.json');let value={};try{if(await file.exists())value=await file.json()}catch{}process.stdout.write(JSON.stringify(value));"], { cwd, signal: signal ?? sandbox.signal });
-    if (!result.success || result.exitCode !== 0) throw new Error(`Sandbox project hook configuration read failed (exit code ${result.exitCode ?? "unavailable"}): ${result.error || result.output}`);
-    let local: unknown;
-    try { local = JSON.parse(result.stdout ?? result.output); }
-    catch { throw new Error("Malformed sandbox project hook configuration"); }
-    if (local && typeof local === "object") {
-      if ("enabled" in local && local.enabled === false) return [];
-      if ("hooks" in local && Array.isArray(local.hooks)) return local.hooks;
-    }
-    return config.hooks.hooks || [];
-  }
-  const local = await readLocalHooks(path.join(cwd, ".jeo", "hooks.json"));
+  const configHooksOn = config.hooks?.enabled === true;
+  // Sandboxed sessions read the project file only when hooks are explicitly enabled, as before.
+  if (sandbox && !configHooksOn) return [];
+  // The registry lives on the host; a sandboxed session never runs it.
+  const user = sandbox ? undefined : await readLocalHooks(userHooksPath());
+  const userHooks = user?.kind === "hooks" ? user.hooks : [];
+  // Common case (no registry, hooks not enabled): nothing can run, so skip the project file.
+  if (!configHooksOn && userHooks.length === 0) return [];
+
+  const local = sandbox
+    ? await readSandboxLocalHooks(sandbox, cwd, signal)
+    : await readLocalHooks(path.join(cwd, ".jeo", "hooks.json"));
   if (local.kind === "disabled") return [];
-  if (local.kind === "hooks") return local.hooks;
 
-  return config.hooks?.hooks || [];
+  const configured = !configHooksOn ? [] : local.kind === "hooks" ? local.hooks : config.hooks?.hooks ?? [];
+  return userHooks.length ? [...userHooks, ...configured] : configured;
 }
 
 async function runHookCommand(
   runCmd: string,
-  payload: any,
+  payload: unknown,
   cwd: string,
   timeoutMs = 30000,
   signal?: AbortSignal
@@ -211,13 +259,79 @@ export function hookMatchesTool(matchTool: string | undefined, tool: string): bo
   return matchTool.split("|").some(t => t.trim() === tool);
 }
 
+let hookSessionId = "";
+
+/** Set by the launch loop so every hook payload carries the live session id
+ *  (`session_id`, Claude hook protocol). Empty string when no session is active. */
+export function setHookSessionId(sessionId: string | undefined): void {
+  hookSessionId = sessionId ?? "";
+}
+
+/**
+ * Fields every hook payload carries. `event` is jeo's own name (kept for existing hooks);
+ * `hook_event_name`/`session_id`/`cwd` follow the Claude hook protocol so scripts written
+ * for Claude Code / Codex (`UserPromptSubmit`, `Stop`, `PreToolUse`) run unmodified.
+ *
+ * A sandboxed hook runs in the guest, so it gets the legacy payload only: never the host
+ * `cwd` or session id.
+ */
+function basePayload(event: HookEvent, claudeEvent: string, cwd: string) {
+  if (currentSandboxExecution()) return { event };
+  return { event, hook_event_name: claudeEvent, session_id: hookSessionId, cwd };
+}
+
+/** Claude-protocol aliases (`tool_name`/`tool_input`) for a tool call; none in a sandbox. */
+function toolAliases(tool: string, args: Record<string, unknown>) {
+  return currentSandboxExecution() ? {} : { tool_name: tool, tool_input: args };
+}
+
+const MAX_HOOK_CONTEXT_CHARS = 8_000;
+
+function parseHookJson(stdout: string): Record<string, unknown> | undefined {
+  const text = stdout.trim();
+  if (!text.startsWith("{")) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function clampContext(text: string): string {
+  return text.length > MAX_HOOK_CONTEXT_CHARS ? `${text.slice(0, MAX_HOOK_CONTEXT_CHARS)}\n... (hook context truncated)` : text;
+}
+
+/** `additionalContext` from a Claude-protocol hook output (`hookSpecificOutput.additionalContext`,
+ *  top-level `additionalContext`, or `context`). Empty when the output carries none. */
+function jsonHookContext(json: Record<string, unknown>): string {
+  const specific = isRecord(json.hookSpecificOutput) ? json.hookSpecificOutput : {};
+  for (const value of [specific.additionalContext, json.additionalContext, json.context]) {
+    if (typeof value === "string" && value.trim()) return clampContext(value.trim());
+  }
+  return "";
+}
+
+/** A deny decision a hook returned with exit 0 (Claude `permissionDecision: deny|ask`,
+ *  legacy `decision: block`, or `continue: false`). jeo has no approval prompt for hooks,
+ *  so `ask` is treated as deny — the safe reading. */
+function jsonHookDenial(json: Record<string, unknown>): { reason: string } | undefined {
+  const specific = isRecord(json.hookSpecificOutput) ? json.hookSpecificOutput : {};
+  const decision = specific.permissionDecision ?? json.decision;
+  const denied = decision === "deny" || decision === "ask" || decision === "block" || json.continue === false;
+  if (!denied) return undefined;
+  const reason = [specific.permissionDecisionReason, json.reason, json.stopReason].find(v => typeof v === "string" && v.trim());
+  return { reason: typeof reason === "string" ? reason.trim() : "no reason given" };
+}
+
 export async function runPreToolHooks(
   cwd: string,
   tool: string,
-  args: Record<string, any>,
+  args: Record<string, unknown>,
   signal?: AbortSignal,
   onNotice?: (msg: string) => void
-): Promise<{ vetoed: boolean; error?: string; output?: string }> {
+): Promise<{ vetoed: boolean; error?: string; output?: string; context?: string }> {
+  const contexts: string[] = [];
   try {
     const hooks = await loadHooks(cwd, signal);
     const preToolHooks = hooks.filter(
@@ -226,9 +340,10 @@ export async function runPreToolHooks(
 
     for (const hook of preToolHooks) {
       const payload = {
-        event: "pre-tool",
+        ...basePayload("pre-tool", "PreToolUse", cwd),
         tool,
         args,
+        ...toolAliases(tool, args),
       };
 
       const timeoutMs = hook.timeoutMs || 30000;
@@ -248,14 +363,27 @@ export async function runPreToolHooks(
         onNotice?.(msg);
         return { vetoed: true, error: msg, output: result.output };
       }
+      // Exit 0 can still carry a structured decision (Claude-protocol hooks never exit 2
+      // to deny; they print `permissionDecision`). Plain stdout stays ignored so a
+      // hook's own logging never leaks into the model's tool result.
+      const json = parseHookJson(result.stdout);
+      if (!json) continue;
+      const denial = jsonHookDenial(json);
+      if (denial) {
+        const msg = `Pre-tool hook "${hook.run}" denied execution: ${denial.reason}`;
+        onNotice?.(msg);
+        return { vetoed: true, error: msg };
+      }
+      const context = jsonHookContext(json);
+      if (context) contexts.push(context);
     }
-  } catch (err: any) {
-    const msg = `Error executing pre-tool hooks: ${err.message}`;
+  } catch (err: unknown) {
+    const msg = `Error executing pre-tool hooks: ${err instanceof Error ? err.message : String(err)}`;
     onNotice?.(msg);
     return { vetoed: true, error: msg, output: "" };
   }
 
-  return { vetoed: false };
+  return contexts.length ? { vetoed: false, context: contexts.join("\n") } : { vetoed: false };
 }
 
 /** One executed tool call fed to the post-turn hooks of a batch. */
@@ -301,10 +429,11 @@ export async function runPostTurnHooksForBatch(
     // Distinct hooks are independent commands → run them concurrently. Each hook
     // itself runs once for the whole batch (the redundancy this fix removes).
     const settled = await Promise.all(jobs.map(async ({ hook, matched }) => {
+      const base = basePayload("post-turn", "PostToolUse", cwd);
       const payload = matched.length === 1
-        ? { event: "post-turn", tool: matched[0].tool, args: matched[0].args, success: matched[0].success, output: outputPreviewOf(matched[0].output) }
+        ? { ...base, tool: matched[0].tool, args: matched[0].args, ...toolAliases(matched[0].tool, matched[0].args), success: matched[0].success, output: outputPreviewOf(matched[0].output) }
         : {
-            event: "post-turn",
+            ...base,
             tool: matched.map(c => c.tool).join(","),
             calls: matched.map(c => ({ tool: c.tool, args: c.args, success: c.success })),
             success: matched.every(c => c.success),
@@ -368,7 +497,7 @@ export async function runPostImplementationHooks(
 
     for (const hook of postImplHooks) {
       const payload = {
-        event: "post-implementation",
+        ...basePayload("post-implementation", "post-implementation", cwd),
         request,
       };
 
@@ -389,3 +518,124 @@ export async function runPostImplementationHooks(
     return { success: false, output: msg };
   }
 }
+
+const PRE_PROMPT_TIMEOUT_MS = 10_000;
+const TURN_END_TIMEOUT_MS = 30_000;
+const MAX_PROMPT_PAYLOAD_CHARS = 20_000;
+const MAX_RESPONSE_PAYLOAD_CHARS = 200_000;
+
+export interface PrePromptHookResult {
+  /** Context the hooks asked to place in front of the model (empty when none). */
+  context: string;
+  /** Hooks that ran to completion (exit 0) — lets callers tell "nothing to add" from "no hook". */
+  ran: number;
+}
+
+/**
+ * Run `pre-prompt` hooks once for a real user prompt, before the model sees it
+ * (Claude `UserPromptSubmit`). Payload: `{event, hook_event_name:"UserPromptSubmit",
+ * session_id, cwd, prompt}`. A hook contributes context by printing either plain text or a
+ * Claude-protocol JSON object (`hookSpecificOutput.additionalContext` / `additionalContext`
+ * / `context`). This is a routing/enrichment point, never a gate: a hook that fails, times
+ * out or is aborted yields a notice and no context, so a broken hook can't block a prompt.
+ */
+export async function runPrePromptHooks(
+  cwd: string,
+  prompt: string,
+  signal?: AbortSignal,
+  onNotice?: (msg: string) => void,
+): Promise<PrePromptHookResult> {
+  const contexts: string[] = [];
+  let ran = 0;
+  try {
+    const hooks = (await loadHooks(cwd, signal)).filter(h => h.event === "pre-prompt");
+    if (hooks.length === 0 || !prompt.trim()) return { context: "", ran: 0 };
+    const payload = { ...basePayload("pre-prompt", "UserPromptSubmit", cwd), prompt: prompt.slice(0, MAX_PROMPT_PAYLOAD_CHARS) };
+    const settled = await Promise.all(hooks.map(async hook => {
+      try {
+        return { hook, result: await runHookCommand(hook.run, payload, cwd, hook.timeoutMs || PRE_PROMPT_TIMEOUT_MS, signal) };
+      } catch (err: unknown) {
+        onNotice?.(`Pre-prompt hook "${hook.run}" failed to start (advisory): ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+      }
+    }));
+    // Hook order, not completion order, decides how contexts are stacked.
+    for (const entry of settled) {
+      if (!entry) continue;
+      const { hook, result } = entry;
+      if (result.timedOut) onNotice?.(`Pre-prompt hook "${hook.run}" timed out (advisory).`);
+      else if (result.aborted) continue;
+      else if (result.exitCode !== 0) onNotice?.(`Pre-prompt hook "${hook.run}" exited with non-zero code ${result.exitCode} (advisory).`);
+      else {
+        ran++;
+        const json = parseHookJson(result.stdout);
+        const context = json ? jsonHookContext(json) : clampContext(result.stdout.trim());
+        if (context) contexts.push(context);
+      }
+    }
+  } catch (err: unknown) {
+    onNotice?.(`Error executing pre-prompt hooks (advisory): ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return { context: contexts.join("\n\n"), ran };
+}
+
+export interface TurnEndInfo {
+  prompt: string;
+  /** The final reply text of the turn. */
+  response: string;
+  /** True when the model signalled completion (false for a step-limit/unverified stop). */
+  done: boolean;
+  steps: number;
+  model?: string;
+}
+
+/**
+ * Run `turn-end` hooks once per finished turn (Claude `Stop`). Payload carries the turn's
+ * final reply under `response` and `last_assistant_message` (and `assistant_output`) so
+ * scripts that ingest assistant output can read it directly, alongside `prompt`, `done`,
+ * `steps`, `model`, `session_id`, `cwd`. Advisory only: failures yield a notice and never
+ * change the turn's result. Awaited so a one-shot `jeo -p` does not exit before they finish.
+ */
+export async function runTurnEndHooks(
+  cwd: string,
+  info: TurnEndInfo,
+  signal?: AbortSignal,
+  onNotice?: (msg: string) => void,
+): Promise<{ ran: number }> {
+  let ran = 0;
+  try {
+    const hooks = (await loadHooks(cwd, signal)).filter(h => h.event === "turn-end");
+    if (hooks.length === 0) return { ran: 0 };
+    const response = info.response.length > MAX_RESPONSE_PAYLOAD_CHARS ? info.response.slice(0, MAX_RESPONSE_PAYLOAD_CHARS) : info.response;
+    const payload = {
+      ...basePayload("turn-end", "Stop", cwd),
+      prompt: info.prompt.slice(0, MAX_PROMPT_PAYLOAD_CHARS),
+      response,
+      last_assistant_message: response,
+      assistant_output: response,
+      done: info.done,
+      steps: info.steps,
+      model: info.model ?? "",
+      stop_hook_active: false,
+    };
+    const settled = await Promise.all(hooks.map(async hook => {
+      try {
+        return { hook, result: await runHookCommand(hook.run, payload, cwd, hook.timeoutMs || TURN_END_TIMEOUT_MS, signal) };
+      } catch (err: unknown) {
+        onNotice?.(`Turn-end hook "${hook.run}" failed to start (advisory): ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+      }
+    }));
+    for (const entry of settled) {
+      if (!entry) continue;
+      const { hook, result } = entry;
+      if (result.timedOut) onNotice?.(`Turn-end hook "${hook.run}" timed out (advisory).`);
+      else if (result.aborted) continue;
+      else if (result.exitCode !== 0) onNotice?.(`Turn-end hook "${hook.run}" exited with non-zero code ${result.exitCode} (advisory).`);
+      else ran++;
+    }
+  } catch (err: unknown) {
+    onNotice?.(`Error executing turn-end hooks (advisory): ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return { ran };
+}