Phase 3: Hook Server - Context

Gathered: 2026-03-23 Status: Ready for planning

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

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

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

## Specific Ideas

No specific requirements — open to standard approaches

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 03-hook-server Context gathered: 2026-03-23

2.9 KiB Raw Blame History