refactor: introduce agent hook installer

[tumberger]

Summary

• Add shared hook merge/remove and JSON file helpers for agent integrations.
• Migrate Claude user hook settings onto the shared helpers without behavior changes.

Verification

• go test ./...

[tumberger]

• feat: support codex permission requests #321
• feat: install codex self-serve hooks #320
• feat: add codex agent adapter #319
• refactor: introduce agent hook installer #318 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR moves Claude hook installation onto a shared agent hook helper. The main changes are:

• New shared command parsing and command handler types.
• New generic hook config merge, remove, and lookup helpers.
• New typed hook plans for canonical handler generation.
• Claude user settings now use the shared helpers for merge and uninstall.
• Tests cover parsing, preservation, pruning, idempotency, and template shape.

Confidence Score: 5/5

This looks safe to merge, with one small compatibility edge case to consider.

• No blocking issues found in the changed code.
• The shared merge and remove paths preserve the existing command-only managed hook shape.
• A split command-plus-args encoding can be missed by the Claude ownership predicates.

internal/claudemanaged/usersettings.go

Important Files Changed

Filename	Overview
internal/agenthooks/command.go	Adds shared command handler parsing and shell-like command splitting for hook ownership checks.
internal/agenthooks/config.go	Adds shared JSON hook map helpers for preserving foreign content while merging or removing owned handlers.
internal/agenthooks/plan.go	Adds typed hook plans and canonical native group generation for supported hook events.
internal/claudemanaged/settings.go	Switches managed settings detection to the shared command splitter.
internal/claudemanaged/usersettings.go	Migrates Claude user settings merge and removal to the shared hook config and plan helpers.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Claude settings map] --> B[MergeManagedHooks or RemoveManagedHooks]
  B --> C[managedHookPlan]
  C --> D[agenthooks.Plan]
  B --> E[agenthooks.Config]
  E --> F[HooksMap]
  E --> G[withoutOwnedHandlers]
  G --> H[CommandHandler predicates]
  H --> I[SplitCommand]
  E --> J[Append canonical groups or prune owned handlers]
  J --> K[Updated settings map]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
  A[Claude settings map] --> B[MergeManagedHooks or RemoveManagedHooks]
  B --> C[managedHookPlan]
  C --> D[agenthooks.Plan]
  B --> E[agenthooks.Config]
  E --> F[HooksMap]
  E --> G[withoutOwnedHandlers]
  G --> H[CommandHandler predicates]
  H --> I[SplitCommand]
  E --> J[Append canonical groups or prune owned handlers]
  J --> K[Updated settings map]

Loading

_{Reviews (1): Last reviewed commit: "refactor: introduce typed agent hook pla..." | Re-trigger Greptile}

[greptile-apps]

Split args are skipped

When an existing Claude settings file stores a hook as command: "kontext" with args: ["hook", "pre-tool-use"] or the Guard equivalent, commandHandlerFromMap can parse that shape, but these predicates immediately return false for any non-empty args. That makes HasCommand miss a Guard conflict warning, and it makes merge/remove treat an existing managed hook as foreign. A reinstall can append a second canonical hook, and uninstall can leave the split-form hook behind. If the shared helper accepts args, the Claude predicates should match the equivalent command-plus-args forms instead of ignoring them.