From a990c1a1b46953c6afeaaf8b362fb3cbc087efb6 Mon Sep 17 00:00:00 2001
From: Pierre Martin <pierre@front-commerce.com>
Date: Mon, 23 Mar 2026 19:24:41 +0100
Subject: [PATCH] docs(03): capture phase context

---
 .planning/phases/03-hook-server/03-CONTEXT.md | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 .planning/phases/03-hook-server/03-CONTEXT.md

diff --git a/.planning/phases/03-hook-server/03-CONTEXT.md b/.planning/phases/03-hook-server/03-CONTEXT.md
new file mode 100644
index 0000000..caf8ccc
--- /dev/null
+++ b/.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*