SPB Git

Repository Public

0002-claude-hooks-scoped-via-settings-flag.md 2.9 KB

# 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

  1. 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.
  2. Project .claude/settings.local.json — pollutes every repository the user opens. Rejected.
  3. Heuristics on terminal output — forbidden by CLAUDE.md ("do not infer agent state solely from terminal text"). Rejected.
  4. --settings <app-private file> with type: http hooks 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 one http handler per subscribed event (SessionStart/End, UserPromptSubmit, Pre/PostToolUse, PostToolUseFailure, PermissionRequest, Notification, Stop, Subagent*, PreCompact, CwdChanged), pointing at http://127.0.0.1:<port>/hook with a per-launch bearer token. The feature is off by default.
  • The receiver (ClaudeIntegration.HookServer) always answers 200 with 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 --resume on 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 --settings file; Mission Control lists such sessions separately when they do.
  • Hook payload fields not documented verbatim (e.g. notification_type) are read defensively and kept in raw.
  • If Claude Code ever restricts http hooks via allowedHttpHookUrls, the user must allow the loopback URL.
Files main
Menu

Theme