Skip to content

Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.

36.1 KB
Raw Blame
package library

import (
	"bytes"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"regexp"
	"slices"
	"strconv"
	"strings"
	"unicode/utf8"

	"github.com/pelletier/go-toml/v2"
	"github.com/tidwall/gjson"
	"github.com/tidwall/jsonc"
	"github.com/yetone/magpie/internal/edit"
)

// Hooks (#1790) are commands an agent runs at a point of its turn: when
// it ends (a phone notification), after it edits a file (a formatter).
// One is kept once and written into each agent ticked for it, in that
// agent's own file and shape:
//
//	Claude Code  <claude dir>/settings.json  hooks.<Event>: [{matcher, hooks: [{type, command, timeout}]}]
//	Codex        <codex home>/hooks.json     the same shape
//	Gemini CLI   ~/.gemini/settings.json     the same shape, timeout in ms
//	Cursor       ~/.cursor/hooks.json        hooks.<event>: [{command, timeout, matcher}], version 1
//
// A portable event ("turn-end") is the same moment in each agent, under
// each one's own name; an agent's own event ("codex:PermissionRequest")
// is given to that agent alone. What magpie wrote is recorded entry by
// entry (Applied.Hooks), and only an entry still exactly as magpie wrote
// it is ever taken out: one the user changed is theirs from then on, and
// the user's own hooks around it stay as they are.

// Hook is a command the agents ticked for it run at Event.
type Hook struct {
	Name string `json:"name"`
	// Description says what the hook is for, in any language (#2011):
	// the name is letters, digits, - and _, which says little to someone
	// who reads Chinese. Only the library keeps it; no agent is given it.
	Description string `json:"description,omitempty"`
	// Event is a portable event (HookEvents), or an agent's own,
	// "<agent>:<Event>" as that agent names it
	Event string `json:"event"`
	// Matcher narrows a tool event to some tools: for a portable event
	// "shell" or "edit" (each agent's own tool names for them), for an
	// agent's own event the agent's own matcher; "" is every tool
	Matcher string   `json:"matcher,omitempty"`
	Command string   `json:"command"`
	Timeout int      `json:"timeout,omitempty"` // seconds; 0 is the agent's own
	Agents  []string `json:"agents"`
}

// HookEntry is one entry magpie wrote into an agent's hooks: the hook it
// is of, the agent's event it is under, and the entry exactly as written.
type HookEntry struct {
	Name  string          `json:"name"`
	Event string          `json:"event"`
	Entry json.RawMessage `json:"entry"`
}

// HookEvents are the portable events, in the order the page offers them.
var HookEvents = []string{"turn-end", "after-tool", "before-tool", "prompt", "session-start"}

// HookTools are the kinds of tools a portable tool event can be narrowed to.
var HookTools = []string{"shell", "edit"}

// hookSpec is how one agent keeps its hooks.
type hookSpec struct {
	path   string
	events map[string]string // portable → the agent's own
	native []string          // every event the agent has
	tools  map[string]string // shell, edit → the agent's matcher for them
	flat   bool              // Cursor: an entry is the command itself, not a group of them
	ms     bool              // Gemini: timeouts in milliseconds
	toml   bool              // Grok: hooks are [[hooks.<Event>]] tables in config.toml, not JSON
}

// hookAgents are the agents magpie can give hooks to.
var hookAgents = []string{"claude", "codex", "cursor", "gemini", "grok", "grok-app"}

// grokHookEvents are the events the Grok CLI fires (docs/user-guide/10-hooks.md),
// shared by Grok Build and the Grok App that runs it. Only the ones magpie
// maps a portable event to, plus an agent's own ("grok:Stop"), are offered;
// the rest are listed so an own-event hook can name any of them.
var grokHookEvents = []string{"SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse",
	"PostToolUseFailure", "PermissionDenied", "Stop", "StopFailure", "StopCancelled", "Notification",
	"SubagentStart", "SubagentStop", "PreCompact", "PostCompact"}

// grokHookTools is Grok's own tool names for a portable tool matcher. Grok also
// reads Claude's names (Bash → run_terminal_command, Edit|Write|MultiEdit →
// search_replace), so the shared Claude tools would do; these are its own.
var grokHookTools = map[string]string{
	"shell": "run_terminal_command",
	"edit":  "search_replace",
}

// grokHookSpec is how the Grok CLI keeps hooks: [[hooks.<Event>]] array tables
// in its config.toml, each with a [[hooks.<Event>.hooks]] child holding the
// command. Grok Build reads ~/.grok/config.toml; Grok App, on a custom route,
// reads agent-home/config.toml. Both are the same shape.
func grokHookSpec(path string) *hookSpec {
	return &hookSpec{
		path: path,
		events: map[string]string{
			"turn-end": "Stop", "after-tool": "PostToolUse", "before-tool": "PreToolUse",
			"prompt": "UserPromptSubmit", "session-start": "SessionStart",
		},
		native: grokHookEvents,
		tools:  grokHookTools,
		toml:   true,
	}
}

// toolEvents are the portable events that take a matcher.
var toolEvents = []string{"after-tool", "before-tool"}

// hookSpecOf is how t keeps its hooks, or why magpie can't give it any.
// claudeHookEvents are every hook event Claude Code has, in its own order:
// the HOOK_EVENTS enum in claude 2.1.296. A settings.json hook under any
// other name is one Claude Code never runs (#2020, emo172).
var claudeHookEvents = []string{"PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification",
	"UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart",
	"SubagentStop", "PreCompact", "PostCompact", "PreModelSwitch", "PostModelSwitch", "PermissionRequest",
	"PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult",
	"ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged",
	"DirectoryAdded", "MessageDisplay"}

func hookSpecOf(t *Target) (*hookSpec, string) {
	if t.Agent.WSL != "" {
		return nil, fmt.Sprintf("magpie gives hooks only to agents on this computer, not yet to %s in WSL", t.Agent.Name)
	}
	switch t.Agent.ID {
	case "claude":
		return &hookSpec{
			path: filepath.Join(claudeDir(), "settings.json"),
			events: map[string]string{"turn-end": "Stop", "after-tool": "PostToolUse", "before-tool": "PreToolUse",
				"prompt": "UserPromptSubmit", "session-start": "SessionStart"},
			native: claudeHookEvents,
			tools:  map[string]string{"shell": "Bash", "edit": "Edit|Write|MultiEdit"},
		}, ""
	case "codex":
		// codex-rs/hooks: hooks.json beside config.toml, whose events are
		// HookEventName's
		return &hookSpec{
			path: filepath.Join(codexDir(), "hooks.json"),
			events: map[string]string{"turn-end": "Stop", "after-tool": "PostToolUse", "before-tool": "PreToolUse",
				"prompt": "UserPromptSubmit", "session-start": "SessionStart"},
			native: []string{"PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "SessionStart", "SessionEnd",
				"UserPromptSubmit", "SubagentStart", "SubagentStop", "Stop", "Interrupt"},
			tools: map[string]string{"shell": "Bash", "edit": "apply_patch"},
		}, ""
	case "gemini":
		// gemini-cli packages/core/src/hooks/types.ts, HookEventName
		return &hookSpec{
			path: filepath.Join(home(), ".gemini", "settings.json"),
			events: map[string]string{"turn-end": "AfterAgent", "after-tool": "AfterTool", "before-tool": "BeforeTool",
				"prompt": "BeforeAgent", "session-start": "SessionStart"},
			native: []string{"BeforeTool", "AfterTool", "BeforeAgent", "AfterAgent", "Notification", "SessionStart", "SessionEnd",
				"PreCompress", "BeforeModel", "AfterModel", "BeforeToolSelection"},
			tools: map[string]string{"shell": "run_shell_command", "edit": "write_file|replace"},
			ms:    true,
		}, ""
	case "cursor":
		return &hookSpec{
			path: filepath.Join(home(), ".cursor", "hooks.json"),
			events: map[string]string{"turn-end": "stop", "after-tool": "postToolUse", "before-tool": "preToolUse",
				"prompt": "beforeSubmitPrompt", "session-start": "sessionStart"},
			native: []string{"beforeShellExecution", "afterShellExecution", "beforeMCPExecution", "afterMCPExecution", "beforeReadFile",
				"afterFileEdit", "beforeSubmitPrompt", "stop", "afterAgentResponse", "afterAgentThought", "sessionStart", "sessionEnd",
				"preToolUse", "postToolUse", "postToolUseFailure", "subagentStart", "subagentStop", "preCompact"},
			tools: map[string]string{"shell": "Shell", "edit": "Write"},
			flat:  true,
		}, ""
	case "grok":
		// Grok Build: [[hooks.<Event>]] tables in ~/.grok/config.toml
		return grokHookSpec(filepath.Join(grokDir(), "config.toml")), ""
	case "grok-app":
		// Grok App runs the same CLI, on a custom route reading
		// agent-home/config.toml, the same [[hooks.<Event>]] shape
		return grokHookSpec(t.MCP.Path), ""
	}
	return nil, fmt.Sprintf("%s has no hooks magpie can write", t.Agent.Name)
}

// event is the agent's own name for h's event, or why it has none.
func (sp *hookSpec) event(agent string, h *Hook) (string, error) {
	if a, ev, ok := strings.Cut(h.Event, ":"); ok {
		if !sameHookFamily(a, agent) {
			return "", fmt.Errorf("%s is an event of another agent's", ev)
		}
		if !slices.Contains(sp.native, ev) {
			return "", fmt.Errorf("it has no event called %s", ev)
		}
		return ev, nil
	}
	if ev := sp.events[h.Event]; ev != "" {
		return ev, nil
	}
	return "", fmt.Errorf("no event called %s", h.Event)
}

// entry is h as the agent's file holds it, under its event ev.
func (sp *hookSpec) entry(h *Hook, ev string) json.RawMessage {
	m := h.Matcher
	if !strings.Contains(h.Event, ":") {
		m = sp.tools[h.Matcher] // "" for none, and for an event that takes no matcher
	}
	timeout := h.Timeout
	if sp.ms {
		timeout *= 1000
	}
	if sp.toml {
		// Grok: a [[hooks.<Event>]] table with a [[hooks.<Event>.hooks]]
		// child. The block text is what goes in the file and what is
		// recorded (as a JSON string) so an entry the user changed is
		// theirs, exactly as with a JSON agent's.
		return json.RawMessage(grokHookBlock(ev, m, h.Command, timeout))
	}
	var v any
	if sp.flat {
		v = struct {
			Command string `json:"command"`
			Timeout int    `json:"timeout,omitempty"`
			Matcher string `json:"matcher,omitempty"`
		}{h.Command, timeout, m}
	} else {
		type cmd struct {
			Type    string `json:"type"`
			Command string `json:"command"`
			Timeout int    `json:"timeout,omitempty"`
		}
		v = struct {
			Matcher string `json:"matcher,omitempty"`
			Hooks   []cmd  `json:"hooks"`
		}{m, []cmd{{"command", h.Command, timeout}}}
	}
	b, _ := json.Marshal(v)
	return b
}

// maxHookDescription is how long a hook's description can be, in
// characters: a line that says what it is for, not a document.
const maxHookDescription = 200

// grokBlockText decodes a Grok hook entry (a JSON string holding the TOML
// block) into the block text.
func grokBlockText(entry json.RawMessage) (string, bool) {
	var s string
	if json.Unmarshal(entry, &s) != nil {
		return "", false
	}
	return s, true
}

// grokHookBlock is one Grok hook as a TOML block: a [[hooks.<Event>]] array
// table, its matcher (when any) and a single [[hooks.<Event>.hooks]] child
// with the command. Returned as a JSON string so it can sit in HookEntry.Entry
// and be compared and moved exactly as a JSON agent's entry is.
func grokHookBlock(ev, matcher, command string, timeout int) string {
	var b strings.Builder
	b.WriteString("[[hooks." + ev + "]]\n")
	if matcher != "" {
		b.WriteString("matcher = " + strconv.Quote(matcher) + "\n")
	}
	b.WriteString("  [[hooks." + ev + ".hooks]]\n")
	b.WriteString("  type = \"command\"\n")
	b.WriteString("  command = " + strconv.Quote(command) + "\n")
	if timeout > 0 {
		b.WriteString("  timeout = " + strconv.Itoa(timeout) + "\n")
	}
	s, _ := json.Marshal(b.String())
	return string(s)
}

// sameHookFamily is whether two agent ids are the same agent for an own
// event: Grok Build and Grok App run the one Grok CLI, so an agent's own
// ("grok:Notification") event goes to both, as a portable one does.
func sameHookFamily(a, b string) bool {
	if a == b {
		return true
	}
	return (a == "grok" || a == "grok-app") && (b == "grok" || b == "grok-app")
}

func (h *Hook) check() error {
	if err := checkName("hook", h.Name); err != nil {
		return err
	}
	if strings.TrimSpace(h.Command) == "" {
		return errors.New("a hook needs a command to run")
	}
	if utf8.RuneCountInString(h.Description) > maxHookDescription {
		return fmt.Errorf("a hook's description is at most %d characters", maxHookDescription)
	}
	if h.Timeout < 0 || h.Timeout > 86400 {
		return errors.New("a hook's timeout is between 0 (the agent's own) and 86400 seconds")
	}
	if a, ev, ok := strings.Cut(h.Event, ":"); ok {
		if !slices.Contains(hookAgents, a) || ev == "" {
			return fmt.Errorf("no event called %s", h.Event)
		}
		for _, x := range h.Agents {
			if !sameHookFamily(x, a) {
				return fmt.Errorf("%s is %s's own event: only it can be given this hook", ev, a)
			}
		}
		return nil
	}
	if !slices.Contains(HookEvents, h.Event) {
		return fmt.Errorf("no event called %s", h.Event)
	}
	if h.Matcher != "" && (!slices.Contains(toolEvents, h.Event) || !slices.Contains(HookTools, h.Matcher)) {
		return fmt.Errorf("%s can't be narrowed to %s", h.Event, h.Matcher)
	}
	return nil
}

func (l *Library) hook(name string) *Hook {
	for _, h := range l.Hooks {
		if h.Name == name {
			return h
		}
	}
	return nil
}

// canonical is a JSON value written one way, its keys sorted, for two
// entries to be told the same however each was spaced.
func canonical(raw []byte) string {
	var v any
	d := json.NewDecoder(bytes.NewReader(raw))
	d.UseNumber()
	if d.Decode(&v) != nil {
		return string(raw)
	}
	b, _ := json.Marshal(v)
	return string(b)
}

// readHooksFile is an agent's hooks file as JSON, "" for one not there. One
// that can't be read, or isn't JSON, is an error: what it holds is unknown,
// never nothing to keep.
func readHooksFile(path string) ([]byte, error) {
	raw, err := edit.Read(path)
	if err != nil {
		return nil, err
	}
	raw = edit.TrimBOM(raw)
	if len(bytes.TrimSpace(raw)) == 0 {
		return nil, nil
	}
	j := jsonc.ToJSON(raw)
	if !json.Valid(j) {
		return nil, fmt.Errorf("%s isn't JSON magpie can read: it is left as it is", path)
	}
	if !gjson.ParseBytes(j).IsObject() {
		return nil, fmt.Errorf("%s isn't a JSON object: it is left as it is", path)
	}
	return j, nil
}

// hookList is the list the file has under hooks.<ev>.
func hookList(doc []byte, path, ev string) ([]json.RawMessage, error) {
	r := gjson.GetBytes(doc, "hooks."+ev)
	if !r.Exists() {
		return nil, nil
	}
	if !r.IsArray() {
		return nil, fmt.Errorf("%s: hooks.%s isn't a list", path, ev)
	}
	var list []json.RawMessage
	if err := json.Unmarshal([]byte(r.Raw), &list); err != nil {
		return nil, fmt.Errorf("%s: hooks.%s: %w", path, ev, err)
	}
	return list, nil
}

// grokHookBlocks reads the [[hooks.<ev>]] blocks a Grok config.toml has, each
// as the block text it is, so it lines up with what grokHookBlock records and
// the same find/claim/drop logic a JSON list uses applies. A file that isn't
// valid TOML is an error, never treated as having no hooks.
func grokHookBlocks(path, ev string) ([]json.RawMessage, error) {
	raw, err := edit.Read(path)
	if err != nil {
		return nil, err
	}
	if len(bytes.TrimSpace(raw)) == 0 {
		return nil, nil
	}
	lines := edit.SplitLines(string(raw))
	header := "[[hooks." + ev + "]]"
	var blocks []json.RawMessage
	for i := 0; i < len(lines); i++ {
		if strings.TrimSpace(lines[i]) != header {
			continue
		}
		j := grokBlockEnd(lines, i)
		block := strings.Join(lines[i:j], "\n") + "\n"
		s, _ := json.Marshal(block)
		blocks = append(blocks, json.RawMessage(s))
		i = j - 1
	}
	return blocks, nil
}

// grokBlockEnd is the line index just past the [[hooks.<ev>]] block starting
// at from: its body, including any [[hooks.<ev>.hooks]] child array tables,
// up to the next table header of another event, trailing blank lines excluded.
func grokBlockEnd(lines []string, from int) int {
	ev, _ := grokArrayEvent(lines[from])
	child := "hooks." + ev + "." // a table under this event continues the block
	j := from + 1
	for j < len(lines) {
		s := strings.TrimSpace(lines[j])
		if isGrokHeader(s) {
			if name := grokTableName(s); !strings.HasPrefix(name, child) {
				break
			}
		}
		j++
	}
	for j-1 > from && strings.TrimSpace(lines[j-1]) == "" {
		j--
	}
	return j
}

// grokTableName is the dotted table name a [[x.y]] header declares, "" for a
// line that isn't one.
func grokTableName(line string) string {
	if ev, ok := grokArrayEvent(line); ok {
		return "hooks." + ev
	}
	return ""
}

// isGrokHeader is whether a line starts a TOML table ([x] or [[x]]).
func isGrokHeader(line string) bool {
	return strings.HasPrefix(strings.TrimSpace(line), "[")
}

// writeGrokHooks applies the drop and add of Grok hook blocks to the config:
// each block whose exact text is dropped is taken out, each added one appended
// after the last [[hooks.*]] block (or at the end). Comments and the user's
// own blocks around them are left as they are; the result is validated as TOML
// before it is written, so a bad state never lands.
func writeGrokHooks(path string, drop, add [][]byte) error {
	raw, err := edit.Read(path)
	if err != nil {
		return err
	}
	lines := edit.SplitLines(string(raw))
	dropped := map[string]bool{}
	for _, d := range drop {
		dropped[string(d)] = true
	}
	var out []string
	lastHooks := -1 // line count up to and including the last [[hooks.*]] block
	i := 0
	for i < len(lines) {
		// start a block only at a [[hooks.<Event>]] header, never at a
		// child [[hooks.<Event>.hooks]] (grokArrayEvent returns that as
		// "Event.hooks"), which belongs to the block above it
		if ev, ok := grokArrayEvent(lines[i]); ok && ev != "" && !strings.Contains(ev, ".") {
			j := grokBlockEnd(lines, i)
			block := strings.Join(lines[i:j], "\n") + "\n"
			if dropped[block] {
				for len(out) > 0 && strings.TrimSpace(out[len(out)-1]) == "" {
					out = out[:len(out)-1] // take the blank line before it too
				}
			} else {
				out = append(out, lines[i:j]...)
			}
			lastHooks = len(out)
			i = j
			continue
		}
		out = append(out, lines[i])
		i++
	}
	for _, a := range add {
		// the block text ends in "\n"; TrimRight then SplitLines leaves no
		// trailing empty element to drop
		blk := edit.SplitLines(strings.TrimRight(string(a), "\n"))
		if lastHooks > 0 {
			insert := append([]string{""}, blk...)
			tail := append([]string{}, out[lastHooks:]...)
			out = append(append(out[:lastHooks], insert...), tail...)
			lastHooks += len(insert)
		} else {
			if len(out) > 0 && strings.TrimSpace(out[len(out)-1]) != "" {
				out = append(out, "")
			}
			out = append(out, blk...)
			lastHooks = len(out)
		}
	}
	return edit.WriteTOMLFile(path, out)
}

// grokArrayEvent is the event a [[hooks.<ev>]] or [[hooks.<ev>.hooks]] header
// names, or "" for a header of another table. The bool says the line is an
// array-table header of the hooks namespace at all.
func grokArrayEvent(line string) (string, bool) {
	s := strings.TrimSpace(line)
	if !strings.HasPrefix(s, "[[") || !strings.HasSuffix(s, "]]") {
		return "", false
	}
	name := strings.TrimSuffix(strings.TrimPrefix(s, "[["), "]]")
	if !strings.HasPrefix(name, "hooks.") {
		return "", false
	}
	return strings.TrimPrefix(name, "hooks."), true
}

// syncHooks writes into t the hooks the library gives it and takes out the
// ones it no longer does: only entries exactly as magpie wrote them, the
// user's own hooks, before and after them, left where they are.
func (l *Library) syncHooks(t *Target, b *backups, res *Result) {
	id := t.Agent.ID
	a := l.applied(id)
	var want []*Hook
	for _, h := range l.Hooks {
		if slices.Contains(h.Agents, id) {
			want = append(want, h)
		}
	}
	if len(a.Hooks) == 0 && len(want) == 0 {
		return
	}
	sp, why := hookSpecOf(t)
	if sp == nil {
		for _, h := range want {
			res.fail(id, "hook:"+h.Name, errors.New(why))
		}
		return
	}
	failAll := func(err error) {
		for _, h := range want {
			res.fail(id, "hook:"+h.Name, err)
		}
		if len(want) == 0 {
			res.fail(id, "hooks", err)
		}
	}
	var doc []byte
	if !sp.toml {
		d, err := readHooksFile(sp.path)
		if err != nil {
			failAll(err)
			return
		}
		doc = d
	}
	lists := map[string][]json.RawMessage{}
	listOf := func(ev string) ([]json.RawMessage, error) {
		if x, ok := lists[ev]; ok {
			return x, nil
		}
		var x []json.RawMessage
		var err error
		if sp.toml {
			x, err = grokHookBlocks(sp.path, ev)
		} else {
			x, err = hookList(doc, sp.path, ev)
		}
		if err == nil {
			lists[ev] = x
		}
		return x, err
	}
	type wanted struct {
		h     *Hook
		ev    string
		entry json.RawMessage
		done  bool
	}
	var ws []*wanted
	for _, h := range want {
		ev, err := sp.event(id, h)
		if err != nil {
			res.fail(id, "hook:"+h.Name, err)
			continue
		}
		if _, err := listOf(ev); err != nil {
			res.fail(id, "hook:"+h.Name, err)
			continue
		}
		ws = append(ws, &wanted{h: h, ev: ev, entry: sp.entry(h, ev)})
	}
	claimed := map[string]map[int]bool{} // event → the entries magpie's records found
	find := func(ev string, entry json.RawMessage) int {
		c := canonical(entry)
		for i, e := range lists[ev] {
			if !claimed[ev][i] && canonical(e) == c {
				return i
			}
		}
		return -1
	}
	claim := func(ev string, i int) {
		if claimed[ev] == nil {
			claimed[ev] = map[int]bool{}
		}
		claimed[ev][i] = true
	}
	var kept []HookEntry
	drop := map[string][]int{} // event → the entries to take out
	var unread []HookEntry     // records of an event whose list can't be read now
	for _, rec := range a.Hooks {
		if _, err := listOf(rec.Event); err != nil {
			res.fail(id, "hook:"+rec.Name, err)
			unread = append(unread, rec)
			continue
		}
		i := find(rec.Event, rec.Entry)
		if i < 0 {
			continue // gone, or changed by the user: theirs now
		}
		claim(rec.Event, i)
		if j := slices.IndexFunc(ws, func(w *wanted) bool {
			return !w.done && w.h.Name == rec.Name && w.ev == rec.Event && canonical(w.entry) == canonical(rec.Entry)
		}); j >= 0 {
			ws[j].done = true
			kept = append(kept, rec)
			continue
		}
		drop[rec.Event] = append(drop[rec.Event], i)
	}
	add := map[string][]json.RawMessage{}
	var added []HookEntry
	for _, w := range ws {
		// an agent gone from here is given nothing new; what it has stays
		// its until unticked
		if w.done || t.Gone {
			continue
		}
		// the same entry of the user's own already runs: it isn't written
		// twice, nor taken as magpie's
		if i := find(w.ev, w.entry); i >= 0 {
			continue
		}
		add[w.ev] = append(add[w.ev], w.entry)
		added = append(added, HookEntry{Name: w.h.Name, Event: w.ev, Entry: w.entry})
	}
	if len(drop) == 0 && len(add) == 0 {
		a.Hooks = append(kept, unread...)
		return
	}
	if sp.toml {
		if err := b.keep(id, sp.path); err != nil {
			failAll(err)
			return
		}
		err := os.MkdirAll(filepath.Dir(sp.path), 0o755)
		if err == nil {
			var drops, adds [][]byte
			// the dropped blocks: the entry text each index in lists holds
			for ev, idxs := range drop {
				for _, i := range idxs {
					if blk, ok := grokBlockText(lists[ev][i]); ok {
						drops = append(drops, []byte(blk))
					}
				}
			}
			for _, es := range add {
				for _, e := range es {
					if blk, ok := grokBlockText(e); ok {
						adds = append(adds, []byte(blk))
					}
				}
			}
			err = writeGrokHooks(sp.path, drops, adds)
		}
		if err != nil {
			failAll(fmt.Errorf("%s: %w", sp.path, err))
			return
		}
		res.changed(id)
		a.Hooks = append(append(kept, added...), unread...)
		return
	}
	// what each list becomes, and where each entry left in it moves to
	var set []edit.KV
	var del []string
	moved := map[string]map[int]int{} // event → old index → new, -1 for one taken out
	for _, ev := range slices.Sorted(func(yield func(string) bool) {
		seen := map[string]bool{}
		for k := range drop {
			if !seen[k] && !yield(k) {
				return
			}
			seen[k] = true
		}
		for k := range add {
			if !seen[k] && !yield(k) {
				return
			}
			seen[k] = true
		}
	}) {
		old := lists[ev]
		m := map[int]int{}
		var next []json.RawMessage
		for i, e := range old {
			if slices.Contains(drop[ev], i) {
				m[i] = -1
				continue
			}
			m[i] = len(next)
			next = append(next, e)
		}
		next = append(next, add[ev]...)
		moved[ev] = m
		if len(next) == 0 {
			del = append(del, "hooks."+ev)
		} else {
			set = append(set, edit.KV{Path: "hooks." + ev, Value: next})
		}
	}
	if err := b.keep(id, sp.path); err != nil {
		failAll(err)
		return
	}
	// Codex trusts a hook by where it is (codex-rs/hooks: hook_key, the
	// file's path, the event, the group's and the handler's index): an
	// entry taken out from before the user's own would leave their trust
	// on the wrong ones, so it is moved with them
	var rekey func() error
	if id == "codex" && len(drop) > 0 {
		cfg := filepath.Join(codexDir(), "config.toml")
		f, err := codexRekey(cfg, sp.path, moved)
		if err != nil {
			failAll(err)
			return
		}
		if f != nil {
			if err := b.keep(id, cfg); err != nil {
				failAll(err)
				return
			}
			rekey = f
		}
	}
	raw := doc
	if raw == nil {
		raw = []byte("{}\n")
	} else if orig, err := edit.Read(sp.path); err == nil {
		raw = orig // its comments and spacing, as the user has them
	}
	if sp.flat && !gjson.GetBytes(jsonc.ToJSON(edit.TrimBOM(raw)), "version").Exists() {
		set = append(set, edit.KV{Path: "version", Value: 1})
	}
	out, err := edit.PatchJSON(raw, set, del)
	if err == nil && len(del) > 0 && len(set) == 0 {
		// a hooks object left empty by magpie goes with what it held
		if h := gjson.GetBytes(jsonc.ToJSON(edit.TrimBOM(out)), "hooks"); h.IsObject() && len(h.Map()) == 0 {
			out, err = edit.PatchJSON(out, nil, []string{"hooks"})
		}
	}
	if err == nil {
		err = os.MkdirAll(filepath.Dir(sp.path), 0o755)
	}
	if err == nil {
		err = edit.WriteAtomic(sp.path, out)
	}
	if err != nil {
		failAll(fmt.Errorf("%s: %w", sp.path, err))
		return
	}
	res.changed(id)
	if rekey != nil {
		if err := rekey(); err != nil {
			res.fail(id, "hooks", fmt.Errorf("the hooks are written, but Codex's trust of the ones after them couldn't be moved: review them in Codex's /hooks (%w)", err))
		}
	}
	a.Hooks = append(append(kept, added...), unread...)
}

// codexState is a [hooks.state."<key>"] header line in Codex's config.toml.
var codexState = regexp.MustCompile(`^(\s*\[\s*hooks\s*\.\s*state\s*\.\s*)("(?:[^"\\]|\\.)*"|'[^']*')(\s*\].*)$`)

// codexStateKey splits a hook's trust key: the file's path, the event's
// label, the group's index and the handler's.
func codexStateKey(k string) (path, label string, group, handler int, ok bool) {
	parts := strings.Split(k, ":")
	if len(parts) < 4 {
		return "", "", 0, 0, false
	}
	n := len(parts)
	g, err1 := strconv.Atoi(parts[n-2])
	h, err2 := strconv.Atoi(parts[n-1])
	if err1 != nil || err2 != nil {
		return "", "", 0, 0, false
	}
	return strings.Join(parts[:n-3], ":"), parts[n-3], g, h, true
}

// snake is an event's label in Codex's trust keys (hook_event_key_label):
// PreToolUse is pre_tool_use.
func snake(ev string) string {
	var b strings.Builder
	for i, r := range ev {
		if r >= 'A' && r <= 'Z' {
			if i > 0 {
				b.WriteByte('_')
			}
			r += 'a' - 'A'
		}
		b.WriteRune(r)
	}
	return b.String()
}

// samePath is whether two paths are the same file.
func samePath(a, b string) bool {
	if filepath.Clean(a) == filepath.Clean(b) {
		return true
	}
	ra, err1 := filepath.EvalSymlinks(filepath.Dir(a))
	rb, err2 := filepath.EvalSymlinks(filepath.Dir(b))
	return err1 == nil && err2 == nil && filepath.Base(a) == filepath.Base(b) && ra == rb
}

// codexRekey is what moves Codex's trust records of hooks.json's groups
// along with them (moved: event → old index → new, -1 for one taken out),
// or nil when none needs moving. A record kept in some other spelling than
// a [hooks.state."…"] table of its own can't be moved: that is an error,
// and nothing is written.
func codexRekey(cfg, hooksPath string, moved map[string]map[int]int) (func() error, error) {
	raw, err := edit.Read(cfg)
	if err != nil {
		return nil, err
	}
	if len(bytes.TrimSpace(raw)) == 0 {
		return nil, nil
	}
	var whole struct {
		Hooks struct {
			State map[string]any `toml:"state"`
		} `toml:"hooks"`
	}
	if err := toml.Unmarshal(raw, &whole); err != nil {
		return nil, fmt.Errorf("%s: %w", cfg, err)
	}
	labels := map[string]map[int]int{}
	for ev, m := range moved {
		labels[snake(ev)] = m
	}
	// to is where the record keyed k goes: ok false for one that stays
	to := func(k string) (string, bool) {
		p, label, g, h, ok := codexStateKey(k)
		if !ok || !samePath(p, hooksPath) {
			return "", false
		}
		m := labels[label]
		if m == nil {
			return "", false
		}
		n, in := m[g]
		if !in {
			// a record of a group past the end of the list, whose place
			// an entry magpie adds takes: it goes
			return "", g >= len(m)
		}
		if n == g {
			return "", false
		}
		if n < 0 {
			return "", true
		}
		return fmt.Sprintf("%s:%s:%d:%d", p, label, n, h), true
	}
	need := map[string]bool{}
	for k := range whole.Hooks.State {
		if _, ok := to(k); ok {
			need[k] = true
		}
	}
	if len(need) == 0 {
		return nil, nil
	}
	lines := strings.SplitAfter(string(raw), "\n")
	type span struct {
		from, to int
		key      string
		m        []string
	}
	var spans []span
	for i, ln := range lines {
		m := codexState.FindStringSubmatch(strings.TrimRight(ln, "\r\n"))
		if m == nil {
			continue
		}
		q := m[2]
		var k string
		if q[0] == '\'' {
			k = q[1 : len(q)-1]
		} else if u, err := strconv.Unquote(q); err == nil {
			k = u
		} else {
			continue
		}
		end := len(lines)
		for j := i + 1; j < len(lines); j++ {
			if s := strings.TrimSpace(lines[j]); strings.HasPrefix(s, "[") {
				end = j
				break
			}
		}
		spans = append(spans, span{i, end, k, m})
	}
	for k := range need {
		if !slices.ContainsFunc(spans, func(s span) bool { return s.key == k }) {
			return nil, fmt.Errorf("%s keeps Codex's trust of %s in a way magpie can't move: take the hook out in Codex's /hooks instead", cfg, k)
		}
	}
	return func() error {
		var out strings.Builder
		at := 0
		for _, s := range spans {
			if !need[s.key] {
				continue
			}
			out.WriteString(strings.Join(lines[at:s.from], ""))
			at = s.to
			nk, _ := to(s.key)
			if nk == "" {
				continue // its group is gone, and its record with it
			}
			// the key's end, :<label>:<group>:<handler>, is digits and a
			// label alone: it is written over as it is spelled
			_, label, g, h, _ := codexStateKey(s.key)
			_, _, ng, _, _ := codexStateKey(nk)
			oldEnd, newEnd := fmt.Sprintf(":%s:%d:%d", label, g, h), fmt.Sprintf(":%s:%d:%d", label, ng, h)
			q := s.m[2]
			nq := q[:len(q)-1-len(oldEnd)] + newEnd + q[len(q)-1:]
			nl := s.m[1] + nq + s.m[3]
			if strings.HasSuffix(lines[s.from], "\r\n") {
				nl += "\r\n"
			} else if strings.HasSuffix(lines[s.from], "\n") {
				nl += "\n"
			}
			out.WriteString(nl)
			out.WriteString(strings.Join(lines[s.from+1:s.to], ""))
		}
		out.WriteString(strings.Join(lines[at:], ""))
		return edit.WriteAtomic(cfg, []byte(out.String()))
	}, nil
}

// hooksOff is whether the agent has every hook turned off in its settings,
// for the page to say why one given it doesn't run.
func hooksOff(t *Target, sp *hookSpec) bool {
	switch t.Agent.ID {
	case "claude":
		v, _ := edit.GetJSON(sp.path, "disableAllHooks")
		return v == "true"
	case "gemini":
		v, _ := edit.GetJSON(sp.path, "hooksConfig.enabled")
		return v == "false"
	case "codex":
		f, _ := edit.GetTOMLTable(filepath.Join(codexDir(), "config.toml"), "features")
		return f["hooks"] == "false"
	}
	return false
}

// ---- changes ---------------------------------------------------------------

// SaveHook adds a hook, or replaces the one called old (renaming it). An
// agent it can't be given is left out of it, said in the result.
func SaveHook(old string, h Hook) (*Result, error) {
	h.Description = strings.Join(strings.Fields(h.Description), " ")
	if err := h.check(); err != nil {
		return nil, err
	}
	return change(func(l *Library) error {
		if h.Name != old && l.hook(h.Name) != nil {
			return fmt.Errorf("the library already has a hook called %s", h.Name)
		}
		if old != "" {
			i := slices.IndexFunc(l.Hooks, func(x *Hook) bool { return x.Name == old })
			if i < 0 {
				return fmt.Errorf("no hook called %s", old)
			}
			l.Hooks = slices.Delete(l.Hooks, i, i+1)
		}
		h.Agents = orNone(slices.Compact(slices.Sorted(slices.Values(h.Agents))))
		l.Hooks = append(l.Hooks, &h)
		return nil
	})
}

// HookAgents sets which agents get a hook.
func HookAgents(name string, agents []string) (*Result, error) {
	return change(func(l *Library) error {
		h := l.hook(name)
		if h == nil {
			return fmt.Errorf("no hook called %s", name)
		}
		c := *h
		c.Agents = agents
		if err := c.check(); err != nil {
			return err
		}
		h.Agents = orNone(slices.Compact(slices.Sorted(slices.Values(agents))))
		return nil
	})
}

// SomeHooksAgents gives the hooks named to the agents, or takes them from
// them, each to the agents that can take it: an agent's own event stays
// that agent's alone.
func SomeHooksAgents(names, agents []string, on bool) (*Result, error) {
	if len(names) == 0 {
		return nil, errors.New("no hooks to give the agents")
	}
	if len(agents) == 0 {
		return nil, errors.New("no agents to give the hooks to")
	}
	return change(func(l *Library) error {
		for _, name := range names {
			if l.hook(name) == nil {
				return fmt.Errorf("no hook called %s", name)
			}
		}
		for _, h := range l.Hooks {
			if !slices.Contains(names, h.Name) {
				continue
			}
			list := slices.Clone(h.Agents)
			for _, a := range agents {
				if on && !hookTakes(h, a) {
					continue
				}
				list = set(list, a, on)
			}
			h.Agents = orNone(list)
		}
		return nil
	})
}

// hookTakes is whether agent a can be given h.
func hookTakes(h *Hook, a string) bool {
	if x, _, ok := strings.Cut(h.Event, ":"); ok {
		return sameHookFamily(x, a)
	}
	return slices.Contains(hookAgents, a)
}

// RemoveHooks takes the hooks named out of the library, and what magpie
// wrote of them out of every agent. A name the library hasn't is said in
// Unremoved, the others gone all the same.
func RemoveHooks(names []string) (*Result, error) {
	if len(names) == 0 {
		return nil, errors.New("no hooks to remove")
	}
	names = slices.Compact(slices.Sorted(slices.Values(names)))
	var failed []Problem
	res, err := change(func(l *Library) error {
		failed = nil
		for _, name := range names {
			if l.hook(name) == nil {
				failed = append(failed, Problem{What: "hook:" + name, Error: "no hook called " + name})
			}
		}
		if len(failed) == len(names) {
			return errors.New(failed[0].Error)
		}
		l.Hooks = slices.DeleteFunc(l.Hooks, func(h *Hook) bool { return slices.Contains(names, h.Name) })
		return nil
	})
	if res != nil {
		res.Unremoved = failed
	}
	return res, err
}

// ---- the page --------------------------------------------------------------

// HookView is a library hook, and what each agent makes of it.
type HookView struct {
	*Hook
	// Native is what each agent it can go to calls its event
	Native map[string]string `json:"native,omitempty"`
	// Problems are the agents it couldn't be given to, and why
	Problems map[string]string `json:"problems,omitempty"`
}

// HookAgentView is an agent the Hooks tab lists.
type HookAgentView struct {
	ID string `json:"id"`
	// File is where its hooks are; No is why magpie can't give it any
	File string `json:"file,omitempty"`
	No   string `json:"no,omitempty"`
	// WSL: No is that it runs in WSL, which magpie gives no hooks yet
	WSL bool `json:"wsl,omitempty"`
	// Off: it has every hook turned off in its settings
	Off bool `json:"off,omitempty"`
	// Events are its own events, for a hook of its alone
	Events []string `json:"events,omitempty"`
}

func (l *Library) hooksView(targets []*Target, of func(string) map[string]string) ([]HookView, []HookAgentView) {
	agents := []HookAgentView{}
	specs := map[string]*hookSpec{}
	for _, t := range targets {
		sp, why := hookSpecOf(t)
		av := HookAgentView{ID: t.Agent.ID, No: why, WSL: t.Agent.WSL != ""}
		if sp != nil {
			specs[t.Agent.ID] = sp
			av.File, av.Off, av.Events = sp.path, hooksOff(t, sp), sp.native
		}
		agents = append(agents, av)
	}
	hooks := []HookView{}
	for _, h := range l.Hooks {
		c := *h
		c.Agents = orNone(c.Agents)
		hv := HookView{Hook: &c, Native: map[string]string{}, Problems: of("hook:" + h.Name)}
		for id, sp := range specs {
			if ev, err := sp.event(id, h); err == nil {
				hv.Native[id] = ev
			}
		}
		// an agent ticked that can't take it says why, before any change
		for _, av := range agents {
			if av.No != "" && slices.Contains(h.Agents, av.ID) {
				if hv.Problems == nil {
					hv.Problems = map[string]string{}
				}
				if hv.Problems[av.ID] == "" {
					hv.Problems[av.ID] = av.No
				}
			}
		}
		hooks = append(hooks, hv)
	}
	return hooks, agents
}