fix(hooks): dispatch specialistStart/Stop lifecycle hooks

docs/EXTENDING.md

@@ -192,7 +192,9 @@ Events the agent emits (in dispatch order):
 | `specialistStart` | A sub-agent is spawned | yes (specialist name) |
 | `specialistStop` | A sub-agent ends | yes (specialist name) |
 
-A hook's exit code decides what happens next: `0` continues, non-zero blocks the tool call (`beforeTool`) or surfaces an error (`afterTool`). Hook execution is recorded in the audit log; the audit is reachable from the agent's view of past actions, not from a dedicated `zero doctor` check.
+For swarm members the matcher subject is the **agent type** (`subagent`, `teammate`, …), not a registered specialist profile name — swarm members run from an inline manifest keyed by agent type.
+
+A hook's exit code decides what happens next: `0` continues, non-zero blocks the tool call (`beforeTool`) or surfaces an error (`afterTool`). `sessionStart` / `sessionEnd` / `specialistStart` / `specialistStop` hooks are advisory (failures are audited but do not interrupt the run). Hook execution is recorded in the audit log; the audit is reachable from the agent's view of past actions, not from a dedicated `zero doctor` check.
 
 > **Roadmap.** An in-UI hooks manager is on the backlog. Today you edit the JSON directly.
 

internal/cli/app.go

@@ -807,6 +807,7 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 	// report can be combined with the plugin activation's, and emit at most one
 	// notice when project hooks/plugins were dropped for an untrusted workspace.
 	hookDispatcher, hookSkip := newHookDispatcherWithExtra(workspaceRoot, pluginActivation.hooks, trustRoot, executionRunner)
+	specialistRuntime.attachLifecycleHooks(hookDispatcher)
 	emitTrustNotice(stderr, hookSkip, pluginActivation.trustSkip, mcpSkip)
 	return deps.runTUI(context.Background(), tui.Options{
 		Cwd:                  workspaceRoot,
@@ -1044,6 +1045,9 @@ type agentToolRuntime struct {
 	// the orchestrator's system-prompt delegation section. Populated alongside the
 	// tools, so it is present exactly when the Task tool is.
 	specialists []agent.SpecialistInfo
+	// lifecycleHooks is shared with the specialist executor so the hooks
+	// dispatcher (built later in startup) can be attached before any specialist runs.
+	lifecycleHooks *specialist.LifecycleHooks
 }
 
 // specialistInfos returns the runtime's specialist summaries, nil-safe so the
@@ -1055,12 +1059,26 @@ func (r *agentToolRuntime) specialistInfos() []agent.SpecialistInfo {
 	return r.specialists
 }
 
+func (r *agentToolRuntime) attachLifecycleHooks(dispatcher *hooks.Dispatcher) {
+	if r == nil || r.lifecycleHooks == nil || dispatcher == nil {
+		return
+	}
+	r.lifecycleHooks.Dispatch = func(ctx context.Context, event string, specialistName string, payload map[string]any) {
+		dispatcher.Dispatch(ctx, hooks.DispatchInput{
+			Event:    hooks.Event(event),
+			ToolName: specialistName,
+			Payload:  payload,
+		})
+	}
+}
+
 func registerSpecialistTools(registry *tools.Registry, workspaceRoot string, maxTeamSize int) (*agentToolRuntime, error) {
 	paths, err := specialist.DefaultPaths(workspaceRoot)
 	if err != nil {
 		return nil, err
 	}
-	executor := specialist.Executor{Paths: paths}
+	lifecycleHooks := &specialist.LifecycleHooks{}
+	executor := specialist.Executor{Paths: paths, LifecycleHooks: lifecycleHooks}
 	runtime, err := specialist.RegisterTools(registry, executor)
 	if err != nil {
 		return nil, err
@@ -1079,7 +1097,12 @@ func registerSpecialistTools(registry *tools.Registry, workspaceRoot string, max
 		return nil, err
 	}
 	swarm.RegisterTools(registry, sw)
-	return &agentToolRuntime{specialist: runtime, swarm: sw, specialists: specialistSummaries(paths)}, nil
+	return &agentToolRuntime{
+		specialist:     runtime,
+		swarm:          sw,
+		specialists:    specialistSummaries(paths),
+		lifecycleHooks: lifecycleHooks,
+	}, nil
 }
 
 // specialistSummaries loads the available specialists (built-ins + user/project

internal/cli/exec.go

@@ -625,6 +625,7 @@ func runExec(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) in
 	// can be combined with the plugin activation's, and emit at most one notice when
 	// project hooks/plugins were dropped for an untrusted workspace.
 	hookDispatcher, hookSkip := newHookDispatcherWithExtra(workspaceRoot, pluginActivation.hooks, trustRoot, executionRunner)
+	specialistRuntime.attachLifecycleHooks(hookDispatcher)
 	emitTrustNotice(stderr, hookSkip, pluginActivation.trustSkip, mcpSkip)
 	result, err := agent.Run(runCtx, agentPrompt, provider, agent.Options{
 		MaxTurns:             resolved.MaxTurns,

internal/cli/hooks_manage.go

@@ -319,7 +319,7 @@ Flags:
       --command <cmd>        Command to run (required)
       --name <name>          Human-readable hook name
       --description <text>   Hook description
-      --matcher <pattern>    Tool matcher (beforeTool/afterTool only)
+      --matcher <pattern>    Tool/specialist matcher (beforeTool/afterTool/specialistStart/specialistStop)
       --arg <value>          Command argument (repeatable)
       --user                 Write to user config instead of the project
       --json                 Print command result as JSON

internal/cli/specialist_lifecycle_hooks_test.go

@@ -0,0 +1,43 @@
+package cli
+
+import (
+	"io"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/hooks"
+	"github.com/Gitlawb/zero/internal/specialist"
+	"github.com/Gitlawb/zero/internal/tools"
+)
+
+func TestRegisterSpecialistToolsWiresLifecycleHooksIntoTaskOutput(t *testing.T) {
+	registry := tools.NewRegistry()
+	runtime, err := registerSpecialistTools(registry, t.TempDir(), 0)
+	if err != nil {
+		t.Fatalf("registerSpecialistTools returned error: %v", err)
+	}
+	t.Cleanup(func() { closeSpecialistRuntime(io.Discard, runtime) })
+
+	if runtime.lifecycleHooks == nil {
+		t.Fatal("lifecycleHooks is nil after registerSpecialistTools")
+	}
+	raw, ok := registry.Get("TaskOutput")
+	if !ok {
+		t.Fatal("TaskOutput tool not registered")
+	}
+	outputTool, ok := raw.(*specialist.OutputTool)
+	if !ok {
+		t.Fatalf("TaskOutput type = %T, want *specialist.OutputTool", raw)
+	}
+	if outputTool.LifecycleHooks != runtime.lifecycleHooks {
+		t.Fatal("TaskOutput LifecycleHooks is not the shared registerSpecialistTools bridge")
+	}
+
+	dispatcher := hooks.NewDispatcher(hooks.DispatcherOptions{})
+	runtime.attachLifecycleHooks(dispatcher)
+	if runtime.lifecycleHooks.Dispatch == nil {
+		t.Fatal("attachLifecycleHooks left Dispatch nil")
+	}
+	if outputTool.LifecycleHooks.Dispatch == nil {
+		t.Fatal("TaskOutput did not observe Dispatch after attachLifecycleHooks")
+	}
+}

internal/hooks/hooks.go

@@ -779,7 +779,7 @@ func normalizeDefinition(raw any, field string) (Definition, error) {
 		return Definition{}, err
 	}
 	if matcher != "" && !eventSupportsMatcher(event) {
-		return Definition{}, manifestError{fieldPath: field + ".matcher", message: "matcher is only supported for beforeTool and afterTool hooks."}
+		return Definition{}, manifestError{fieldPath: field + ".matcher", message: "matcher is only supported for beforeTool, afterTool, specialistStart, and specialistStop hooks."}
 	}
 	command, err := requiredString(obj, field+".command")
 	if err != nil {
@@ -843,7 +843,7 @@ func matchesHookMatcher(matcher string, toolName string) bool {
 }
 
 func eventSupportsMatcher(event Event) bool {
-	return event == EventBeforeTool || event == EventAfterTool
+	return event == EventBeforeTool || event == EventAfterTool || event == EventSpecialistStart || event == EventSpecialistStop
 }
 
 func toDiagnostic(err error, source ConfigSource, path string) Diagnostic {

internal/hooks/hooks_test.go

@@ -180,7 +180,7 @@ func TestLoadConfigPreservesUserDisabledStateWhenProjectOmitsEnabled(t *testing.
 }
 
 func TestLoadConfigRejectsMatchersOnLifecycleHooks(t *testing.T) {
-	for _, event := range []string{"sessionStart", "specialistStart"} {
+	for _, event := range []string{"sessionStart", "sessionEnd"} {
 		t.Run(event, func(t *testing.T) {
 			dir := t.TempDir()
 			projectConfigPath := filepath.Join(dir, "hooks.json")
@@ -210,6 +210,46 @@ func TestLoadConfigRejectsMatchersOnLifecycleHooks(t *testing.T) {
 	}
 }
 
+func TestLoadConfigAcceptsMatchersOnSpecialistHooks(t *testing.T) {
+	for _, tc := range []struct {
+		event Event
+		id    string
+	}{
+		{event: EventSpecialistStart, id: "zero.explorer-start"},
+		{event: EventSpecialistStop, id: "zero.explorer-stop"},
+	} {
+		t.Run(string(tc.event), func(t *testing.T) {
+			dir := t.TempDir()
+			projectConfigPath := filepath.Join(dir, "hooks.json")
+			writeHookJSON(t, projectConfigPath, map[string]any{
+				"hooks": []any{map[string]any{
+					"id":      tc.id,
+					"event":   string(tc.event),
+					"matcher": "explorer",
+					"command": "node",
+				}},
+			})
+
+			result, err := LoadConfig(LoadOptions{
+				UserConfigPath:    filepath.Join(dir, "missing-user-hooks.json"),
+				ProjectConfigPath: projectConfigPath,
+			})
+			if err != nil {
+				t.Fatalf("LoadConfig returned error: %v", err)
+			}
+			if len(result.Config.Hooks) != 1 || result.Config.Hooks[0].Matcher != "explorer" {
+				t.Fatalf("specialist matcher hook = %#v", result.Config.Hooks)
+			}
+			if got := hookIDs(Select(result.Config, SelectInput{Event: tc.event, ToolName: "explorer"})); !reflect.DeepEqual(got, []string{tc.id}) {
+				t.Fatalf("matched selection = %#v", got)
+			}
+			if got := Select(result.Config, SelectInput{Event: tc.event, ToolName: "worker"}); len(got) != 0 {
+				t.Fatalf("unmatched specialist should be empty, got %#v", got)
+			}
+		})
+	}
+}
+
 func TestConfigStorePersistsUpdates(t *testing.T) {
 	configPath := filepath.Join(t.TempDir(), "hooks.json")
 	store, err := NewConfigStore(StoreOptions{ConfigPath: configPath})

internal/specialist/accounting.go

@@ -1,6 +1,7 @@
 package specialist
 
 import (
+	"context"
 	"encoding/json"
 	"strings"
 	"sync"
@@ -36,12 +37,11 @@ type specialistAccountingInput struct {
 func (executor Executor) recordSpecialistStart(input specialistAccountingInput) {
 	payload := baseSpecialistPayload(input)
 	_, _ = appendSpecialistSessionEvent(executor.SessionStore, input.ParentSessionID, sessions.EventSpecialistStart, payload)
+	executor.dispatchLifecycleHook("specialistStart", input, payload)
 }
 
 func (executor Executor) recordSpecialistStop(input specialistAccountingInput, summary StreamResult, status string, exitCode int, runErr error, usageRolledUp bool) {
 	store := accountingStore(executor.SessionStore)
-	accountingMu.Lock()
-	defer accountingMu.Unlock()
 	payload := baseSpecialistPayload(input)
 	if summary.RunID != "" {
 		payload["runId"] = summary.RunID
@@ -55,9 +55,30 @@ func (executor Executor) recordSpecialistStop(input specialistAccountingInput, s
 	if len(summary.Errors) > 0 {
 		payload["errors"] = append([]string(nil), summary.Errors...)
 	}
-	// Atomic check+append under the session lock so a concurrent stop path cannot
-	// also pass the existence check and write a duplicate stop event.
+	// Hold accountingMu only for the deduped append so a slow lifecycle hook cannot
+	// stall concurrent specialist stop/usage accounting.
+	accountingMu.Lock()
 	_, _ = appendSpecialistEventOnce(store, input.ParentSessionID, sessions.EventSpecialistStop, payload, input.ChildSessionID, summary.RunID)
+	accountingMu.Unlock()
+	// Dispatch is claimed on this LifecycleHooks bridge, not on session append.
+	// Swarm members may have an empty parent session (append never succeeds) and
+	// TaskOutput may race Task.onExit; hooks must still fire exactly once when a
+	// hook-carrying executor observes the stop.
+	if executor.LifecycleHooks.claimStopDispatch(input.ChildSessionID, summary.RunID) {
+		executor.dispatchLifecycleHook("specialistStop", input, payload)
+	}
+}
+
+func (executor Executor) dispatchLifecycleHook(event string, input specialistAccountingInput, payload map[string]any) {
+	if executor.LifecycleHooks == nil || executor.LifecycleHooks.Dispatch == nil {
+		return
+	}
+	hookPayload := make(map[string]any, len(payload)+1)
+	for key, value := range payload {
+		hookPayload[key] = value
+	}
+	hookPayload["event"] = event
+	executor.LifecycleHooks.Dispatch(context.Background(), event, strings.TrimSpace(input.SpecialistName), hookPayload)
 }
 
 func (executor Executor) rollUpSpecialistUsage(input specialistAccountingInput, summary StreamResult) bool {