ADR 0002 — Claude Code integration through --settings HTTP observer hooks
Status: Accepted — 2026-11-01
Context
NEXTERM must show verified Claude session state (working / waiting for permission / idle) without
scraping terminal text, and without silently modifying the user's Claude Code configuration.
The official hooks reference (https://code.claude.com/docs/en/hooks, read 2026-11-01) documents
33 events, handler types command|http|mcp_tool|prompt|agent, settings file locations, and that
settings merge across user/project/local scopes. claude --help (2.1.316) exposes
--session-id <uuid> and --settings <file-or-json>; there is no --hooks flag.
Options considered
- Edit
~/.claude/settings.json— global, affects every Claude session on the machine, violates the "never modify Claude configuration without consent" rule and is hard to make reversible. Rejected. - Project
.claude/settings.local.json— pollutes every repository the user opens. Rejected. - Heuristics on terminal output — forbidden by CLAUDE.md ("do not infer agent state solely from terminal text"). Rejected.
--settings <app-private file>withtype: httphooks to a loopback receiver — scoped to sessions NEXTERM launches, removable by deleting one file, observable without any decision-making. Chosen.
Decision
- NEXTERM writes
~/Library/Application Support/NEXTERM/hooks/hooks-settings.json(0600) containing onehttphandler per subscribed event (SessionStart/End, UserPromptSubmit, Pre/PostToolUse, PostToolUseFailure, PermissionRequest, Notification, Stop, Subagent*, PreCompact, CwdChanged), pointing athttp://127.0.0.1:<port>/hookwith a per-launch bearer token. The feature is off by default. - The receiver (
ClaudeIntegration.HookServer) always answers200with an empty body, so Claude Code behaves exactly as if no hook were installed: it cannot approve, deny, rewrite or block anything. - The pane ↔ session link is the UUID NEXTERM passes to
--session-id(or--resumeon restore).
Evidence
Live test with claude 2.1.316: claude --session-id … --settings … -p "…" printed PONG; an
interactive session in a pane produced SessionStart, Stop and Notification(idle_prompt) events
that Mission Control rendered as "Waiting for you · hook 26s ago · verified" (mc1.png). Unit tests cover
payload parsing, settings generation (no permissionDecision ever emitted), 0600 permissions, HTTP
parsing and a real loopback round trip with 200/401/400 paths.
Consequences
- Sessions started outside NEXTERM (plain
claude) report nothing unless the user passes the same--settingsfile; Mission Control lists such sessions separately when they do. - Hook payload fields not documented verbatim (e.g.
notification_type) are read defensively and kept inraw. - If Claude Code ever restricts http hooks via
allowedHttpHookUrls, the user must allow the loopback URL.