feat: make claude codex opencode hooks session-only

6 files changed, 38 insertions, 23 deletions

diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md
index 234e7503..9db3ec9d 100644
--- a/docs/next/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
@@ -9,6 +9,7 @@
 
 ### Changed
 - Native agent session restore is now enabled by default for supported panes with current official integrations. Set `[session] resume_agents_on_restore = false` to disable it.
+- Claude Code, Codex, and OpenCode integrations now report session identity only. Native state for those agents comes from Herdr's screen detection, while Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can still report state.
 
 ### Fixed
 - Kiro sub-agent tool approval prompts are now detected as blocked instead of working. (#388)
diff --git a/docs/next/README.md b/docs/next/README.md
index 39b3cef8..93906b5b 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -57,7 +57,7 @@ Press `ctrl+b q` to detach the client. The server and pane processes keep runnin
 
 **Keybindings.** Herdr uses explicit keybinding strings. `prefix+n` means press the configured prefix, then `n`. `ctrl+alt+n`, `cmd+k`, `alt+1`, and function-key chords are direct terminal-mode shortcuts and do not need the prefix. Plain direct printable keys such as `n` steal normal typing, so use `prefix+n` unless you intentionally want a modifier-gated direct binding.
 
-**Agent awareness.** The sidebar shows blocked, working, done, and idle states. Detection works with process names and terminal output by default. Official integrations make state reporting and native agent session restore more reliable, but Herdr still works as a terminal multiplexer without them.
+**Agent awareness.** The sidebar shows blocked, working, done, and idle states. Detection works with process names and terminal output by default. Official Claude Code, Codex, and OpenCode integrations add session restore identity, while Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can still report their own state.
 
 ## update
 
@@ -121,7 +121,7 @@ states:
 - 🔵 **done** — work finished, you have not looked at it yet
 - 🟢 **idle** — done and seen
 
-detection works by reading foreground process and terminal output. zero config, no hooks required. for agents that expose hooks, the socket api integration gives more robust state reporting.
+detection works by reading foreground process and terminal output. zero config, no hooks required. official claude code, codex, and opencode integrations provide session restore identity; pi, omp, github copilot cli, hermes, qodercli, and custom socket integrations can report their own state.
 
 ## lives in your terminal
 
@@ -168,7 +168,7 @@ for agents outside the built-in list, herdr still works as a terminal multiplexe
 
 ### direct integrations
 
-the built-in pi, omp, claude code, codex, github copilot cli, opencode, hermes, and qodercli integrations forward semantic state to herdr over the socket api. install with:
+the built-in pi, omp, github copilot cli, hermes, and qodercli integrations forward semantic state to herdr over the socket api. claude code, codex, and opencode integrations provide session-start identity while native state comes from screen detection. install with:
 
 ```bash
 herdr integration install pi
diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx
index 57d18b0e..bc3a8b00 100644
--- a/docs/next/website/src/content/docs/agents.mdx
+++ b/docs/next/website/src/content/docs/agents.mdx
@@ -37,9 +37,9 @@ Herdr combines three signals:
 
 1. foreground process detection
 2. terminal output heuristics
-3. integration state reports
+3. integration session identity or state reports
 
-Process detection tells Herdr which pane owns an agent. Heuristics infer state when no hook is available. Integrations provide the most precise semantic state.
+Process detection tells Herdr which pane owns an agent. Heuristics infer native agent state from the visible terminal. Claude Code, Codex, and OpenCode integrations provide session identity for restore; Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can report state when they define state outside the native terminal UI.
 
 ## State rollups
 
diff --git a/docs/next/website/src/content/docs/integrations.mdx b/docs/next/website/src/content/docs/integrations.mdx
index 2cf87e12..cb2041af 100644
--- a/docs/next/website/src/content/docs/integrations.mdx
+++ b/docs/next/website/src/content/docs/integrations.mdx
@@ -3,9 +3,9 @@ title: Integrations
 description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Hermes Agent, and Qoder CLI.
 ---
 
-Herdr detects supported agents automatically. Integrations make that detection more precise by reporting semantic state directly to Herdr.
+Herdr detects supported agents automatically. Native Claude Code, Codex, and OpenCode state comes from screen detection. Their official integrations add session identity for restore; Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom integrations can report their own state.
 
-Use integrations when you want reliable `working`, `blocked`, `idle`, and `done` state from agent hooks or plugins.
+Use integrations when you want native agent session restore or custom extension state from Pi/OMP/Copilot/Hermes/Qoder-style hooks or plugins.
 
 ## Install integrations
 
@@ -42,14 +42,14 @@ Herdr combines three signals:
 | Signal | Purpose |
 | --- | --- |
 | Process detection | Identifies which pane owns which running process. |
-| Agent integration events | Reports semantic state such as `working` or `blocked`. |
-| Screen heuristics | Fills gaps when hooks are unavailable or incomplete. |
+| Screen heuristics | Infers visible native agent state such as `working` or `blocked`. |
+| Integration events | Reports native session identity, or state for Pi/OMP/Copilot/Hermes/Qoder-style extensions. |
 
-Integrations enrich state reporting. They do not replace process detection.
+Claude Code, Codex, and OpenCode state detection is screen-read first. Their Herdr-owned integrations do not author `idle`, `working`, or `blocked` state. Pi, OMP, GitHub Copilot CLI, Hermes Agent, Qoder CLI, and custom socket integrations can still report state when they define state that is not visible in the native terminal UI.
 
-Some integrations also report native agent session references. Herdr uses official session references to resume Claude Code, Codex, GitHub Copilot CLI, Pi, Hermes Agent, and OpenCode panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it.
+Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, GitHub Copilot CLI, Pi, Hermes Agent, and OpenCode panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it.
 
-Native session restore requires current Herdr integrations: Pi integration version `2`, Claude Code version `4`, Codex version `4`, GitHub Copilot CLI version `1`, OpenCode version `2`, or Hermes Agent version `2`. OMP integration version `2` reports agent state only. Check installed versions with `herdr integration status`.
+Native session restore requires current Herdr integrations: Pi integration version `2`, Claude Code version `5`, Codex version `5`, GitHub Copilot CLI version `1`, OpenCode version `4`, or Hermes Agent version `2`. OMP integration version `2` and Qoder CLI integration version `1` report agent state only. Check installed versions with `herdr integration status`.
 
 ## Pi
 
@@ -93,7 +93,7 @@ Install the Claude Code hook:
 herdr integration install claude
 ```
 
-The hook reports agent state to the local Herdr socket when Claude Code exposes hook events.
+The hook reports Claude Code session identity to the local Herdr socket on session start. Claude Code state comes from Herdr's screen detection.
 
 Herdr uses `~/.claude` by default, or `CLAUDE_CONFIG_DIR` when set. The Claude config directory must already exist. Install writes `hooks/herdr-agent-state.sh` and updates `settings.json` with Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.
 
@@ -105,7 +105,7 @@ Install the Codex hook:
 herdr integration install codex
 ```
 
-Codex state is reported through the same local socket API used by other integrations.
+The Codex hook reports session identity through the same local socket API used by other integrations. Codex state comes from Herdr's screen detection.
 
 Herdr uses `~/.codex` by default, or `CODEX_HOME` when set. The Codex config directory must already exist. Install writes `herdr-agent-state.sh`, updates `hooks.json`, and ensures `[features] hooks = true` in `config.toml`. It also removes the deprecated top-level `codex_hooks` flag when present. Uninstall removes Herdr entries from `hooks.json` and deletes the hook script, but leaves `config.toml` unchanged.
 
@@ -133,7 +133,7 @@ herdr integration install opencode
 
 Herdr writes the plugin to `~/.config/opencode/plugins/herdr-agent-state.js`. The OpenCode config directory must already exist. Uninstall removes only that plugin file.
 
-The plugin reports semantic state while OpenCode runs inside a Herdr pane. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with `opencode --session <id>`.
+The plugin reports session identity while OpenCode runs inside a Herdr pane. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with `opencode --session <id>`. OpenCode state comes from Herdr's screen detection.
 
 ## Hermes Agent
 
@@ -181,7 +181,6 @@ User hooks that run next to a Herdr-managed integration should use metadata inst
 herdr pane report-metadata "$HERDR_PANE_ID" \
   --source user:claude-title \
   --agent claude \
-  --applies-to-source herdr:claude \
   --title "Refactor auth middleware" \
   --display-agent "Claude: auth" \
   --custom-status "refactor auth" \
diff --git a/docs/next/website/src/content/docs/session-state.mdx b/docs/next/website/src/content/docs/session-state.mdx
index 6ec10af4..d1568675 100644
--- a/docs/next/website/src/content/docs/session-state.mdx
+++ b/docs/next/website/src/content/docs/session-state.mdx
@@ -56,13 +56,14 @@ Native session restore requires these Herdr integration versions or newer:
 | Agent | Minimum Herdr integration version | Resume command |
 | --- | --- | --- |
 | Pi | `2` | `pi --session <path-or-id>` |
-| Claude Code | `4` | `claude --resume <id>` |
-| Codex | `4` | `codex resume <id>` |
+| Claude Code | `5` | `claude --resume <id>` |
+| Codex | `5` | `codex resume <id>` |
 | GitHub Copilot CLI | `1` | `copilot --resume=<id>` |
-| OpenCode | `2` | `opencode --session <id>` |
+| OpenCode | `4` | `opencode --session <id>` |
 | Hermes Agent | `2` | `hermes --resume <id>` |
 
 OMP integration version `2` reports agent state, but does not report native session references for restore.
+Qoder CLI integration version `1` reports agent state, but does not report native session references for restore.
 
 Run `herdr integration status` to check installed integration versions. Reinstall outdated integrations with `herdr integration install <agent>`.
 
diff --git a/docs/next/website/src/content/docs/socket-api.mdx b/docs/next/website/src/content/docs/socket-api.mdx
index 8525c33b..9d9791e7 100644
--- a/docs/next/website/src/content/docs/socket-api.mdx
+++ b/docs/next/website/src/content/docs/socket-api.mdx
@@ -73,7 +73,7 @@ Raw socket method names use dot notation:
 | Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.close` |
 | Worktree | `worktree.list`, `worktree.create`, `worktree.open`, `worktree.remove` |
 | Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.close` |
-| Pane | `pane.split`, `pane.list`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
+| Pane | `pane.split`, `pane.list`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.report_agent_session`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
 | Agent | `agent.list`, `agent.get`, `agent.read`, `agent.send`, `agent.rename`, `agent.focus`, `agent.start` |
 | Events | `events.subscribe`, `events.wait` |
 | Integrations | `integration.install`, `integration.uninstall` |
@@ -163,7 +163,22 @@ Integrations report agent state with `pane.report_agent`.
 
 `custom_status` is visual. It can show a short label like `indexing` without changing semantic behavior.
 
-Official integrations can also report a native session reference. `pane.get`, `pane.list`, `agent.get`, and `agent.list` expose a read-only `agent_session` object when Herdr has a stored native session reference:
+Session-only official integrations report native session references with `pane.report_agent_session`. State-reporting integrations can still include native session references in `pane.report_agent`. State-independent session reports do not affect waits, notifications, or rollups.
+
+```json
+{
+  "id": "req_2",
+  "method": "pane.report_agent_session",
+  "params": {
+    "pane_id": "1-1",
+    "source": "herdr:codex",
+    "agent": "codex",
+    "agent_session_id": "..."
+  }
+}
+```
+
+`pane.get`, `pane.list`, `agent.get`, and `agent.list` expose a read-only `agent_session` object when Herdr has a stored native session reference:
 
 ```json
 {
@@ -190,7 +205,6 @@ Use `pane.report_metadata` when a user hook wants to customize presentation with
     "pane_id": "1-1",
     "source": "user:claude-title",
     "agent": "claude",
-    "applies_to_source": "herdr:claude",
     "title": "Refactor auth middleware",
     "display_agent": "Claude: auth",
     "custom_status": "refactor auth",
@@ -204,7 +218,7 @@ Use `pane.report_metadata` when a user hook wants to customize presentation with
 }
 ```
 
-Metadata reports are display-only. Valid metadata can override the pane title, displayed agent name, compact custom status, and visible state labels. `working`, `blocked`, `idle`, waits, notifications, session restore, and rollups still come from the active agent state report. `agent` is an optional guard for the authoritative agent label; `applies_to_source` is an optional guard for the active lifecycle authority source. Use `display_agent` to change the visible name. `state_labels` keys must be `idle`, `working`, `blocked`, `done`, or `unknown`. Use clear fields such as `clear_custom_status: true` with the same `source` to remove one presentation override.
+Metadata reports are display-only. Valid metadata can override the pane title, displayed agent name, compact custom status, and visible state labels. `working`, `blocked`, `idle`, waits, notifications, and rollups still come from semantic state. Native session restore comes from stored official session references. `agent` is an optional guard for the authoritative agent label; `applies_to_source` is an optional guard for the active lifecycle authority source. Use `display_agent` to change the visible name. `state_labels` keys must be `idle`, `working`, `blocked`, `done`, or `unknown`. Use clear fields such as `clear_custom_status: true` with the same `source` to remove one presentation override.
 
 ## Event subscriptions