# 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*