hook

type Deps struct {
	// Now is the clock for every timestamp the hook records (map times,
	// the prune stamp, the retry stamp) and for the pipeline's rate
	// window; nil means time.Now. Real waits (for a pidfile) use the
	// system clock regardless.
	Now func() time.Time
	// Spawner starts the watcher; nil means RealSpawner.
	Spawner Spawner
	// Registry is the fs.FS the session registry is read from; nil means
	// registry.Dir(config.ClaudeConfigDir(environ)) per run.
	Registry fs.FS
	// ReadFile reads the three settings files of the native scan (6.10),
	// the candidate settings files of the doing-rules scan (card 25, plan
	// 5.2) and, at SessionStart, the frame_file option's file (P5-12);
	// nil means os.ReadFile.
	ReadFile func(string) ([]byte, error)
	// WriteFile is the ONE write under the Claude Code configuration
	// directory (card 50, policy.EnsureUserAccept); nil means
	// adapterkit.WriteAtomicMode.
	WriteFile func(path string, data []byte, mode os.FileMode) error
	// Spawn is the adapter request/response seam (adapterclient.Client.
	// Spawn); nil means adapterkit.Spawn, a real child.
	Spawn adapterclient.SpawnFunc
	// Lookup reads process facts for the pidfile guard; nil means
	// procutil.Lookup.
	Lookup pidfile.LookupFunc
	// LookPath searches a PATH value for an executable name (the
	// shadowing check of 6.2); nil means the package's own search.
	LookPath func(pathVar, name string) (string, bool)
	// SoundPlayer resolves the fixed argv of the sound player the
	// `message_sound` option would run on this machine, or nil and why
	// not (card 35, notify.Sound), and Notifier the same for the desktop
	// notifier of `message_notification` (card 36, notify.Banner); nil
	// means the package's own probe. The hook never runs either:
	// SessionStart only says when one cannot be run.
	SoundPlayer func(pathVar string) ([]string, string)
	Notifier    func(pathVar string) ([]string, string)
	// BrigadeVersion is this binary's own version as a registration
	// reports it (brigade_version, C-46); nil means buildinfo.Claimed,
	// which is nil itself for a binary with no version to claim.
	BrigadeVersion func() *string
	// SyncPeer is the folder-sync peer descriptor a registration and the
	// start heartbeat report when the hook knows one (sync_peer, C-47);
	// nil means it knows none, and the member is then absent — never
	// cleared. At SessionStart it usually knows none: the watcher's sync
	// adapter attaches after the registration and the watcher's first
	// heartbeat after that carries the peer (plan folder-sync.md 4.2).
	SyncPeer func() *string
	// Sink, when set, is passed to the watcher as `--sink <file>` (6.6).
	// Only a test harness sets it; production never does.
	Sink string
	// PidfileWait bounds the wait for a spawned watcher's pidfile; zero
	// means DefaultPidfileWait.
	PidfileWait time.Duration
	// PromptBudget bounds the whole prompt-hook run; zero means
	// promptBudget. Only a test lowers it, to reach the doing reminder's
	// budget guard (plan 5.4) without a real 3.5 s stall.
	PromptBudget time.Duration
}

type RealSpawner struct{}

type SpawnSpec struct {
	// Args is the argv after the program name: "watch", plus "--sink
	// <file>" when Deps.Sink is set.
	Args []string
	// Env is the child's whole environment, built from scratch by
	// watcherEnviron. The messaging token is in here and nowhere else.
	Env []string
	// Dir is the child's working directory (the user's HOME).
	Dir string
	// LogPath is the 0600 append-mode file both of the child's output
	// streams go to: ${stateDir}/logs/watcher-<claude_pid>.log.
	LogPath string
}

type Spawner interface {
	// Spawn starts `brigade watch` per spec and returns its pid. It never
	// waits for the child.
	Spawn(ctx context.Context, spec SpawnSpec) (int, error)
}