Repository Public
1# ADR 0002 — Claude Code integration through `--settings` HTTP observer hooks23**Status:** Accepted — 2026-11-0145## Context6NEXTERM must show verified Claude session state (working / waiting for permission / idle) without7scraping terminal text, and without silently modifying the user's Claude Code configuration.8The official hooks reference (https://code.claude.com/docs/en/hooks, read 2026-11-01) documents933 events, handler types `command|http|mcp_tool|prompt|agent`, settings file locations, and that10settings merge across user/project/local scopes. `claude --help` (2.1.316) exposes11`--session-id <uuid>` and `--settings <file-or-json>`; there is no `--hooks` flag.1213## Options considered141. **Edit `~/.claude/settings.json`** — global, affects every Claude session on the machine, violates the15 "never modify Claude configuration without consent" rule and is hard to make reversible. Rejected.162. **Project `.claude/settings.local.json`** — pollutes every repository the user opens. Rejected.173. **Heuristics on terminal output** — forbidden by CLAUDE.md ("do not infer agent state solely from terminal text"). Rejected.184. **`--settings <app-private file>` with `type: http` hooks to a loopback receiver** — scoped to sessions19 NEXTERM launches, removable by deleting one file, observable without any decision-making. **Chosen.**2021## Decision22* NEXTERM writes `~/Library/Application Support/NEXTERM/hooks/hooks-settings.json` (0600) containing one23 `http` handler per subscribed event (SessionStart/End, UserPromptSubmit, Pre/PostToolUse,24 PostToolUseFailure, PermissionRequest, Notification, Stop, Subagent*, PreCompact, CwdChanged), pointing at25 `http://127.0.0.1:<port>/hook` with a per-launch bearer token. The feature is off by default.26* The receiver (`ClaudeIntegration.HookServer`) always answers `200` with an empty body, so Claude Code27 behaves exactly as if no hook were installed: it cannot approve, deny, rewrite or block anything.28* The pane ↔ session link is the UUID NEXTERM passes to `--session-id` (or `--resume` on restore).2930## Evidence31Live test with claude 2.1.316: `claude --session-id … --settings … -p "…"` printed `PONG`; an32interactive session in a pane produced `SessionStart`, `Stop` and `Notification(idle_prompt)` events33that Mission Control rendered as "Waiting for you · hook 26s ago · verified" (mc1.png). Unit tests cover34payload parsing, settings generation (no `permissionDecision` ever emitted), 0600 permissions, HTTP35parsing and a real loopback round trip with 200/401/400 paths.3637## Consequences38* Sessions started outside NEXTERM (plain `claude`) report nothing unless the user passes the same39 `--settings` file; Mission Control lists such sessions separately when they do.40* Hook payload fields not documented verbatim (e.g. `notification_type`) are read defensively and kept in `raw`.41* If Claude Code ever restricts http hooks via `allowedHttpHookUrls`, the user must allow the loopback URL.42