codex-agent-view 0.2.0 → 0.2.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Read-only local monitor for Codex parent-task and subagent lifecycle events.",
   "author": {
     "name": "Junho Yoon",

package/README.md

@@ -8,23 +8,27 @@ Codex Agent View는 공식 Codex 앱을 그대로 사용하면서 부모 task와
 
 ### 현재 상태
 
-현재 source version은 `0.2.0`이다. 다음 구성은 구현되어 있다.
+현재 source version은 `0.2.1`이다. 다음 구성은 구현되어 있다.
 
 - `.codex-plugin/plugin.json`, local marketplace catalog, genuine Codex skill
-- `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, `PermissionRequest` hook wiring
+- 부모 task용 `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Stop`과 subagent/tool/permission hook wiring
 - privacy-minimized hook sender와 bounded in-memory reducer
 - `127.0.0.1` 전용 token-authenticated local HTTP runtime
 - 부모 task/session, subagent, 최근 활동, permission wait 상태를 표시하는 local UI
 - `start`, `status`, `doctor`, `install`, `uninstall` CLI
 - 명시적 설치·hook trust·제거 경로
 
-Homebrew Codex CLI와 공식 앱에 포함된 embedded Codex executable에서 plugin 설치와 실제 lifecycle payload를 검증했다. Local companion 제품 구현은 완료되었으며, 공식 Codex 앱의 **현재 GUI task에서 trusted hook → local monitor → UI 전체 흐름을 확인하는 최종 E2E**와 실제 `PermissionRequest` payload 관찰은 외부 compatibility acceptance로 남아 있다. 이는 구현되지 않은 제품 기능 목록이 아니라 현재 공식 앱 조합에 대한 미확인 검증 범위다.
+Homebrew Codex CLI와 공식 앱에 포함된 embedded Codex executable에서는 plugin 설치와 lifecycle payload를 검증했다. 그러나 `0.2.0`을 실행 중인 공식 앱 process에 설치·enable한 실사용 재현에서는 실제 subagent 2개를 실행해도 monitor가 event를 0건 수신했다. Monitor, plugin 등록, enable, 설치 bundle은 정상이었지만 앱 log에는 sender 실행 흔적이 없었다. 같은 app process가 설치 전의 `hooks/list` snapshot을 유지한 정황이 있으며, CLI JSON으로 exact hook trust 상태를 확인할 수 없어 config snapshot과 trust 중 어느 경계에서 skip됐는지는 확정하지 않았다.
+
+`0.2.1`은 부모 task lifecycle hook을 추가하고, `status`, `doctor`, 빈 UI가 “monitor 정상”과 “hook event 수신”을 구분하도록 개선한 patch다. 공식 Codex 앱 `26.727.40816`(`build 6067`)을 재시작하고 설치·활성화된 plugin `0.2.1`을 사용한 실제 E2E에서 task ID를 사전 등록하지 않아도 parent session 3개와 subagent 3개가 UI에 자동으로 나타났다. 실제 hook의 `SessionStart`, `UserPromptSubmit`, `Stop`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, `PermissionRequest`가 sender → loopback monitor → UI 경로에 반영됐다. `SessionEnd` wiring은 포함돼 있지만 실제 공식 앱 event는 아직 관찰하지 않았으므로 호환 확인을 주장하지 않는다.
 
 Maintainer npm 2FA는 `auth-and-writes` mode로 활성화됐고 `codex-agent-view@0.2.0`은 public npm registry에서 사용할 수 있다. npm publish와 별개인 Universal Plugins Directory 제출은 아직 완료되지 않아 directory 검색에는 나타나지 않는다.
 
+검증된 `0.2.0` 릴리스: npm `gitHead`와 annotated `v0.2.0` tag는 commit `00b62af56698ac875e39c7d1386905c157c3a7e8`로 일치하고, registry SRI/signature 및 tag source와 registry artifact의 21개 package file byte 일치를 확인했다. [GitHub Release v0.2.0](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.2.0)은 공개 상태다. 별도 npm provenance attestation은 선택 사항이며 이 릴리스에는 없다.
+
 ### 제품 경계
 
-Codex Agent View는 historical audit이나 session replay 제품이 아니라 현재 활동을 보여주는 live companion이다. Bounded in-memory state와 monitor 재시작 시 reset은 privacy와 단순한 failure boundary를 위한 의도된 `0.2.0` 완성 설계다. SQLite/영구 history는 누락된 요구사항이 아니다. 실제 사용자 요구가 입증될 때에만 retention, migration, deletion, privacy 비용을 별도 검토하는 명시적 opt-in 기능 후보로 취급한다.
+Codex Agent View는 historical audit이나 session replay 제품이 아니라 현재 활동을 보여주는 live companion이다. Bounded in-memory state와 monitor 재시작 시 reset은 privacy와 단순한 failure boundary를 위한 의도된 완성 설계다. SQLite/영구 history는 누락된 요구사항이 아니다. 실제 사용자 요구가 입증될 때에만 retention, migration, deletion, privacy 비용을 별도 검토하는 명시적 opt-in 기능 후보로 취급한다.
 
 - live 상태의 source of truth는 hook event다.
 - Live 상태는 설계대로 monitor process의 bounded memory에만 있고 재시작하면 새 관찰 window가 시작된다.
@@ -33,6 +37,14 @@ Codex Agent View는 historical audit이나 session replay 제품이 아니라
 - task/subagent 중지·재시작, message 전송, permission 자동 승인·거절 기능이 없다.
 - App Server는 향후 계층 metadata 보강 후보일 뿐이며 공식 앱 process와 memory를 공유한다고 가정하지 않는다.
 
+별도로 실행한 Codex `0.146` App Server의 `thread/list` fallback도 실제 확인했지만 현재 root/subagent가 모두 `notLoaded`로 나타나 공식 앱의 live running/completed 상태를 공유하지 않았다. Persisted parent ID, alias, depth 보강은 가능하나 live 판별은 불가능했고 state DB read, privacy, 복잡도만 늘어나므로 `0.2.1`에는 채택하지 않았다.
+
+### npm, local browser UI, Plugins Directory가 각각 필요한 이유
+
+- npm은 `codex-agent-view` local executable, hook sender, runtime, static UI를 사용자 machine에 배포하는 경로다.
+- Browser는 `127.0.0.1`에서만 열리는 현재 read-only companion UI다. 외부 website나 telemetry dashboard가 아니다.
+- Universal Plugins Directory는 npm의 대체재가 아니다. 공개 directory의 in-app custom UI 경로는 public HTTPS MCP server와 domain verification이 필요해 local-only/no-external-server 원칙과 충돌한다. 현재는 별도의 listing/skills 제출 가능성만 검토하며, 심사·publish 전에는 Codex plugin 검색으로 설치할 수 있다고 안내하지 않는다.
+
 Hook event가 누락·중복·역순으로 올 수 있으므로 UI의 `unknown`, `stopped_without_start`, 빈 상태는 그대로 해석해야 한다. 빈 session 목록은 “이 monitor가 event를 관찰하지 못함”이며 “실행 중인 task가 없음”의 증거가 아니다.
 
 ### 요구사항과 검증 범위
@@ -45,7 +57,7 @@ Hook event가 누락·중복·역순으로 올 수 있으므로 UI의 `unknown`,
 
 | Runtime | 확인된 버전 | 확인 범위 |
 | --- | --- | --- |
-| 공식 Codex 앱 | `26.727.40816` (`build 6067`) | bundle metadata, GUI current-task compatibility acceptance 대기 |
+| 공식 Codex 앱 | `26.727.40816` (`build 6067`) | 재시작한 현재 조합에서 plugin `0.2.1`의 parent 3개·subagent 3개 자동 표시 및 실제 hook 8종 E2E 확인; `SessionEnd` 미관찰 |
 | 앱 embedded Codex | `0.146.0-alpha.9.2` | isolated plugin install/runtime 및 lifecycle probe |
 | Homebrew Codex CLI | `0.146.0` | isolated plugin install/runtime probe |
 
@@ -89,7 +101,8 @@ node bin/codex-agent-view.mjs install
 2. 공식 앱의 Plugins Directory 또는 CLI `/plugins`에서 plugin이 설치·활성화됐는지 확인한다.
 3. CLI TUI composer의 `/hooks` 또는 공식 앱의 해당 hook review UI에서 `hooks/hooks.json`과 `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command를 검토한다.
 4. 현재 hook definition의 exact hash를 사용자가 직접 trust한다.
-5. 공식 앱을 완전히 재시작하고 **새 task**를 만든다.
+5. Plugin 설치 전부터 공식 앱이 열려 있었다면 앱을 완전히 종료·재실행한다.
+6. 반드시 plugin 활성화와 hook trust 이후에 **새 task**를 만든다. 설치·trust 전에 발생한 event는 재생되지 않는다.
 
 `/hooks`는 CLI TUI command이며 `codex /hooks`라는 shell command가 아니다. Hook definition이 바뀌면 hash도 바뀌므로 다시 검토한다. 일반 설치에서 trust-bypass option을 사용하지 않는다.
 
@@ -117,17 +130,20 @@ node bin/codex-agent-view.mjs doctor --json
 
 - `status`는 실행 중 monitor가 관찰한 task/session과 subagent 수를 읽는다.
 - `status --json`은 hook 기반 snapshot과 bounded diagnostics를 반환한다.
-- `doctor`는 Codex CLI, plugin 설치, monitor, runtime directory를 진단한다.
+- `doctor`는 Codex CLI, plugin 설치·enable, 설치된 hook bundle, monitor event 수신 여부, runtime directory를 진단한다.
+- `doctor`의 hook trust는 `unknown`일 수 있다. `codex plugin list --json`은 persisted exact-hook trust를 노출하지 않으므로 interactive Codex CLI의 `/hooks`에서 직접 확인한다.
 - `Ctrl+C`는 monitor를 종료하며 in-memory state와 정상 종료된 runtime file을 정리한다.
 
 Monitor가 꺼져 있어도 hook sender는 fail-open으로 끝나 Codex task를 막지 않는다. Monitor를 나중에 켜면 꺼져 있던 동안의 event가 복구되지는 않는다.
 
+Monitor가 실행 중이고 plugin enable/trust가 끝난 뒤 생성되거나 재개되는 task는 hook이 도착하면 task ID를 미리 등록하지 않아도 자동으로 목록에 나타난다. UI 검색은 이렇게 자동 수신된 목록을 거르는 선택적 filter일 뿐이며, task 추적을 시작하거나 ID를 등록하는 기능이 아니다. Plugin 설치·trust 전이나 monitor downtime에 이미 지나간 event는 재생되지 않는다.
+
 ### npm에서 설치
 
-권장 설치 방법은 public registry의 exact version을 global로 설치하는 것이다.
+`0.2.1` release의 권장 설치 방법은 exact version을 global로 설치하는 것이다. 이 문서 작성 시점에 public registry에서 확인된 버전은 아직 `0.2.0`이므로, `0.2.1` publish가 확인되기 전에는 이 repository source에서 검증한다.
 
 ```bash
-npm install --global codex-agent-view@0.2.0
+npm install --global codex-agent-view@0.2.1
 codex-agent-view doctor
 codex-agent-view install
 codex-agent-view start
@@ -136,11 +152,13 @@ codex-agent-view start
 Global install 없이 exact version을 일회성으로 실행할 수도 있다.
 
 ```bash
-npx --yes codex-agent-view@0.2.0 doctor
-npx --yes codex-agent-view@0.2.0 install
-npx --yes codex-agent-view@0.2.0 start
+npx --yes codex-agent-view@0.2.1 doctor
+npx --yes codex-agent-view@0.2.1 install
+npx --yes codex-agent-view@0.2.1 start
 ```
 
+위 public artifact 검증 기록은 `0.2.0`에 대한 것이다. Isolated global install과 exact-version `npx` 양쪽에서 CLI lifecycle을 통과했고 fixture event는 status/UI에 반영됐지만, 이후 실행 중이던 실제 공식 앱 process에서는 event 0건이 재현됐다. 별도의 `0.2.1` source/package QA와 재시작한 공식 앱 E2E에서는 실제 hook 8종과 task ID 등록 없는 자동 표시를 확인했다. 다만 `0.2.1` registry artifact, digest, tag·GitHub Release는 publish 뒤 별도로 검증해야 하며, 실제 `SessionEnd`도 아직 미관찰이다. Registry evidence와 검증 경계는 [docs/distribution.md](docs/distribution.md)에 기록한다.
+
 npm install 자체는 Codex 설정을 자동 변경하지 않는다. `install` command는 사용자가 명시적으로 실행하며 hook trust도 사용자 검토로 남긴다. npm publish와 Universal Plugins Directory 제출은 서로 별도 절차다. 자세한 배포 경계는 [docs/distribution.md](docs/distribution.md), directory 제출 상태는 [docs/plugin-submission.md](docs/plugin-submission.md)를 참고한다.
 
 ### Privacy와 opt-in diagnostic capture
@@ -182,15 +200,19 @@ Monitor가 실행 중인지, stale runtime file인지, runtime directory가 예
 
 #### UI에 task/subagent가 없음
 
-- plugin이 설치뿐 아니라 enable됐는지 확인한다.
-- 현재 `send-hook.mjs` definition을 검토하고 trust했는지 확인한다.
-- plugin enable/trust 후 공식 앱을 재시작하고 새 task를 만들었는지 확인한다.
-- monitor가 event 발생 전에 실행 중이었는지 확인한다.
-- 빈 상태만으로 GUI hook 미지원이라고 결론내리지 않는다.
+다음 순서대로 확인한다.
+
+1. `codex-agent-view doctor --json`에서 plugin `installed`, `enabled`, hook bundle `wiring_ok`, monitor `ok`를 확인한다.
+2. `monitor.events_received`가 `false`라면 monitor 연결 성공과 hook 전달 성공을 혼동하지 않는다.
+3. Interactive Codex CLI의 `/hooks`에서 현재 `send-hook.mjs` definition의 exact hash를 검토하고 trust한다.
+4. Plugin 설치 전에 열려 있던 공식 앱은 완전히 종료·재실행한다.
+5. Plugin enable/trust 뒤 만든 새 task에서 parent prompt와 subagent를 실행한다.
+
+빈 상태는 “이 monitor observation window에 event가 도착하지 않음”을 뜻한다. Codex에 실행 중인 task가 없다는 뜻도, 반대로 GUI가 hook을 절대 지원하지 않는다는 뜻도 아니다. 위 절차 뒤에도 `events_received: false`이면 Codex 앱 version, plugin version, 앱/CLI 구분을 포함해 issue로 보고한다.
 
 #### `PermissionRequest`가 표시되지 않음
 
-Approval이 실제 필요한 동작에서만 발생할 수 있다. 현재 공식 앱 GUI의 실제 payload는 external compatibility evidence가 아직 없어, 표시되지 않는 원인을 schema 문제와 “event 자체가 발생하지 않음”으로 분리해 조사한다. Monitor는 approval을 자동 처리하지 않는다.
+Approval이 실제 필요한 동작에서만 발생할 수 있다. 공식 앱 `26.727.40816`(`build 6067`) E2E에서는 실제 `PermissionRequest` hook이 sender → loopback monitor → UI에 도착해 read-only waiting 상태로 표시되는 것을 확인했다. 다른 환경에서 표시되지 않으면 schema 문제와 “event 자체가 발생하지 않음”을 분리해 조사한다. Monitor는 approval을 자동 처리하지 않는다.
 
 ### 문서와 지원
 
@@ -213,15 +235,19 @@ Codex Agent View is a lightweight, read-only companion monitor for the official
 
 ### Status
 
-The current source version is `0.2.0`. It includes the plugin and marketplace manifests, a genuine Codex skill, privacy-minimized hooks, a bounded in-memory reducer, a token-authenticated `127.0.0.1` runtime, a local dashboard, and `start`, `status`, `doctor`, `install`, and `uninstall` commands. The local companion product implementation is complete.
+The current source version is `0.2.1`. It includes the plugin and marketplace manifests, a genuine Codex skill, privacy-minimized parent-task, subagent, tool, and permission hooks, a bounded in-memory reducer, a token-authenticated `127.0.0.1` runtime, a local dashboard, and `start`, `status`, `doctor`, `install`, and `uninstall` commands.
+
+Plugin installation and lifecycle payloads were verified with Homebrew Codex CLI and the Codex executable embedded in the official app. However, a real-use attempt that installed and enabled `0.2.0` in an already-running official app process delivered zero events while two subagents ran. The monitor, registration, enablement, and installed bundle were healthy, while app logs showed no sender invocation. Evidence indicates that the same process retained a pre-install `hooks/list` snapshot; persisted exact-hook trust is not exposed through CLI JSON, so the precise skip boundary remains unconfirmed.
 
-Plugin installation and real lifecycle payloads were verified with Homebrew Codex CLI and the Codex executable embedded in the official app. The final **trusted hook → local monitor → UI E2E in a current official Codex GUI task remains unverified**, and a real `PermissionRequest` payload has not been observed. These are external compatibility-acceptance checks for the current official app combination, not missing local product features.
+`0.2.1` adds `SessionStart`, `SessionEnd`, `UserPromptSubmit`, and `Stop` for parent-task lifecycle visibility and makes `status`, `doctor`, and the empty UI distinguish monitor health from hook delivery. In a real E2E after restarting official Codex app `26.727.40816` (`build 6067`) with plugin `0.2.1` installed and enabled, three parent sessions and three subagents appeared automatically without pre-registering task IDs. Real `SessionStart`, `UserPromptSubmit`, `Stop`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, and `PermissionRequest` hooks reached the sender, loopback monitor, and UI. `SessionEnd` is wired but has not yet been observed from the real official app, so compatibility for that event is not claimed.
 
 Maintainer npm 2FA is enabled in `auth-and-writes` mode, and `codex-agent-view@0.2.0` is available from the public npm registry. npm publication remains separate from Universal Plugins Directory submission; the plugin is not directory-searchable.
 
+Verified `0.2.0` release: npm `gitHead` and the annotated `v0.2.0` tag both resolve to commit `00b62af56698ac875e39c7d1386905c157c3a7e8`; the registry SRI/signature and all 21 package files against the tagged source were verified. [GitHub Release v0.2.0](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.2.0) is public. A separate npm provenance attestation is optional and was not published for this release.
+
 ### Boundaries
 
-Codex Agent View is a live companion, not a historical audit or session-replay product. Bounded in-memory state and reset-on-restart semantics are the intentional completed `0.2.0` design: they keep privacy and failure boundaries small. SQLite or persistent history is not a missing requirement. Consider it only as a separate explicit opt-in feature if demonstrated user demand justifies retention, migration, deletion, and privacy costs.
+Codex Agent View is a live companion, not a historical audit or session-replay product. Bounded in-memory state and reset-on-restart semantics are intentional: they keep privacy and failure boundaries small. SQLite or persistent history is not a missing requirement. Consider it only as a separate explicit opt-in feature if demonstrated user demand justifies retention, migration, deletion, and privacy costs.
 
 - Hooks are the source of truth for live state.
 - Operational state exists by design only in bounded process memory; restart begins a new observation window.
@@ -230,6 +256,14 @@ Codex Agent View is a live companion, not a historical audit or session-replay p
 - The product cannot stop or restart tasks/subagents, send messages, or approve/deny permissions.
 - Missing, duplicated, or out-of-order events remain visible as empty, unknown, or degraded state instead of being guessed away.
 
+A separately launched Codex `0.146` App Server `thread/list` fallback was also tested. It reported both the current root and subagents as `notLoaded`, so it did not share the official app's live running/completed state. Persisted parent IDs, aliases, and depth could enrich metadata, but the fallback could not determine live status and would add state-database reads, privacy surface, and complexity. It is therefore not included in `0.2.1`.
+
+### Why npm, a local browser UI, and the Plugins Directory are different
+
+- npm distributes the local `codex-agent-view` executable, hook sender, runtime, and static UI to the user's machine.
+- The browser renders the current read-only companion UI on `127.0.0.1`; it is not an external website or telemetry dashboard.
+- The Universal Plugins Directory does not replace npm. A public in-app custom UI path requires a public HTTPS MCP server and domain verification, which conflicts with this project's local-only, no-external-server boundary. Only a separate listing/skills submission remains under consideration; do not expect Directory search installation until review and publication actually finish.
+
 ### Requirements and tested versions
 
 - Node.js `>=18`
@@ -238,7 +272,7 @@ Codex Agent View is a live companion, not a historical audit or session-replay p
 
 | Runtime | Tested version | Scope |
 | --- | --- | --- |
-| Official Codex app | `26.727.40816` (`build 6067`) | bundle metadata; current GUI-task E2E pending |
+| Official Codex app | `26.727.40816` (`build 6067`) | real E2E after restart with plugin `0.2.1`: three parents and three subagents appeared automatically and eight real hook types reached the UI; `SessionEnd` unobserved |
 | App-embedded Codex | `0.146.0-alpha.9.2` | isolated install/runtime and lifecycle probe |
 | Homebrew Codex CLI | `0.146.0` | isolated install/runtime probe |
 
@@ -258,7 +292,7 @@ node bin/codex-agent-view.mjs install
 
 There are no production dependencies; the runtime uses Node.js built-ins. `install` explicitly copies the package into a local marketplace under the runtime directory and registers `codex-agent-view@codex-agent-view`. No `postinstall` script changes Codex settings.
 
-Review the installed plugin and `hooks/hooks.json`, inspect the `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command, explicitly trust the current hook hash, restart the official app, and create a new task.
+Review the installed plugin and `hooks/hooks.json`, inspect the `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command, and explicitly trust the current hook hash. If the app was open before installation, quit it completely and reopen it. Create the test task only after enablement and trust; earlier events are not replayed.
 
 Start the foreground monitor:
 
@@ -273,14 +307,18 @@ node bin/codex-agent-view.mjs status --json
 node bin/codex-agent-view.mjs doctor --json
 ```
 
+`doctor` checks installation, enablement, the installed hook bundle, monitor health, and whether any hook event reached the monitor. Hook trust can remain `unknown`: `codex plugin list --json` does not expose persisted exact-hook trust, so inspect it interactively in Codex CLI `/hooks`.
+
 An empty session list means that this monitor observed no events. It does not prove that Codex has no running task. Stopping or restarting the monitor discards its in-memory state, and downtime events are not replayed.
 
+Once the monitor is running and plugin enablement/trust is complete, hooks from newly created or resumed tasks appear automatically without pre-registering a task ID. Search is only an optional filter over that automatically received list; it does not start tracking or register a task. Events that occurred before installation/trust or while the monitor was down are not replayed.
+
 ### Install from npm
 
-Install the public exact version globally:
+The recommended installation for the `0.2.1` release is the exact global version below. At the time of writing, the public registry version confirmed by this document is still `0.2.0`; validate from this repository source until the `0.2.1` publication is confirmed.
 
 ```bash
-npm install --global codex-agent-view@0.2.0
+npm install --global codex-agent-view@0.2.1
 codex-agent-view doctor
 codex-agent-view install
 codex-agent-view start
@@ -289,13 +327,25 @@ codex-agent-view start
 Or run the exact version without a global install:
 
 ```bash
-npx --yes codex-agent-view@0.2.0 doctor
-npx --yes codex-agent-view@0.2.0 install
-npx --yes codex-agent-view@0.2.0 start
+npx --yes codex-agent-view@0.2.1 doctor
+npx --yes codex-agent-view@0.2.1 install
+npx --yes codex-agent-view@0.2.1 start
 ```
 
+That public-artifact evidence applies to `0.2.0`: isolated global and exact-version `npx` CLI lifecycles passed, and fixture events reached status/UI. A later already-running official-app process reproduced zero delivered events. Separate `0.2.1` source/package QA and a restarted official-app E2E confirmed eight real hook types and automatic listing without task-ID registration. The `0.2.1` registry artifact, digest, tag, and GitHub Release still require separate post-publication verification, and a real `SessionEnd` remains unobserved. See [Distribution](docs/distribution.md) for the registry evidence and verification boundary.
+
 npm installation does not modify Codex settings automatically. The explicit `install` command performs local plugin registration and leaves hook trust to the user. npm publication and Universal Plugins Directory submission are separate. See [Distribution](docs/distribution.md) and [Plugin submission](docs/plugin-submission.md).
 
+### Troubleshooting an empty monitor
+
+1. Run `codex-agent-view doctor --json` and check plugin `installed`, `enabled`, hook `wiring_ok`, and monitor `ok`.
+2. If `monitor.events_received` is `false`, do not confuse monitor connectivity with successful hook delivery.
+3. In interactive Codex CLI `/hooks`, review and trust the exact current `send-hook.mjs` definition.
+4. Fully quit and reopen an official app process that was running before plugin installation.
+5. Create a new task after enablement/trust, then run a parent prompt and a subagent.
+
+If events are still absent, report the Codex app/CLI version, plugin version, app-versus-CLI runtime, and redacted `doctor` diagnostic codes. Never share the runtime token or a raw payload.
+
 ### Privacy
 
 The normal hook path uses `scripts/send-hook.mjs`. It minimizes the local Codex payload before loopback delivery, and the reducer retains only a narrower state schema in memory. The normal monitor does not write an event JSONL history.

package/bin/codex-agent-view.mjs

@@ -172,32 +172,172 @@ async function status(args) {
     0,
   );
   process.stdout.write(`${sessions.length} task(s), ${agents} subagent(s) observed.\n`);
+  if (!Number.isFinite(snapshot.updated_at_ms) || snapshot.updated_at_ms <= 0) {
+    process.stdout.write(
+      "No hook event has reached this monitor yet. The monitor can be healthy while Codex skips an untrusted or not-yet-loaded hook. Run `codex-agent-view doctor`, review `/hooks` in Codex CLI, then use a new task.\n",
+    );
+  }
   for (const session of sessions) {
     process.stdout.write(`- ${session.session_id}: ${session.status} (${session.agents.length} agents)\n`);
   }
 }
 
+function parsePluginList(result) {
+  if (result.code !== 0) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return Array.isArray(parsed.installed) ? parsed.installed : [];
+  } catch {
+    return null;
+  }
+}
+
+async function inspectInstalledHookBundle(pluginEntry) {
+  const sourcePath = pluginEntry?.source?.path;
+  if (typeof sourcePath !== "string" || sourcePath.length === 0) {
+    return {
+      hooks_file: false,
+      sender_file: false,
+      source_path: null,
+      wiring_ok: false,
+    };
+  }
+  const hooksPath = join(sourcePath, "hooks", "hooks.json");
+  const senderPath = join(sourcePath, "scripts", "send-hook.mjs");
+  const hooks = await readJsonRegularFile(hooksPath);
+  const sender = await pathExists(senderPath);
+  const hookGroups = hooks?.hooks;
+  const expectedEvents = [
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "Stop",
+    "SubagentStart",
+    "SubagentStop",
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionRequest",
+  ];
+  const hooksFile = hookGroups && typeof hookGroups === "object";
+  const declaredEvents = hooksFile
+    ? expectedEvents.filter((event) => Array.isArray(hookGroups[event]))
+    : [];
+  return {
+    declared_events: declaredEvents,
+    hooks_file: Boolean(hooksFile),
+    sender_file: Boolean(sender?.isFile() && !sender.isSymbolicLink()),
+    source_path: sourcePath,
+    wiring_ok:
+      Boolean(hooksFile) &&
+      declaredEvents.length === expectedEvents.length &&
+      Boolean(sender?.isFile() && !sender.isSymbolicLink()),
+  };
+}
+
 async function doctor(args) {
   const codex = await run("codex", ["--version"], { allowFailure: true });
   let monitor = { ok: false, message: "not running" };
   try {
     const snapshot = await fetchState();
-    monitor = { ok: true, sessions: snapshot.sessions?.length || 0 };
+    monitor = {
+      events_received:
+        Number.isFinite(snapshot.updated_at_ms) && snapshot.updated_at_ms > 0,
+      ok: true,
+      sessions: snapshot.sessions?.length || 0,
+      updated_at_ms:
+        Number.isFinite(snapshot.updated_at_ms) && snapshot.updated_at_ms > 0
+          ? snapshot.updated_at_ms
+          : null,
+    };
   } catch (error) {
     monitor = { ok: false, message: error.message };
   }
   const plugins = await run("codex", ["plugin", "list", "--json"], {
     allowFailure: true,
   });
-  let installed = false;
-  try {
-    const parsed = JSON.parse(plugins.stdout);
-    installed = parsed.installed?.some((entry) => entry.pluginId === PLUGIN_ID) || false;
-  } catch {}
+  const pluginList = parsePluginList(plugins);
+  const pluginEntry = pluginList?.find((entry) => entry.pluginId === PLUGIN_ID) || null;
+  const hookBundle = await inspectInstalledHookBundle(pluginEntry);
+  const diagnostics = [];
+  if (codex.code !== 0) {
+    diagnostics.push({
+      action: "Install or repair Codex CLI so `codex --version` succeeds.",
+      code: "codex_cli_unavailable",
+      severity: "error",
+    });
+  }
+  if (pluginList === null) {
+    diagnostics.push({
+      action: "Check `codex plugin list --json` and the installed Codex CLI version.",
+      code: "plugin_list_unavailable",
+      severity: "error",
+    });
+  } else if (!pluginEntry) {
+    diagnostics.push({
+      action: "Run `codex-agent-view install`.",
+      code: "plugin_not_installed",
+      severity: "error",
+    });
+  } else if (pluginEntry.enabled !== true) {
+    diagnostics.push({
+      action: "Enable Codex Agent View in the Codex plugin browser, then start a new task.",
+      code: "plugin_disabled",
+      severity: "error",
+    });
+  }
+  if (pluginEntry && !hookBundle.wiring_ok) {
+    diagnostics.push({
+      action: "Run `codex-agent-view install` again to restore the owned plugin bundle.",
+      code: "hook_bundle_invalid",
+      severity: "error",
+    });
+  }
+  if (pluginEntry && pluginEntry.version !== (await packageVersion())) {
+    diagnostics.push({
+      action: "Run `codex-agent-view install` to align the installed plugin with this CLI package.",
+      code: "plugin_version_mismatch",
+      severity: "warning",
+    });
+  }
+  if (!monitor.ok) {
+    diagnostics.push({
+      action: "Run `codex-agent-view start` before expecting live task events.",
+      code: "monitor_not_running",
+      severity: "warning",
+    });
+  }
+  if (pluginEntry) {
+    diagnostics.push({
+      action: "Review the current plugin hook definition in interactive Codex CLI `/hooks`.",
+      code: "hook_trust_unverified",
+      severity: "info",
+    });
+  }
+  if (monitor.ok && monitor.events_received === false) {
+    diagnostics.push({
+      action:
+        "Open Codex CLI, review and trust the current definition in `/hooks`, then start a new task. Restart a Codex app process that was already open during installation.",
+      code: "no_hook_events_observed",
+      severity: "warning",
+    });
+  }
   const report = {
     codex: { ok: codex.code === 0, version: codex.stdout.trim() || null },
+    diagnostics,
+    hook: {
+      ...hookBundle,
+      trust: pluginEntry ? "unknown" : "not_applicable",
+      trust_note: pluginEntry
+        ? "Codex CLI does not expose persisted hook trust through `plugin list --json`; review `/hooks` interactively."
+        : null,
+    },
     monitor,
-    plugin: { installed },
+    plugin: {
+      enabled: pluginEntry?.enabled === true,
+      installed: Boolean(pluginEntry),
+      source_path: pluginEntry?.source?.path || null,
+      version: pluginEntry?.version || null,
+    },
     runtime_directory: runtimeDirectory(),
   };
   if (args.includes("--json")) {
@@ -205,8 +345,20 @@ async function doctor(args) {
     return;
   }
   process.stdout.write(`Codex CLI: ${report.codex.ok ? report.codex.version : "not available"}\n`);
-  process.stdout.write(`Plugin: ${installed ? "installed" : "not installed"}\n`);
+  process.stdout.write(
+    `Plugin: ${report.plugin.installed ? `installed (${report.plugin.enabled ? "enabled" : "disabled"})` : "not installed"}\n`,
+  );
+  if (report.plugin.installed) {
+    process.stdout.write(`Hook bundle: ${report.hook.wiring_ok ? "valid" : "invalid"}\n`);
+    process.stdout.write("Hook trust: unknown (Codex exposes review through interactive `/hooks`)\n");
+  }
   process.stdout.write(`Monitor: ${monitor.ok ? "running" : monitor.message}\n`);
+  if (monitor.ok) {
+    process.stdout.write(`Hook events: ${monitor.events_received ? "observed" : "none observed"}\n`);
+  }
+  for (const diagnostic of diagnostics) {
+    process.stdout.write(`[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.action}\n`);
+  }
 }
 
 async function pathExists(path) {
@@ -362,8 +514,30 @@ async function install() {
     await run("codex", ["plugin", "marketplace", "add", destination, "--json"]);
   }
   await run("codex", ["plugin", "add", PLUGIN_ID, "--json"]);
+  const verification = await run("codex", ["plugin", "list", "--json"], {
+    allowFailure: true,
+  });
+  const installed = parsePluginList(verification)?.find(
+    (entry) => entry.pluginId === PLUGIN_ID,
+  );
+  if (!installed) {
+    throw new Error(
+      "Codex did not report the plugin as installed after registration; run `codex-agent-view doctor` for details",
+    );
+  }
+  if (installed.enabled !== true) {
+    throw new Error(
+      "the plugin was registered but is disabled; enable it in the Codex plugin browser, then run `codex-agent-view doctor`",
+    );
+  }
   process.stdout.write(`Installed ${PLUGIN_ID} from ${destination}.\n`);
-  process.stdout.write("Review and trust the hook in the CLI /hooks screen, restart Codex, then start a new task.\n");
+  process.stdout.write("Registration verified: installed and enabled.\n");
+  process.stdout.write(
+    "Hook trust cannot be granted or inspected non-interactively. Review and trust this plugin's current hook definition in Codex CLI `/hooks`.\n",
+  );
+  process.stdout.write(
+    "If Codex was already open during installation, restart it completely, then create a new task.\n",
+  );
 }
 
 function isBroadRuntimeRoot(root) {

package/hooks/hooks.json

@@ -1,6 +1,50 @@
 {
   "description": "Capture privacy-minimized Codex lifecycle payloads for the local companion monitor.",
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "SubagentStart": [
       {
         "hooks": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Local read-only companion monitor for Codex parent tasks and subagents.",
   "type": "module",
   "main": "./src/core/index.mjs",

package/public/app.js

@@ -65,6 +65,7 @@ const elements = Object.freeze({
 const viewState = {
   updatedAtMs: null,
   sessions: [],
+  diagnostics: [],
   hasLoaded: false,
   errorMessage: "",
   canRetry: true,
@@ -130,10 +131,22 @@ function normalizeActivity(value) {
   };
 }
 
+function normalizeDiagnostic(value) {
+  const diagnostic = isRecord(value) ? value : {};
+  return {
+    code: safeString(diagnostic.code, "unknown_diagnostic"),
+    diagnosedAtMs: safeTimestamp(diagnostic.diagnosed_at_ms),
+  };
+}
+
 function deriveSessionStatus(session, agents, recentActivities) {
   if (session.permission?.status === "waiting_for_user") {
     return "waiting";
   }
+  const reportedStatus = normalizeCoreStatus(session.status);
+  if (reportedStatus === "running" || reportedStatus === "completed") {
+    return reportedStatus;
+  }
   if (
     agents.some((agent) => agent.status === "running") ||
     recentActivities[0]?.status === "running"
@@ -166,7 +179,8 @@ function normalizeState(value) {
     !isRecord(value) ||
     value.schema_version !== 1 ||
     value.source_of_truth !== "hook" ||
-    !Array.isArray(value.sessions)
+    !Array.isArray(value.sessions) ||
+    !Array.isArray(value.diagnostics)
   ) {
     throw new TypeError("상태 응답 형식이 올바르지 않습니다.");
   }
@@ -174,6 +188,7 @@ function normalizeState(value) {
   return {
     updatedAtMs: safeTimestamp(value.updated_at_ms),
     sessions: value.sessions.map(normalizeSession),
+    diagnostics: value.diagnostics.map(normalizeDiagnostic),
   };
 }
 
@@ -462,7 +477,7 @@ function renderMetrics() {
   elements.metricWaiting.textContent = String(waitingCount);
   elements.metricCompleted.textContent = String(countStatus("completed"));
   elements.lastUpdated.textContent = !viewState.updatedAtMs
-    ? "시간 정보 없음"
+    ? "수신된 hook 없음"
     : formatDateTime(viewState.updatedAtMs);
 }
 
@@ -486,10 +501,77 @@ function setStateMessage(kind, title, description, includeRetry = false) {
   }
 }
 
+function setEmptyObservationMessage() {
+  elements.stateMessage.className = "state-message state-empty state-empty-observation";
+  elements.stateMessage.replaceChildren();
+
+  const heading = document.createElement("strong");
+  const copy = document.createElement("span");
+
+  if (viewState.diagnostics.length) {
+    heading.textContent = "표시 가능한 task가 없습니다.";
+    copy.textContent = `Monitor가 hook 입력 ${viewState.diagnostics.length}건을 받았지만 유효한 session으로 적용하지 않았습니다.`;
+  } else {
+    heading.textContent = "이 관찰 창에서 수신된 hook event가 0건입니다.";
+    copy.textContent = "로컬 monitor 연결은 정상입니다. 이 결과만으로 Codex에 실행 중인 task나 agent가 없다고 판단할 수 없습니다.";
+  }
+
+  const guidance = document.createElement("div");
+  guidance.className = "empty-guidance";
+
+  const guidanceTitle = document.createElement("h3");
+  guidanceTitle.textContent = "표시되지 않을 때 확인 순서";
+
+  const automaticTracking = document.createElement("p");
+  automaticTracking.className = "automatic-tracking";
+  automaticTracking.textContent = "task ID를 입력하거나 task별로 등록할 필요가 없습니다. Trusted hook event가 자동으로 이 목록에 추가됩니다.";
+
+  const steps = document.createElement("ol");
+  for (const step of [
+    "Codex Agent View를 실행한 뒤 새 Codex task를 시작합니다.",
+    "설치된 plugin의 현재 hook command를 검토하고 직접 trust했는지 확인합니다.",
+    "plugin 설치 또는 hook trust 변경 후 공식 Codex 앱을 완전히 재시작하고 새 task에서 subagent를 실행합니다.",
+  ]) {
+    const item = document.createElement("li");
+    item.textContent = step;
+    steps.append(item);
+  }
+
+  const boundary = document.createElement("p");
+  boundary.className = "observation-boundary";
+  boundary.textContent = "Plugin 설치·trust 전에 이미 지나간 event와 monitor가 꺼져 있던 동안의 event는 재생되지 않습니다.";
+
+  guidance.append(guidanceTitle, automaticTracking, steps, boundary);
+
+  if (viewState.diagnostics.length) {
+    const diagnostics = document.createElement("details");
+    diagnostics.className = "diagnostic-details";
+    const summary = document.createElement("summary");
+    summary.textContent = `검증 diagnostic ${viewState.diagnostics.length}건`;
+    const codes = document.createElement("ul");
+    const diagnosticCounts = new Map();
+    for (const { code } of viewState.diagnostics) {
+      diagnosticCounts.set(code, (diagnosticCounts.get(code) ?? 0) + 1);
+    }
+    for (const [diagnosticCode, count] of diagnosticCounts) {
+      const item = document.createElement("li");
+      const code = document.createElement("code");
+      code.textContent = diagnosticCode;
+      item.append(code, ` · ${count}건`);
+      codes.append(item);
+    }
+    diagnostics.append(summary, codes);
+    guidance.append(diagnostics);
+  }
+
+  elements.stateMessage.append(heading, copy, guidance);
+}
+
 function renderSessions() {
   const visibleSessions = filteredSessions();
   const hasFilters = elements.search.value.trim() || elements.statusFilter.value !== "all";
 
+  elements.toolbar.hidden = viewState.sessions.length === 0;
   elements.stateMessage.hidden = false;
 
   elements.sessionList.replaceChildren();
@@ -523,11 +605,7 @@ function renderSessions() {
 
   if (!viewState.sessions.length) {
     elements.sessionList.hidden = true;
-    setStateMessage(
-      "empty",
-      "아직 관찰된 task가 없습니다.",
-      "Codex에서 task나 subagent가 시작되면 이곳에 나타납니다.",
-    );
+    setEmptyObservationMessage();
     return;
   }
 
@@ -597,6 +675,7 @@ async function refreshState() {
     const nextState = normalizeState(await response.json());
     viewState.updatedAtMs = nextState.updatedAtMs;
     viewState.sessions = nextState.sessions;
+    viewState.diagnostics = nextState.diagnostics;
     viewState.hasLoaded = true;
     viewState.errorMessage = "";
     viewState.canRetry = true;

package/public/index.html

@@ -95,20 +95,25 @@
             </p>
           </div>
 
-          <form class="toolbar" role="search" aria-label="task와 subagent 검색 및 필터">
+          <form
+            class="toolbar"
+            role="search"
+            aria-label="자동 수신된 task와 subagent 목록 필터"
+            hidden
+          >
             <div class="field field-search">
-              <label for="session-search">검색</label>
+              <label for="session-search">목록 필터 (선택)</label>
               <input
                 id="session-search"
                 name="query"
                 type="search"
-                placeholder="Session ID, agent ID, 유형 또는 event"
+                placeholder="자동 수신된 task·agent 목록에서 찾기"
                 autocomplete="off"
                 spellcheck="false"
               >
             </div>
             <div class="field">
-              <label for="status-filter">상태</label>
+              <label for="status-filter">상태 필터 (선택)</label>
               <select id="status-filter" name="status">
                 <option value="all">모든 상태</option>
                 <option value="running">실행 중</option>

package/public/styles.css

@@ -362,6 +362,10 @@ h1 {
   gap: var(--space-3);
 }
 
+.toolbar[hidden] {
+  display: none;
+}
+
 .field {
   display: grid;
   gap: var(--space-2);
@@ -425,6 +429,74 @@ h1 {
   color: var(--text-secondary);
 }
 
+.state-empty-observation {
+  justify-items: stretch;
+  text-align: left;
+}
+
+.state-empty-observation > strong,
+.state-empty-observation > span {
+  justify-self: center;
+  text-align: center;
+}
+
+.empty-guidance {
+  width: min(42rem, 100%);
+  margin-top: var(--space-5);
+  padding: var(--space-4);
+  background: var(--surface-raised);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+}
+
+.empty-guidance h3 {
+  margin-bottom: var(--space-3);
+  font-size: var(--text-sm);
+}
+
+.automatic-tracking {
+  margin-bottom: var(--space-3);
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+}
+
+.empty-guidance ol {
+  margin: 0;
+  padding-left: 1.25rem;
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+}
+
+.empty-guidance li + li {
+  margin-top: var(--space-2);
+}
+
+.observation-boundary {
+  margin: var(--space-4) 0 0;
+  padding-top: var(--space-3);
+  color: var(--text-muted);
+  border-top: 1px solid var(--border-default);
+  font-size: var(--text-xs);
+}
+
+.diagnostic-details {
+  margin-top: var(--space-3);
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+}
+
+.diagnostic-details summary {
+  min-height: 2.75rem;
+  padding: var(--space-2) 0;
+  cursor: pointer;
+  font-weight: 700;
+}
+
+.diagnostic-details ul {
+  margin: 0;
+  padding-left: 1.25rem;
+}
+
 .state-message.state-error {
   background: var(--danger-soft);
   border-color: color-mix(in srgb, var(--danger) 40%, transparent);

package/src/core/monitor-store.mjs

@@ -21,6 +21,20 @@ function createSession(event) {
     last_seen_at_ms: event.received_at_ms,
     agents: new Map(),
     tools: new Map(),
+    lifecycle: {
+      start_observed: false,
+      end_observed: false,
+      started_at_ms: null,
+      ended_at_ms: null,
+      has_out_of_order_events: false,
+    },
+    root_turn: {
+      status: "idle",
+      turn_id: null,
+      started_at_ms: null,
+      stopped_at_ms: null,
+      has_out_of_order_events: false,
+    },
     permission: { status: "idle" },
     recent_activities: [],
   };
@@ -31,11 +45,15 @@ function deriveSessionStatus(session) {
     return "waiting_for_user";
   }
   if (
+    session.root_turn.status === "running" ||
     [...session.agents.values()].some(({ status }) => status === "running") ||
     [...session.tools.values()].some(({ status }) => status === "running")
   ) {
     return "running";
   }
+  if (session.lifecycle.end_observed) {
+    return "completed";
+  }
   return "observed";
 }
 
@@ -54,11 +72,10 @@ function addActivity(session, event, status, limit) {
   const activity = {
     type: event.type,
     status,
-    turn_id: event.turn_id,
     received_at_ms: event.received_at_ms,
   };
 
-  for (const field of ["agent_id", "agent_type", "tool_name", "tool_use_id"]) {
+  for (const field of ["turn_id", "agent_id", "agent_type", "tool_name", "tool_use_id"]) {
     if (field in event) {
       activity[field] = event[field];
     }
@@ -70,6 +87,71 @@ function addActivity(session, event, status, limit) {
   }
 }
 
+function applySessionEvent(session, event, limits) {
+  const lifecycle = session.lifecycle;
+  if (event.type === "session_started") {
+    const resumedAfterEnd = lifecycle.end_observed;
+    lifecycle.start_observed = true;
+    lifecycle.started_at_ms ??= event.received_at_ms;
+    lifecycle.end_observed = false;
+    lifecycle.ended_at_ms = null;
+    lifecycle.has_out_of_order_events ||= resumedAfterEnd;
+    addActivity(session, event, "observed", limits.maxActivitiesPerSession);
+    return "applied";
+  }
+
+  if (lifecycle.end_observed) {
+    return "duplicate";
+  }
+  lifecycle.end_observed = true;
+  lifecycle.ended_at_ms = event.received_at_ms;
+  lifecycle.has_out_of_order_events = !lifecycle.start_observed;
+  session.root_turn.status = "completed";
+  session.root_turn.stopped_at_ms ??= event.received_at_ms;
+  session.permission = { status: "idle" };
+  addActivity(session, event, "completed", limits.maxActivitiesPerSession);
+  return "applied";
+}
+
+function applyTurnEvent(session, event, limits) {
+  const turn = session.root_turn;
+  if (event.type === "turn_started") {
+    if (turn.turn_id === event.turn_id && turn.status === "running") {
+      return "duplicate";
+    }
+    session.root_turn = {
+      status: "running",
+      turn_id: event.turn_id,
+      started_at_ms: event.received_at_ms,
+      stopped_at_ms: null,
+      has_out_of_order_events: false,
+    };
+    session.permission = { status: "idle" };
+    addActivity(session, event, "running", limits.maxActivitiesPerSession);
+    return "applied";
+  }
+
+  if (turn.turn_id === event.turn_id && turn.status === "completed") {
+    return "duplicate";
+  }
+  const startObserved = turn.turn_id === event.turn_id && turn.started_at_ms !== null;
+  session.root_turn = {
+    status: "completed",
+    turn_id: event.turn_id,
+    started_at_ms: startObserved ? turn.started_at_ms : null,
+    stopped_at_ms: event.received_at_ms,
+    has_out_of_order_events: !startObserved,
+  };
+  session.permission = { status: "idle" };
+  addActivity(
+    session,
+    event,
+    startObserved ? "completed" : "completed_without_start",
+    limits.maxActivitiesPerSession,
+  );
+  return "applied";
+}
+
 function applySubagentEvent(session, event, limits) {
   let agent = session.agents.get(event.agent_id);
   if (!agent) {
@@ -212,6 +294,12 @@ function applyPermissionEvent(session, event, limits) {
 }
 
 function applyEvent(session, event, limits) {
+  if (event.type === "session_started" || event.type === "session_ended") {
+    return applySessionEvent(session, event, limits);
+  }
+  if (event.type === "turn_started" || event.type === "turn_stopped") {
+    return applyTurnEvent(session, event, limits);
+  }
   if (event.type === "subagent_started" || event.type === "subagent_stopped") {
     return applySubagentEvent(session, event, limits);
   }
@@ -230,6 +318,7 @@ function snapshotSession(session) {
     agents: [...session.agents.values()]
       .map(({ start_observed, stop_observed, ...agent }) => ({ ...agent }))
       .sort((left, right) => right.last_seen_at_ms - left.last_seen_at_ms),
+    root_turn: { ...session.root_turn },
     recent_activities: session.recent_activities.map((activity) => ({
       ...activity,
     })),

package/src/core/normalize-hook-payload.mjs

@@ -2,10 +2,16 @@ const NORMALIZED_EVENT_TYPES = Object.freeze({
   PermissionRequest: "permission_requested",
   PostToolUse: "tool_completed",
   PreToolUse: "tool_started",
+  SessionEnd: "session_ended",
+  SessionStart: "session_started",
+  Stop: "turn_stopped",
   SubagentStart: "subagent_started",
   SubagentStop: "subagent_stopped",
+  UserPromptSubmit: "turn_started",
 });
 
+const SESSION_EVENT_TYPES = new Set(["session_started", "session_ended"]);
+
 const MAX_IDENTIFIER_LENGTH = 512;
 const MAX_LABEL_LENGTH = 256;
 
@@ -58,8 +64,8 @@ function commonEvent(payload, type, receivedAtMs) {
     source: "hook",
     type,
     session_id: payload.session_id,
-    turn_id: payload.turn_id,
     received_at_ms: receivedAtMs,
+    ...(typeof payload.turn_id === "string" ? { turn_id: payload.turn_id } : {}),
   };
 }
 
@@ -88,7 +94,10 @@ export function normalizeHookPayload(payload, options = {}) {
     return ignored("unsupported_hook_event", receivedAtMs, "hook_event_name");
   }
 
-  for (const field of ["session_id", "turn_id"]) {
+  const commonFields = SESSION_EVENT_TYPES.has(type)
+    ? ["session_id"]
+    : ["session_id", "turn_id"];
+  for (const field of commonFields) {
     const error = requiredString(payload, field, receivedAtMs);
     if (error) {
       return error;
@@ -143,4 +152,3 @@ export function normalizeHookPayload(payload, options = {}) {
 
   return { status: "accepted", event };
 }
-