codex-agent-view 0.5.5 → 0.5.6

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "A read-only Codex plugin for monitoring live tasks and subagents in your browser. Open each view with one lightweight @codex-agent-view invocation. Once open, live monitoring runs locally with no additional model calls.",
   "author": {
     "name": "Junho Yoon",

package/README.ko.md

@@ -13,19 +13,36 @@ Codex를 대체하거나 작업·에이전트를 제어하지 않으며, 외부
 일반 터미널에서 현재 릴리스를 설치합니다.
 
 ```bash
-npm install --global codex-agent-view@0.5.5
+codex --version
+```
+
+PATH에서 선택되는 `codex` executable을 npm으로 설치했다면 다음과 같이 업데이트한 뒤 선택된 version을 다시 확인합니다.
+
+```bash
+npm install --global @openai/codex@latest
+codex --version
+```
+
+Codex를 다른 install channel로 설치했다면 그 channel에서 업데이트하세요. 그다음 plugin package를 설치합니다.
+
+```bash
+npm install --global codex-agent-view@0.5.6
 codex-agent-view install
 ```
 
-첫 번째 명령은 npm package를 설치하고, 두 번째 명령은 포함된 local Codex plugin을 명시적으로 등록합니다. `npm install`만으로는 Codex 설정을 바꾸지 않으며, 이 package에는 설정을 자동 변경하는 `postinstall` script가 없습니다.
+`0.5.6` installer는 등록 전에 포함된 plugin을 marketplace의 strict subdirectory로 복사하여 `0.5.5`의 marketplace-root discovery 실패를 피합니다.
+
+npm 명령은 package를 설치합니다. `codex-agent-view install`은 포함된 local Codex plugin을 복사하고 명시적으로 등록합니다. `npm install`만으로는 Codex 설정을 바꾸지 않으며, 이 package에는 설정을 자동 변경하는 `postinstall` script가 없습니다.
 
 설치 후에는 다음 순서를 따릅니다.
 
-1. 설치 중 Codex 앱이 열려 있었다면 완전히 종료한 뒤 다시 엽니다.
-2. Codex 앱의 **Plugins** 화면에서 **Codex Agent View**가 설치·활성화됐는지 확인합니다.
-3. Hook 검토 화면이 나오면 `hooks/hooks.json`과 `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` 명령을 확인하고 현재 정의를 명시적으로 trust합니다. 앱이 hook 검토 화면을 제공하지 않을 때만 설치 과정에서 interactive Codex CLI의 `/hooks`를 사용합니다.
+1. Codex 앱의 **Plugins** 화면에서 **Codex Agent View**가 설치·활성화됐는지 확인합니다.
+2. **Hooks** 영역에서 **검토(Review)**를 선택해 `hooks/hooks.json`과 `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` 명령을 확인한 뒤, 현재 정의에 **모두 신뢰하기(Trust all)**를 선택합니다. 앱에 Hook 검토 UI가 없을 때만 interactive Codex CLI의 `/hooks`를 사용합니다.
+3. Codex 앱을 완전히 종료한 뒤 다시 엽니다.
 4. Codex 앱에서 새 작업을 만듭니다. 설치 전에 지나간 event는 재생되지 않습니다.
 
+현재 programmatic plugin status에는 저장된 Hook 신뢰 상태가 노출되지 않으므로 browser와 `doctor`는 승인 여부를 확인할 수 없습니다. Codex 앱이나 interactive `/hooks` UI에서 직접 확인하세요.
+
 ## 사용
 
 Codex 앱의 작업 입력창에서 다음 plugin을 선택해 그대로 전송합니다.
@@ -40,6 +57,7 @@ Codex 앱의 작업 입력창에서 다음 plugin을 선택해 그대로 전송
 - 터미널에서 monitor를 시작하지 않습니다.
 - localhost 주소를 복사하거나 관리하지 않습니다.
 - 브라우저 탭을 닫아도 Codex 작업은 중단되지 않습니다. 새 인증 탭이 필요하면 `@codex-agent-view`를 다시 실행합니다.
+- Viewer를 연 작업 자체는 화면에서 숨겨지므로, 확인하려는 작업과 별도의 viewer 작업에서 실행합니다.
 
 공개 Codex plugin API는 이 흐름을 위한 앱 sidebar나 in-app panel 자동 생성을 안정적으로 제공하지 않으므로, 운영체제 기본 브라우저가 지원하는 표시 화면입니다.
 
@@ -94,7 +112,7 @@ codex-agent-view uninstall --purge
 
 ## 릴리스 및 프로젝트 문서
 
-Registry digest, exact reinstall, CI, tag와 GitHub Release를 포함한 공개·검증 증거는 변경할 수 없는 npm package README 밖의 [배포 문서](docs/distribution.md)에 기록합니다.
+Registry digest, 이 기기의 compatible-CLI reinstall, CI, tag와 GitHub Release를 포함한 공개·검증 증거는 변경할 수 없는 npm package README 밖의 [배포 문서](docs/distribution.md)에 기록합니다. 이 검증은 clean cross-device first install을 확인하지 않았으며, 위 호환성 실패는 별도 사실로 기록합니다.
 
 npm 공개와 Universal Plugins Directory 제출은 별도 절차입니다. Directory validator 호환성, portal/reviewer acceptance, 검색 노출과 promptless plugin-card Quick start 동작은 아직 확인하지 않았으며 이 문서에서 지원을 주장하지 않습니다.
 

package/README.md

@@ -13,19 +13,36 @@ It does not replace Codex, control tasks or agents, run a hosted service, send t
 Install the current release from a regular terminal:
 
 ```bash
-npm install --global codex-agent-view@0.5.5
+codex --version
+```
+
+If the `codex` executable on your PATH was installed through npm, update it and verify the selected version again:
+
+```bash
+npm install --global @openai/codex@latest
+codex --version
+```
+
+If Codex came from another install channel, update it through that channel instead. Then install the plugin package:
+
+```bash
+npm install --global codex-agent-view@0.5.6
 codex-agent-view install
 ```
 
-The first command installs the npm package. The second explicitly registers its bundled local Codex plugin. `npm install` alone does not modify Codex settings, and this package has no `postinstall` script that does so.
+The `0.5.6` installer copies the bundled plugin into a strict marketplace subdirectory before registration, avoiding the marketplace-root discovery failure in `0.5.5`.
+
+The npm command installs the package. `codex-agent-view install` copies and explicitly registers its bundled local Codex plugin. `npm install` alone does not modify Codex settings, and this package has no `postinstall` script that does so.
 
 Then:
 
-1. If Codex was open during installation, quit it completely and reopen it.
-2. In the Codex app's **Plugins** screen, confirm that **Codex Agent View** is installed and enabled.
-3. If Codex asks you to review hooks, inspect `hooks/hooks.json` and the `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command before explicitly trusting the current definition. If the app does not provide hook review, use `/hooks` in the interactive Codex CLI during installation.
+1. In the Codex app's **Plugins** screen, confirm that **Codex Agent View** is installed and enabled.
+2. In its **Hooks** section, choose **Review**, inspect `hooks/hooks.json` and the `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command, then choose **Trust all** for the current definitions. Only if the app has no hook-review UI, use `/hooks` in the interactive Codex CLI.
+3. Quit Codex completely and reopen it.
 4. Create a new Codex task. Events from before installation are not replayed.
 
+Persisted hook trust is not exposed by the current programmatic plugin status, so the browser and `doctor` cannot confirm that approval; verify it in the Codex app or interactive `/hooks` UI.
+
 ## Use
 
 In a Codex app task, select and send:
@@ -40,6 +57,7 @@ That is the whole normal-use command. The plugin prepares or reuses its local mo
 - Do not start the monitor in a terminal.
 - Do not copy or manage a localhost URL.
 - Closing the browser tab does not stop Codex work. Invoke `@codex-agent-view` again when you want a new authenticated tab.
+- The task used to open the viewer is hidden from the view itself, so use a separate viewer task to monitor the work you care about.
 
 The public Codex plugin API does not provide a reliable automatic app sidebar or in-app panel for this workflow, so the default browser is the supported display surface.
 
@@ -94,7 +112,7 @@ codex-agent-view uninstall --purge
 
 ## Release and project documentation
 
-Release publication and verification evidence is recorded outside the immutable npm package README in [Distribution](docs/distribution.md), including registry digests, exact reinstall checks, CI, tags, and GitHub Releases.
+Release publication and verification evidence is recorded outside the immutable npm package README in [Distribution](docs/distribution.md), including registry digests, this-device compatible-CLI reinstall checks, CI, tags, and GitHub Releases. Those checks did not verify a clean cross-device first install; the compatibility failure above is now recorded separately.
 
 npm publication is separate from submission to the Universal Plugins Directory. Directory validator compatibility, portal/reviewer acceptance, search exposure, and promptless plugin-card Quick start behavior remain unverified and are not claimed here.
 

package/bin/codex-agent-view.mjs

@@ -32,6 +32,8 @@ import {
 const PACKAGE_ROOT = resolve(fileURLToPath(new URL("../", import.meta.url)));
 const PLUGIN_ID = "codex-agent-view@codex-agent-view";
 const MARKETPLACE_NAME = "codex-agent-view";
+const PLUGIN_BUNDLE_RELATIVE_PATH = join("plugins", "codex-agent-view");
+const INSTALLED_MARKETPLACE_PLUGIN_SOURCE = "./plugins/codex-agent-view";
 const BUNDLE_MARKER = ".codex-agent-view-owned.json";
 const BUNDLE_MARKER_SCHEMA_VERSION = 1;
 const PREPARE_LIVE_VIEW_WAIT_MS = 2_000;
@@ -50,8 +52,7 @@ const KNOWN_PRE_PROOF_MANAGED_VERSIONS = new Set([
 ]);
 const CANONICAL_THREAD_ID_PATTERN =
   /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i;
-const INSTALL_ENTRIES = [
-  ".agents",
+const PLUGIN_INSTALL_ENTRIES = [
   ".codex-plugin",
   "assets",
   "bin",
@@ -641,13 +642,11 @@ async function inspectInstalledBundleForLiveView() {
     throw new LiveViewPreparationError("plugin_bundle_unowned");
   }
 
-  const manifest = await readJsonRegularFile(
-    join(destination, ".codex-plugin", "plugin.json"),
-  );
-  if (manifest?.name !== MARKETPLACE_NAME || typeof manifest.version !== "string") {
+  const installedBundle = await inspectManagedBundleLayout(destination);
+  if (installedBundle === null) {
     throw new LiveViewPreparationError("plugin_bundle_invalid");
   }
-  if (manifest.version !== (await packageVersion())) {
+  if (installedBundle.version !== (await packageVersion())) {
     throw new LiveViewPreparationError("plugin_version_mismatch");
   }
 }
@@ -874,18 +873,46 @@ async function inspectPluginBundle(destination) {
   }
 
   const marker = await readJsonRegularFile(join(destination, BUNDLE_MARKER));
-  const manifest = await readJsonRegularFile(
-    join(destination, ".codex-plugin", "plugin.json"),
-  );
   if (
     marker?.schema_version !== BUNDLE_MARKER_SCHEMA_VERSION ||
     marker?.package !== MARKETPLACE_NAME ||
-    marker?.plugin_id !== PLUGIN_ID ||
-    manifest?.name !== MARKETPLACE_NAME
+    marker?.plugin_id !== PLUGIN_ID
   ) {
     return { kind: "unmanaged" };
   }
-  return { kind: "managed", version: manifest.version };
+  const installedBundle = await inspectManagedBundleLayout(destination);
+  if (installedBundle === null) {
+    return { kind: "unmanaged" };
+  }
+  return {
+    kind: "managed",
+    layout: installedBundle.layout,
+    version: installedBundle.version,
+  };
+}
+
+async function inspectManagedBundleLayout(destination) {
+  const candidates = [
+    {
+      layout: "subdirectory",
+      path: join(destination, PLUGIN_BUNDLE_RELATIVE_PATH, ".codex-plugin", "plugin.json"),
+    },
+    {
+      layout: "legacy-root",
+      path: join(destination, ".codex-plugin", "plugin.json"),
+    },
+  ];
+  const matches = [];
+  for (const candidate of candidates) {
+    const manifest = await readJsonRegularFile(candidate.path);
+    if (
+      manifest?.name === MARKETPLACE_NAME &&
+      typeof manifest.version === "string"
+    ) {
+      matches.push({ layout: candidate.layout, version: manifest.version });
+    }
+  }
+  return matches.length === 1 ? matches[0] : null;
 }
 
 function legacyBearerProbeOptions(bundle) {
@@ -926,10 +953,31 @@ async function copyPluginBundle(destination) {
     await rm(destination, { force: true, recursive: true });
   }
   await mkdir(destination, { mode: 0o700, recursive: true });
-  for (const entry of INSTALL_ENTRIES) {
+  await cp(join(PACKAGE_ROOT, ".agents"), join(destination, ".agents"), {
+    errorOnExist: true,
+    force: false,
+    recursive: true,
+  });
+  const installedCatalogPath = join(destination, ".agents", "plugins", "marketplace.json");
+  const installedCatalog = JSON.parse(await readFile(installedCatalogPath, "utf8"));
+  const installedEntry = installedCatalog?.plugins?.find(
+    (entry) => entry?.name === MARKETPLACE_NAME,
+  );
+  if (installedEntry?.source?.source !== "local") {
+    throw new Error("the bundled marketplace catalog is invalid");
+  }
+  installedEntry.source.path = INSTALLED_MARKETPLACE_PLUGIN_SOURCE;
+  await writeFile(installedCatalogPath, `${JSON.stringify(installedCatalog, null, 2)}\n`, {
+    encoding: "utf8",
+    flag: "w",
+    mode: 0o600,
+  });
+  const pluginDestination = join(destination, PLUGIN_BUNDLE_RELATIVE_PATH);
+  await mkdir(pluginDestination, { mode: 0o700, recursive: true });
+  for (const entry of PLUGIN_INSTALL_ENTRIES) {
     const source = join(PACKAGE_ROOT, entry);
     if (!(await pathExists(source))) continue;
-    await cp(source, join(destination, entry), {
+    await cp(source, join(pluginDestination, entry), {
       errorOnExist: true,
       force: false,
       recursive: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-agent-view",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "A read-only Codex plugin for monitoring live tasks and subagents in your browser. Open each view with one lightweight @codex-agent-view invocation. Once open, live monitoring runs locally with no additional model calls.",
   "type": "module",
   "main": "./src/core/index.mjs",

package/public/app.js

@@ -125,10 +125,17 @@ const MESSAGES = Object.freeze({
     emptyTitle: "No task activity has been received in this observation window.",
     emptyCopy: "The local monitor is connected. This result alone does not mean that Codex has no active work or participating agents.",
     emptyGuidanceTitle: "If work does not appear",
+    hookReviewTitle: "Check hook approval first",
+    hookReviewCopy: "No activity has reached this monitor. The hook may not be trusted or loaded yet, but this page cannot inspect Codex's saved hook-trust state.",
     automaticTracking: "You do not need to enter or register task IDs. Activity from trusted hooks is added automatically.",
-    emptyStep1: "After installing the plugin, fully restart the official Codex app.",
-    emptyStep2: "In a new task, review and explicitly trust the Codex Agent View hook command.",
-    emptyStep3: "After trusting it, start new work and run agents. New activity is added automatically.",
+    emptyStep1: "In the Codex app, open Plugins > Codex Agent View, confirm that it is enabled, choose Review under Hooks, and then choose Trust all if those controls are available.",
+    emptyStep2: "If the app has no hook-review controls, open the interactive Codex CLI, run /hooks, inspect the current Codex Agent View command, and approve it.",
+    emptyStep3: "Fully quit and restart the official Codex app so it loads the current plugin and hook definition.",
+    emptyStep4: "After approval and restart, create a new task and start new work to verify delivery.",
+    viewerTaskHiddenTitle: "The viewer task is hidden from this page.",
+    viewerTaskHiddenCopy: "The only observed work item is the task that opened this view, so the visible list is empty.",
+    viewerTaskActionTitle: "Open the viewer from a separate task",
+    viewerTaskExclusion: "The task that opened this view is intentionally excluded. Open Codex Agent View from a separate lightweight viewer task, then start or continue the work you want to monitor in another task.",
     observationBoundary: "Observation starts with the first trusted hook event. Earlier activity and activity missed while local collection was stopped cannot be replayed; restarting collection opens a new observation window.",
     diagnosticsCount: "Validation information · {count}",
     diagnosticOccurrences: "{count} occurrences",
@@ -280,10 +287,17 @@ const MESSAGES = Object.freeze({
     emptyTitle: "이 관찰 화면에서 수신된 작업 활동이 없습니다.",
     emptyCopy: "로컬 모니터 연결은 정상입니다. 이 결과만으로 Codex에 진행 중인 작업이나 참여 에이전트가 없다고 판단할 수 없습니다.",
     emptyGuidanceTitle: "표시되지 않을 때 확인 순서",
+    hookReviewTitle: "먼저 Hook 승인 상태를 확인하세요",
+    hookReviewCopy: "아직 이 모니터에 도착한 활동이 없습니다. Hook이 신뢰되지 않았거나 아직 로드되지 않았을 수 있지만, 이 화면에서는 Codex에 저장된 Hook 신뢰 상태를 확인할 수 없습니다.",
     automaticTracking: "작업 ID를 입력하거나 작업별로 등록할 필요가 없습니다. 신뢰한 hook의 작업 활동이 이 목록에 자동으로 추가됩니다.",
-    emptyStep1: "플러그인을 설치한 뒤 공식 Codex 앱을 완전히 재시작했는지 확인합니다.",
-    emptyStep2: "새 작업에서 표시되는 Codex Agent View hook 명령을 검토하고 직접 신뢰합니다.",
-    emptyStep3: "신뢰 설정 후 새 작업을 시작해 에이전트를 실행합니다. 새 활동은 이 목록에 자동으로 추가됩니다.",
+    emptyStep1: "Codex 앱에서 Plugins > Codex Agent View를 열어 활성화 상태를 확인하고, Hooks에서 '검토'를 누른 뒤 해당 버튼이 보이면 '모두 신뢰하기'를 선택합니다.",
+    emptyStep2: "앱에 Hook 검토 화면이 없다면 interactive Codex CLI에서 /hooks를 실행하고 현재 Codex Agent View 명령을 검토한 뒤 승인합니다.",
+    emptyStep3: "현재 플러그인과 Hook 정의를 다시 로드하도록 공식 Codex 앱을 완전히 종료한 뒤 재시작합니다.",
+    emptyStep4: "승인과 재시작을 마친 뒤 새 작업을 만들고 새로운 활동을 시작해 전달 여부를 확인합니다.",
+    viewerTaskHiddenTitle: "이 화면을 연 작업은 목록에서 숨겨집니다.",
+    viewerTaskHiddenCopy: "현재 관찰된 유일한 작업이 이 화면을 연 작업이므로 표시 목록이 비어 있습니다.",
+    viewerTaskActionTitle: "별도의 작업에서 보기 화면을 여세요",
+    viewerTaskExclusion: "이 화면을 연 작업은 의도적으로 제외됩니다. 별도의 가벼운 보기용 작업에서 Codex Agent View를 연 뒤, 다른 작업에서 관찰할 새 작업을 시작하거나 기존 작업을 계속하세요.",
     observationBoundary: "관찰 화면은 첫 번째로 신뢰한 hook을 받은 시점부터 시작합니다. 그 전에 이미 지나간 활동과 로컬 상태 수집이 중단된 동안의 활동은 재생되지 않으며, 수집이 다시 시작되면 새 관찰 화면이 열립니다.",
     diagnosticsCount: "검증 정보 · {count}건",
     diagnosticOccurrences: "{count}건",
@@ -435,10 +449,17 @@ const MESSAGES = Object.freeze({
     emptyTitle: "No se recibió actividad en esta ventana de observación.",
     emptyCopy: "El monitor local está conectado. Este resultado no implica por sí solo que Codex no tenga trabajos o agentes activos.",
     emptyGuidanceTitle: "Si el trabajo no aparece",
+    hookReviewTitle: "Comprueba primero la aprobación del hook",
+    hookReviewCopy: "Aún no llegó actividad a este monitor. Es posible que el hook todavía no sea confiable o no esté cargado, pero esta página no puede consultar el estado de confianza guardado por Codex.",
     automaticTracking: "No es necesario introducir ni registrar IDs de tareas. La actividad de hooks confiables se añade automáticamente.",
-    emptyStep1: "Tras instalar el plugin, reinicia por completo la aplicación oficial de Codex.",
-    emptyStep2: "En una tarea nueva, revisa y autoriza explícitamente el comando hook de Codex Agent View.",
-    emptyStep3: "Después, inicia un trabajo nuevo y ejecuta agentes. La actividad se añadirá automáticamente.",
+    emptyStep1: "En la aplicación Codex, abre Plugins > Codex Agent View, confirma que esté activado, elige Revisar en Hooks y después Confiar en todos si aparecen esos controles.",
+    emptyStep2: "Si la aplicación no tiene controles para revisar hooks, abre la CLI interactiva de Codex, ejecuta /hooks, inspecciona el comando actual de Codex Agent View y apruébalo.",
+    emptyStep3: "Cierra por completo y reinicia la aplicación oficial de Codex para que cargue el plugin y la definición de hook actuales.",
+    emptyStep4: "Después de aprobar y reiniciar, crea una tarea nueva e inicia trabajo nuevo para verificar la entrega.",
+    viewerTaskHiddenTitle: "La tarea que abrió esta vista está oculta.",
+    viewerTaskHiddenCopy: "El único trabajo observado es la tarea que abrió esta vista, por eso la lista visible está vacía.",
+    viewerTaskActionTitle: "Abre el visor desde otra tarea",
+    viewerTaskExclusion: "La tarea que abrió esta vista se excluye intencionalmente. Abre Codex Agent View desde otra tarea ligera de visualización y después inicia o continúa el trabajo que quieras observar en una tarea diferente.",
     observationBoundary: "La observación comienza con el primer evento de un hook autorizado. La actividad anterior o perdida mientras la recopilación local estuvo detenida no se puede reproducir; al reiniciarla se abre una ventana nueva.",
     diagnosticsCount: "Información de validación · {count}",
     diagnosticOccurrences: "{count} apariciones",
@@ -1713,12 +1734,26 @@ function setEmptyObservationMessage() {
   elements.stateMessage.className = "state-message state-empty state-empty-observation";
   elements.stateMessage.replaceChildren();
 
+  const rawSessions = Array.isArray(viewState.sessions) ? viewState.sessions : [];
+  const hasOnlyExcludedViewerTask =
+    rawSessions.length > 0 &&
+    observableSessions().length === 0 &&
+    CANONICAL_SESSION_ID_PATTERN.test(excludedSessionId) &&
+    rawSessions.some((session) => session.sessionId === excludedSessionId);
+  const noHookEventsObserved =
+    viewState.diagnostics.length === 0 &&
+    rawSessions.length === 0 &&
+    (!Number.isFinite(viewState.updatedAtMs) || viewState.updatedAtMs <= 0);
+
   const heading = document.createElement("strong");
   const copy = document.createElement("span");
 
   if (viewState.diagnostics.length) {
     heading.textContent = t("emptyWithDiagnosticsTitle");
     copy.textContent = t("emptyWithDiagnosticsCopy", { count: viewState.diagnostics.length });
+  } else if (hasOnlyExcludedViewerTask) {
+    heading.textContent = t("viewerTaskHiddenTitle");
+    copy.textContent = t("viewerTaskHiddenCopy");
   } else {
     heading.textContent = t("emptyTitle");
     copy.textContent = t("emptyCopy");
@@ -1734,18 +1769,45 @@ function setEmptyObservationMessage() {
   automaticTracking.className = "automatic-tracking";
   automaticTracking.textContent = t("automaticTracking");
 
-  const steps = document.createElement("ol");
-  for (const step of [t("emptyStep1"), t("emptyStep2"), t("emptyStep3")]) {
-    const item = document.createElement("li");
-    item.textContent = step;
-    steps.append(item);
-  }
-
   const boundary = document.createElement("p");
   boundary.className = "observation-boundary";
   boundary.textContent = t("observationBoundary");
 
-  guidance.append(guidanceTitle, automaticTracking, steps, boundary);
+  guidance.append(guidanceTitle);
+  if (hasOnlyExcludedViewerTask) {
+    const viewerTaskCallout = document.createElement("section");
+    viewerTaskCallout.className = "viewer-task-callout";
+    const viewerTaskTitle = document.createElement("h4");
+    viewerTaskTitle.textContent = t("viewerTaskActionTitle");
+    const viewerTaskCopy = document.createElement("p");
+    viewerTaskCopy.textContent = t("viewerTaskExclusion");
+    viewerTaskCallout.append(viewerTaskTitle, viewerTaskCopy);
+    guidance.append(viewerTaskCallout);
+  } else if (noHookEventsObserved) {
+    const hookReview = document.createElement("section");
+    hookReview.className = "hook-review-callout";
+    const hookReviewTitle = document.createElement("h4");
+    hookReviewTitle.textContent = t("hookReviewTitle");
+    const hookReviewCopy = document.createElement("p");
+    hookReviewCopy.textContent = t("hookReviewCopy");
+    hookReview.append(hookReviewTitle, hookReviewCopy);
+
+    const steps = document.createElement("ol");
+    for (const step of [
+      t("emptyStep1"),
+      t("emptyStep2"),
+      t("emptyStep3"),
+      t("emptyStep4"),
+    ]) {
+      const item = document.createElement("li");
+      item.textContent = step;
+      steps.append(item);
+    }
+    guidance.append(hookReview, automaticTracking, steps);
+  } else {
+    guidance.append(automaticTracking);
+  }
+  guidance.append(boundary);
 
   if (viewState.diagnostics.length) {
     const diagnostics = document.createElement("div");

package/public/styles.css

@@ -482,6 +482,29 @@ h1 {
   font-size: var(--text-sm);
 }
 
+.hook-review-callout,
+.viewer-task-callout {
+  margin-bottom: var(--space-4);
+  padding: var(--space-4);
+  background: color-mix(in srgb, var(--accent) 9%, var(--surface-raised));
+  border: 1px solid color-mix(in srgb, var(--accent) 42%, var(--border-default));
+  border-left: 0.3rem solid var(--accent);
+  border-radius: var(--radius-sm);
+}
+
+.hook-review-callout h4,
+.viewer-task-callout h4 {
+  margin-bottom: var(--space-2);
+  font-size: var(--text-md);
+}
+
+.hook-review-callout p,
+.viewer-task-callout p {
+  margin: 0;
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+}
+
 .automatic-tracking {
   margin-bottom: var(--space-3);
   color: var(--text-secondary);