docs(03): capture phase context

.planning/phases/03-hook-server/03-CONTEXT.md

@@ -0,0 +1,82 @@
+# Phase 3: Hook Server - Context
+
+**Gathered:** 2026-03-23
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+HTTP hook server dans vmuxd qui reçoit les events Claude Code (PreToolUse, PostToolUse, Stop, Notification) pour une détection d'état push (< 1s). Distinction fine des types d'attente : permission prompt, question utilisateur, idle prompt.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Cohabitation polling / hooks
+- **D-01:** Hooks comme source primaire. Le poll reste actif mais ralenti (15-30s) comme filet de sécurité pour les sessions sans hooks configurés ou en cas d'event raté.
+- **D-02:** Quand un hook event arrive, le registre est mis à jour immédiatement (pas besoin d'attendre le prochain cycle de poll).
+
+### Claude's Discretion
+- Port HTTP pour le hook server (ex: localhost:3119 ou port dynamique)
+- Format exact des requêtes hook Claude Code (consulter la doc officielle)
+- Mapping events hook → types d'attente (permission_prompt, idle_prompt, etc.)
+- Comment les hooks Claude Code sont configurés (fichier .claude/settings.json ou équivalent)
+- Intervalle du poll fallback ralenti (entre 15s et 30s)
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Existing codebase (Phases 1-2)
+- `daemon.go` — Daemon struct avec poll loop, Unix socket, handlers. Le hook server s'intègre ici.
+- `protocol.go` — SessionInfo struct qui sera enrichie avec le type d'attente.
+- `state.go` — DetectState() et PermissionStallThreshold. Le hook server fournira un signal plus fiable.
+- `types.go` — Session struct et SessionState enum.
+
+### Claude Code hooks documentation
+- Hooks HTTP POST avec payload JSON contenant session_id, cwd, transcript_path, etc.
+- Events : PreToolUse, PostToolUse, Stop, Notification (idle_prompt, permission_prompt)
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `Daemon` struct dans daemon.go — le hook server HTTP sera un goroutine supplémentaire dans le daemon
+- `SessionRegistry` — le hook server y pousse les updates directement
+- `SessionInfo.State` — string, déjà "Working" / "Needs Input" / "Idle". STATE-03 ajoute la granularité
+
+### Established Patterns
+- Daemon démarre des goroutines (acceptLoop, pollLoop) → hookServerLoop suivra le même pattern
+- Handlers JSON dans handleConnection → le HTTP handler suit la même logique
+
+### Integration Points
+- `Daemon.Start()` dans daemon.go — ajouter le démarrage du hook server HTTP
+- `SessionInfo` dans protocol.go — ajouter un champ `WaitType` (permission, question, idle)
+- `state.go` — PermissionStallThreshold peut être remplacé par le signal hook plus fiable
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — open to standard approaches
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 03-hook-server*
+*Context gathered: 2026-03-23*