Documentation
¶
Overview ¶
Package hook is lazyshell's authoritative AI agent state channel: a Unix socket per session that an agent's own hook mechanism (Claude Code's settings.json hooks, Codex's notify command, ...) can push a state to, via the `lazyshell hook <event>` CLI command. lazyshell never calls the agent — this package only ever listens.
The wire protocol is deliberately the smallest thing that works: one line per event, the line being one of agent.State's four spellings ("idle"/"working"/"blocked"/"done"). No JSON, no framing, no verbs beyond "this is my state now" — an agent declares itself here, it does not control lazyshell.
That last part is a property of *this* channel, not of lazyshell as a whole any more: the verbs an agent can send live in pkg/control, on a separate socket with a separate protocol, off unless config.Control.Enabled says otherwise (docs/adr/0006-api-de-controle-par-les-agents.md). Keeping the two apart is the point — this one stays open by default precisely because it can only ever move a marker in a list.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Send ¶
Send dials the socket at path and writes state as a single line — the client half, used by `lazyshell hook <event>`. Bounded by dialTimeout in both directions: a hook invocation typically blocks the agent that called it, and lazyshell being slow to accept (or gone entirely) must not turn into the agent hanging.
func SocketPath ¶
SocketPath is the Unix socket path a session's hook channel listens on — exported so pkg/session can compute it before starting the process, to inject it into that process's environment as $LAZYSHELL_SOCK. Kept short on purpose (session ids are short, "session-N"): config.RuntimeDir's own doc comment explains the path budget this spends from.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is one session's hook listener.
func Listen ¶
Listen opens path (creating its parent directory at 0700) and starts accepting connections in the background, calling onEvent once per valid line received on any of them. A line that does not parse as an agent.State is silently dropped, never fatal to the connection or the listener — a malformed hook payload degrades a marker, nothing else.
Both shapes of client work: one connection per event (the `lazyshell hook` CLI, which dials, writes one line and disconnects) and a long-lived connection streaming several events over time.
Source Files