feat(hooks): add on_session_resume event

Fires when the user explicitly approves the runtime to continue

past its configured max_iterations limit. The runtime already

supports user-driven resume via the resumeChan / ResumeTypeApprove

path, but the resumption was visible only as a runtime-internal

behaviour (the iteration counter quietly extended). The hook makes

the event accessible for:

  - alerting on extended-runtime sessions ("agent X has resumed

    past its iteration cap N times this hour")

  - billing/quota pipelines that meter resumes separately from

    initial budget

  - audit transcripts that distinguish "agent stopped at N" from

    "agent stopped at N, user resumed, then stopped at N+10"

Two new typed Input fields, PreviousMaxIterations and

NewMaxIterations, carry the granted runtime so audit pipelines can

compute the delta directly without reconstructing it from the

iteration counter.

The hook fires alongside the existing AgentSwitching / Notification

machinery in the resume branch, so consumers that already track

ResumeTypeApprove via other channels see no behaviour change.

Assisted-By: docker-agent

Author: dgageot

agent-schema.json

@@ -574,6 +574,13 @@
           "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"
+          }
         }
       },
       "additionalProperties": false

pkg/config/latest/types.go

@@ -1676,6 +1676,11 @@ type HooksConfig struct {
 	// 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"`
 }
 
 // IsEmpty returns true if no hooks are configured
@@ -1695,7 +1700,8 @@ func (h *HooksConfig) IsEmpty() bool {
 		len(h.Notification) == 0 &&
 		len(h.OnError) == 0 &&
 		len(h.OnMaxIterations) == 0 &&
-		len(h.OnAgentSwitch) == 0
+		len(h.OnAgentSwitch) == 0 &&
+		len(h.OnSessionResume) == 0
 }
 
 // HookMatcherConfig represents a hook matcher with its hooks.
@@ -1836,6 +1842,13 @@ func (h *HooksConfig) validate() error {
 		}
 	}
 
+	// Validate OnSessionResume hooks
+	for i, hook := range h.OnSessionResume {
+		if err := hook.validate("on_session_resume", i); err != nil {
+			return err
+		}
+	}
+
 	return nil
 }
 

pkg/hooks/executor.go

@@ -86,6 +86,7 @@ func compileEvents(c *Config) map[EventType][]matcher {
 		EventOnError:         flat(c.OnError),
 		EventOnMaxIterations: flat(c.OnMaxIterations),
 		EventOnAgentSwitch:   flat(c.OnAgentSwitch),
+		EventOnSessionResume: flat(c.OnSessionResume),
 	}
 }
 

pkg/hooks/types.go

@@ -53,6 +53,11 @@ const (
 	// 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"
 )
 
 // consumesContext reports whether the runtime emit site for e routes
@@ -100,6 +105,14 @@ type Input struct {
 	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"`
 }
 
 // ToJSON serializes the input.

pkg/runtime/hooks.go

@@ -201,6 +201,20 @@ func (r *LocalRuntime) executeOnAgentSwitchHooks(ctx context.Context, a *agent.A
 	}, 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)
+}
+
 // 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())
 

pkg/runtime/on_session_resume_test.go

@@ -0,0 +1,79 @@
+package runtime
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/docker/docker-agent/pkg/agent"
+	"github.com/docker/docker-agent/pkg/hooks"
+	"github.com/docker/docker-agent/pkg/team"
+)
+
+// runtimeWithRecordedSessionResume mirrors runtimeWithRecordedAgentSwitch
+// for the on_session_resume event. Same pattern: register a recording
+// builtin on the runtime's private registry post-construction so the
+// test can assert on dispatched input without exposing a runtime
+// option that production callers shouldn't reach for.
+func runtimeWithRecordedSessionResume(t *testing.T) (*LocalRuntime, *recordingBuiltin) {
+	t.Helper()
+
+	rb := &recordingBuiltin{}
+	prov := &mockProvider{id: "test/mock-model", stream: &mockStream{}}
+	a := agent.New("root", "instructions",
+		agent.WithModel(prov),
+		agent.WithHooks(&hooks.Config{
+			OnSessionResume: []hooks.Hook{{
+				Type:    hooks.HookTypeBuiltin,
+				Command: "test_record_session_resume",
+			}},
+		}),
+	)
+	tm := team.New(team.WithAgents(a))
+
+	r, err := NewLocalRuntime(tm, WithModelStore(mockModelStore{}))
+	require.NoError(t, err)
+
+	require.NoError(t, r.hooksRegistry.RegisterBuiltin("test_record_session_resume", rb.hook))
+	r.buildHooksExecutors()
+
+	return r, rb
+}
+
+// TestExecuteOnSessionResumeHooks_ForwardsLimits pins the contract:
+// PreviousMaxIterations and NewMaxIterations both reach the hook
+// verbatim. Audit pipelines compute the granted-runtime delta from
+// these directly without rebuilding it from the iteration counter.
+func TestExecuteOnSessionResumeHooks_ForwardsLimits(t *testing.T) {
+	t.Parallel()
+
+	r, rb := runtimeWithRecordedSessionResume(t)
+	a := r.CurrentAgent()
+	require.NotNil(t, a)
+
+	r.executeOnSessionResumeHooks(t.Context(), a, "session-y", 5, 15)
+
+	got := rb.snapshot()
+	require.Len(t, got, 1)
+	in := got[0]
+	assert.Equal(t, "session-y", in.SessionID)
+	assert.Equal(t, 5, in.PreviousMaxIterations)
+	assert.Equal(t, 15, in.NewMaxIterations)
+}
+
+// TestExecuteOnSessionResumeHooks_NoopWhenNoHookRegistered keeps the
+// cheap-when-unused property symmetric with on_agent_switch: no
+// dispatch, no panic, no error when no hook is configured.
+func TestExecuteOnSessionResumeHooks_NoopWhenNoHookRegistered(t *testing.T) {
+	t.Parallel()
+
+	prov := &mockProvider{id: "test/mock-model", stream: &mockStream{}}
+	a := agent.New("root", "instructions", agent.WithModel(prov))
+	tm := team.New(team.WithAgents(a))
+
+	r, err := NewLocalRuntime(tm, WithModelStore(mockModelStore{}))
+	require.NoError(t, err)
+
+	r.executeOnSessionResumeHooks(t.Context(), a, "s", 5, 15)
+}