Merge pull request #2542 from dgageot/board/runtime-code-extension-points-analysis-776bc127

feat(hooks): add three observability events around runtime transitions

Author: dgageot

agent-schema.json

@@ -567,6 +567,27 @@
           "items": {
             "$ref": "#/definitions/HookDefinition"
           }
+        },
+        "on_agent_switch": {
+          "type": "array",
+          "description": "Hooks that run whenever the runtime moves the active agent to a new one (transfer_task, handoff, or the return after a transferred task completes). Receives from_agent, to_agent, and agent_switch_kind in the input. Observational; useful for audit, transcript, and metrics pipelines that track which agent ran which tools.",
+          "items": {
+            "$ref": "#/definitions/HookDefinition"
+          }
+        },
+        "on_session_resume": {
+          "type": "array",
+          "description": "Hooks that run when the user explicitly approves the runtime to continue past its configured max_iterations limit. Receives previous_max_iterations and new_max_iterations in the input. Observational; useful for alerting on extended-runtime sessions or for billing/quota pipelines that meter resumes.",
+          "items": {
+            "$ref": "#/definitions/HookDefinition"
+          }
+        },
+        "on_tool_approval_decision": {
+          "type": "array",
+          "description": "Hooks that run after the runtime's tool approval chain (yolo / permissions / readonly / ask) resolves a verdict for a tool call, before the call is executed (allow) or its error response is recorded (deny / canceled). Receives approval_decision (\"allow\" | \"deny\" | \"canceled\") and approval_source (a stable classifier of which step decided). Observational; gives audit pipelines a single \"who approved what\" record without re-implementing the chain.",
+          "items": {
+            "$ref": "#/definitions/HookDefinition"
+          }
         }
       },
       "additionalProperties": false

pkg/config/latest/types.go

@@ -1670,6 +1670,23 @@ type HooksConfig struct {
 	// max_iterations limit. Fires alongside Notification with
 	// level="warning".
 	OnMaxIterations []HookDefinition `json:"on_max_iterations,omitempty" yaml:"on_max_iterations,omitempty"`
+
+	// OnAgentSwitch hooks run whenever the runtime moves the active
+	// agent to a new one — transfer_task, handoff, or the return
+	// after a transferred task completes. Observational; useful for
+	// audit, transcript, and metrics pipelines.
+	OnAgentSwitch []HookDefinition `json:"on_agent_switch,omitempty" yaml:"on_agent_switch,omitempty"`
+
+	// OnSessionResume hooks run when the user explicitly approves the
+	// runtime to continue past its configured max_iterations limit.
+	// Observational; useful for alerting on extended-runtime sessions.
+	OnSessionResume []HookDefinition `json:"on_session_resume,omitempty" yaml:"on_session_resume,omitempty"`
+
+	// OnToolApprovalDecision hooks run after the runtime's tool
+	// approval chain resolves a verdict for a tool call. Observational;
+	// gives audit pipelines a structured "who approved what" record
+	// without re-implementing the chain.
+	OnToolApprovalDecision []HookDefinition `json:"on_tool_approval_decision,omitempty" yaml:"on_tool_approval_decision,omitempty"`
 }
 
 // IsEmpty returns true if no hooks are configured
@@ -1688,7 +1705,10 @@ func (h *HooksConfig) IsEmpty() bool {
 		len(h.Stop) == 0 &&
 		len(h.Notification) == 0 &&
 		len(h.OnError) == 0 &&
-		len(h.OnMaxIterations) == 0
+		len(h.OnMaxIterations) == 0 &&
+		len(h.OnAgentSwitch) == 0 &&
+		len(h.OnSessionResume) == 0 &&
+		len(h.OnToolApprovalDecision) == 0
 }
 
 // HookMatcherConfig represents a hook matcher with its hooks.
@@ -1822,6 +1842,27 @@ func (h *HooksConfig) validate() error {
 		}
 	}
 
+	// Validate OnAgentSwitch hooks
+	for i, hook := range h.OnAgentSwitch {
+		if err := hook.validate("on_agent_switch", i); err != nil {
+			return err
+		}
+	}
+
+	// Validate OnSessionResume hooks
+	for i, hook := range h.OnSessionResume {
+		if err := hook.validate("on_session_resume", i); err != nil {
+			return err
+		}
+	}
+
+	// Validate OnToolApprovalDecision hooks
+	for i, hook := range h.OnToolApprovalDecision {
+		if err := hook.validate("on_tool_approval_decision", i); err != nil {
+			return err
+		}
+	}
+
 	return nil
 }
 

pkg/hooks/executor.go

@@ -73,18 +73,21 @@ func compileEvents(c *Config) map[EventType][]matcher {
 		return []matcher{{hooks: hooks}}
 	}
 	return map[EventType][]matcher{
-		EventPreToolUse:      compileMatchers(c.PreToolUse),
-		EventPostToolUse:     compileMatchers(c.PostToolUse),
-		EventSessionStart:    flat(c.SessionStart),
-		EventTurnStart:       flat(c.TurnStart),
-		EventBeforeLLMCall:   flat(c.BeforeLLMCall),
-		EventAfterLLMCall:    flat(c.AfterLLMCall),
-		EventSessionEnd:      flat(c.SessionEnd),
-		EventOnUserInput:     flat(c.OnUserInput),
-		EventStop:            flat(c.Stop),
-		EventNotification:    flat(c.Notification),
-		EventOnError:         flat(c.OnError),
-		EventOnMaxIterations: flat(c.OnMaxIterations),
+		EventPreToolUse:             compileMatchers(c.PreToolUse),
+		EventPostToolUse:            compileMatchers(c.PostToolUse),
+		EventSessionStart:           flat(c.SessionStart),
+		EventTurnStart:              flat(c.TurnStart),
+		EventBeforeLLMCall:          flat(c.BeforeLLMCall),
+		EventAfterLLMCall:           flat(c.AfterLLMCall),
+		EventSessionEnd:             flat(c.SessionEnd),
+		EventOnUserInput:            flat(c.OnUserInput),
+		EventStop:                   flat(c.Stop),
+		EventNotification:           flat(c.Notification),
+		EventOnError:                flat(c.OnError),
+		EventOnMaxIterations:        flat(c.OnMaxIterations),
+		EventOnAgentSwitch:          flat(c.OnAgentSwitch),
+		EventOnSessionResume:        flat(c.OnSessionResume),
+		EventOnToolApprovalDecision: flat(c.OnToolApprovalDecision),
 	}
 }
 

pkg/hooks/types.go

@@ -45,6 +45,26 @@ const (
 	EventOnError EventType = "on_error"
 	// EventOnMaxIterations fires when the runtime reaches its max_iterations limit.
 	EventOnMaxIterations EventType = "on_max_iterations"
+	// EventOnAgentSwitch fires whenever the runtime moves the active
+	// agent to a new one — either delegating a task (transfer_task),
+	// handing off the conversation (handoff), or returning to the
+	// caller after a transferred task completes. Observational; useful
+	// for audit, transcript, and metrics pipelines that track which
+	// agent ran which tools without subscribing to the runtime event
+	// channel.
+	EventOnAgentSwitch EventType = "on_agent_switch"
+	// EventOnSessionResume fires when the user explicitly approves the
+	// runtime to continue past its configured max_iterations limit.
+	// Observational; useful for alerting on extended-runtime sessions
+	// or for pipelines that bill / quota-track per resume.
+	EventOnSessionResume EventType = "on_session_resume"
+	// EventOnToolApprovalDecision fires after the runtime's tool
+	// approval chain (yolo / permissions / readonly / ask) has resolved
+	// a verdict for a tool call, before the call is executed (for
+	// allow) or its error response is recorded (for deny / canceled).
+	// Observational; gives audit pipelines a single, structured "who
+	// approved what" record without re-implementing the chain.
+	EventOnToolApprovalDecision EventType = "on_tool_approval_decision"
 )
 
 // consumesContext reports whether the runtime emit site for e routes
@@ -83,6 +103,33 @@ type Input struct {
 	// Notification specific.
 	NotificationLevel   string `json:"notification_level,omitempty"`
 	NotificationMessage string `json:"notification_message,omitempty"`
+
+	// OnAgentSwitch specific: the agent the runtime is moving away
+	// from (FromAgent) and the one it's switching to (ToAgent), plus
+	// the cause of the transition ("transfer_task", "handoff",
+	// "transfer_task_return"). Empty FromAgent is valid for the
+	// initial switch into the team's default agent.
+	FromAgent       string `json:"from_agent,omitempty"`
+	ToAgent         string `json:"to_agent,omitempty"`
+	AgentSwitchKind string `json:"agent_switch_kind,omitempty"`
+
+	// OnSessionResume specific: the iteration cap that was reached
+	// (PreviousMaxIterations) and the new cap after the user approved
+	// continuation (NewMaxIterations). Carrying both lets audit
+	// pipelines compute how much extra runtime was granted without
+	// reconstructing it from the iteration counter.
+	PreviousMaxIterations int `json:"previous_max_iterations,omitempty"`
+	NewMaxIterations      int `json:"new_max_iterations,omitempty"`
+
+	// OnToolApprovalDecision specific: the verdict resolved by the
+	// approval chain ("allow", "deny", "canceled") and a stable
+	// classifier for what produced it ("yolo",
+	// "session_permissions_allow", "session_permissions_deny",
+	// "team_permissions_allow", "team_permissions_deny",
+	// "readonly_hint", "user_approved", "user_approved_session",
+	// "user_approved_tool", "user_rejected", "context_canceled").
+	ApprovalDecision string `json:"approval_decision,omitempty"`
+	ApprovalSource   string `json:"approval_source,omitempty"`
 }
 
 // ToJSON serializes the input.

pkg/runtime/agent_delegation.go

@@ -311,13 +311,15 @@ func (r *LocalRuntime) handleTaskTransfer(ctx context.Context, sess *session.Ses
 
 	// Emit agent switching start event
 	evts <- AgentSwitching(true, a.Name(), params.Agent)
+	r.executeOnAgentSwitchHooks(ctx, a, sess.ID, a.Name(), params.Agent, agentSwitchKindTransferTask)
 
 	r.setCurrentAgent(params.Agent)
 	defer func() {
 		r.setCurrentAgent(a.Name())
 
 		// Emit agent switching end event
 		evts <- AgentSwitching(false, params.Agent, a.Name())
+		r.executeOnAgentSwitchHooks(ctx, a, sess.ID, params.Agent, a.Name(), agentSwitchKindTransferTaskReturn)
 
 		// Restore original agent info in sidebar
 		evts <- AgentInfo(a.Name(), getAgentModelID(a), a.Description(), a.WelcomeMessage())
@@ -345,7 +347,7 @@ func (r *LocalRuntime) handleTaskTransfer(ctx context.Context, sess *session.Ses
 	return r.runSubSessionForwarding(ctx, sess, s, span, evts, a.Name())
 }
 
-func (r *LocalRuntime) handleHandoff(_ context.Context, _ *session.Session, toolCall tools.ToolCall, _ chan Event) (*tools.ToolCallResult, error) {
+func (r *LocalRuntime) handleHandoff(ctx context.Context, sess *session.Session, toolCall tools.ToolCall, _ chan Event) (*tools.ToolCallResult, error) {
 	var params builtin.HandoffArgs
 	if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &params); err != nil {
 		return nil, fmt.Errorf("invalid arguments: %w", err)
@@ -367,6 +369,7 @@ func (r *LocalRuntime) handleHandoff(_ context.Context, _ *session.Session, tool
 		return nil, err
 	}
 
+	r.executeOnAgentSwitchHooks(ctx, currentAgent, sess.ID, ca, next.Name(), agentSwitchKindHandoff)
 	r.setCurrentAgent(next.Name())
 	handoffMessage := "The agent " + ca + " handed off the conversation to you. " +
 		"Your available handoff agents and tools are specified in the system messages that follow. " +

pkg/runtime/hooks.go

@@ -9,6 +9,7 @@ import (
 	"github.com/docker/docker-agent/pkg/hooks"
 	"github.com/docker/docker-agent/pkg/hooks/builtins"
 	"github.com/docker/docker-agent/pkg/session"
+	"github.com/docker/docker-agent/pkg/tools"
 )
 
 // buildHooksExecutors builds a [hooks.Executor] for every agent in the
@@ -177,6 +178,84 @@ func (r *LocalRuntime) notify(ctx context.Context, a *agent.Agent, event hooks.E
 	}, nil)
 }
 
+// Agent-switch kinds passed via [hooks.Input.AgentSwitchKind] to
+// describe what kind of transition triggered the on_agent_switch
+// event. Constants instead of literals so the hook contract is
+// discoverable from the runtime side and a typo trips a compile
+// error.
+const (
+	agentSwitchKindTransferTask       = "transfer_task"
+	agentSwitchKindTransferTaskReturn = "transfer_task_return"
+	agentSwitchKindHandoff            = "handoff"
+)
+
+// executeOnAgentSwitchHooks fires on_agent_switch when the runtime
+// changes the active agent. Observational; failures are logged. The
+// hook runs alongside the existing [AgentSwitching] event, so users
+// who already consume that event see no behaviour change.
+func (r *LocalRuntime) executeOnAgentSwitchHooks(ctx context.Context, a *agent.Agent, sessionID, fromAgent, toAgent, kind string) {
+	r.dispatchHook(ctx, a, hooks.EventOnAgentSwitch, &hooks.Input{
+		SessionID:       sessionID,
+		FromAgent:       fromAgent,
+		ToAgent:         toAgent,
+		AgentSwitchKind: kind,
+	}, nil)
+}
+
+// executeOnSessionResumeHooks fires on_session_resume when the user
+// explicitly approves continuation past the configured
+// max_iterations limit. Observational; failures are logged. The hook
+// runs alongside the existing event-channel signalling so audit /
+// quota / alerting pipelines can react without subscribing to the
+// per-session channel.
+func (r *LocalRuntime) executeOnSessionResumeHooks(ctx context.Context, a *agent.Agent, sessionID string, prevMax, newMax int) {
+	r.dispatchHook(ctx, a, hooks.EventOnSessionResume, &hooks.Input{
+		SessionID:             sessionID,
+		PreviousMaxIterations: prevMax,
+		NewMaxIterations:      newMax,
+	}, nil)
+}
+
+// Verdicts and sources for [hooks.EventOnToolApprovalDecision]. Constants
+// instead of literals so the contract between executeWithApproval and
+// the hook protocol is discoverable from the runtime side and a typo
+// trips a compile error.
+const (
+	ApprovalDecisionAllow    = "allow"
+	ApprovalDecisionDeny     = "deny"
+	ApprovalDecisionCanceled = "canceled"
+
+	ApprovalSourceYolo                    = "yolo"
+	ApprovalSourceSessionPermissionsAllow = "session_permissions_allow"
+	ApprovalSourceSessionPermissionsDeny  = "session_permissions_deny"
+	ApprovalSourceTeamPermissionsAllow    = "team_permissions_allow"
+	ApprovalSourceTeamPermissionsDeny     = "team_permissions_deny"
+	ApprovalSourceReadOnlyHint            = "readonly_hint"
+	ApprovalSourceUserApproved            = "user_approved"
+	ApprovalSourceUserApprovedSession     = "user_approved_session"
+	ApprovalSourceUserApprovedTool        = "user_approved_tool"
+	ApprovalSourceUserRejected            = "user_rejected"
+	ApprovalSourceContextCanceled         = "context_canceled"
+)
+
+// executeOnToolApprovalDecisionHooks fires on_tool_approval_decision
+// after the runtime's approval chain has resolved a verdict for a
+// tool call. Fired once per call from each return path of
+// [executeWithApproval], so a single hook gets one record per tool
+// call regardless of which step decided.
+func (r *LocalRuntime) executeOnToolApprovalDecisionHooks(
+	ctx context.Context,
+	sess *session.Session,
+	a *agent.Agent,
+	toolCall tools.ToolCall,
+	decision, source string,
+) {
+	input := newHooksInput(sess, toolCall)
+	input.ApprovalDecision = decision
+	input.ApprovalSource = source
+	r.dispatchHook(ctx, a, hooks.EventOnToolApprovalDecision, input, nil)
+}
+
 // executeBeforeLLMCallHooks fires before_llm_call just before each
 // model call. A terminating verdict (decision="block" / continue=false
 // / exit 2) stops the run loop — see [hooks.EventBeforeLLMCall] for

pkg/runtime/loop.go

@@ -302,7 +302,9 @@ func (r *LocalRuntime) RunStream(ctx context.Context, sess *session.Session) <-c
 				case req := <-r.resumeChan:
 					if req.Type == ResumeTypeApprove {
 						slog.Debug("User chose to continue after max iterations", "agent", a.Name())
-						runtimeMaxIterations = iteration + 10
+						newMax := iteration + 10
+						r.executeOnSessionResumeHooks(ctx, a, sess.ID, runtimeMaxIterations, newMax)
+						runtimeMaxIterations = newMax
 					} else {
 						slog.Debug("User rejected continuation", "agent", a.Name())