Merge pull request #1847 from doringeman/hook-on_user_input

dgageot · web-flow · commit 39f64e694ab0 · 2026-02-26T13:28:55.000+01:00
feat(hooks): add on_user_input
diff --git a/agent-schema.json b/agent-schema.json
@@ -390,6 +390,13 @@
           "items": {
             "$ref": "#/definitions/HookDefinition"
           }
+        },
+        "on_user_input": {
+          "type": "array",
+          "description": "Hooks that run when the agent needs user input. Can send notifications or log events.",
+          "items": {
+            "$ref": "#/definitions/HookDefinition"
+          }
         }
       },
       "additionalProperties": false
diff --git a/docs/TODO.md b/docs/TODO.md
@@ -3,7 +3,7 @@
 ## New Pages
 
 - [x] **Go SDK** — Not documented anywhere. The `examples/golibrary/` directory shows how to use cagent as a Go library. Needs a dedicated page. *(Completed: pages/guides/go-sdk.html)*
-- [x] **Hooks** — `hooks` agent config (`pre_tool_use`, `post_tool_use`, `session_start`, `session_end`) is a significant feature with no documentation page. Covers running shell commands at various agent lifecycle points. *(Completed: pages/configuration/hooks.html)*
+- [x] **Hooks** — `hooks` agent config (`pre_tool_use`, `post_tool_use`, `session_start`, `session_end`, `on_user_input`) is a significant feature with no documentation page. Covers running shell commands at various agent lifecycle points. *(Completed: pages/configuration/hooks.html)*
 - [x] **Permissions** — Top-level `permissions` config with `allow`/`deny` glob patterns for tool call approval. Mentioned briefly in TUI page but has no dedicated reference. *(Completed: pages/configuration/permissions.html)*
 - [x] **Sandbox Mode** — Shell tool `sandbox` config runs commands in Docker containers. Includes `image` and `paths` (bind mounts with `:ro` support). Not documented. *(Completed: pages/configuration/sandbox.html)*
 - [x] **Structured Output** — Agent-level `structured_output` config (name, description, schema, strict). Forces model responses into a JSON schema. Not documented. *(Completed: pages/configuration/structured-output.html)*
diff --git a/docs/pages/configuration/agents.html b/docs/pages/configuration/agents.html
@@ -33,6 +33,7 @@ <h2>Full Schema</h2>
       post_tool_use: [list]
       session_start: [list]
       session_end: [list]
+      on_user_input: [list]
     permissions:                   # Optional: tool execution control
       allow: [list]
       deny: [list]
diff --git a/docs/pages/configuration/hooks.html b/docs/pages/configuration/hooks.html
@@ -18,7 +18,7 @@ <h2>Overview</h2>
 
 <h2>Hook Types</h2>
 
-<p>There are four hook event types:</p>
+<p>There are five hook event types:</p>
 
 <table>
   <thead><tr><th>Event</th><th>When it fires</th><th>Can block?</th></tr></thead>
@@ -27,6 +27,7 @@ <h2>Hook Types</h2>
     <tr><td><code>post_tool_use</code></td><td>After a tool completes successfully</td><td>No</td></tr>
     <tr><td><code>session_start</code></td><td>When a session begins or resumes</td><td>No</td></tr>
     <tr><td><code>session_end</code></td><td>When a session terminates</td><td>No</td></tr>
+    <tr><td><code>on_user_input</code></td><td>When the agent is waiting for user input</td><td>No</td></tr>
   </tbody>
 </table>
 
@@ -61,7 +62,12 @@ <h2>Configuration</h2>
       # Run when session ends
       session_end:
         - type: command
-          command: "./scripts/cleanup.sh"</code></pre>
+          command: "./scripts/cleanup.sh"
+
+      # Run when agent is waiting for user input
+      on_user_input:
+        - type: command
+          command: "./scripts/notify.sh"</code></pre>
 
 <h2>Matcher Patterns</h2>
 
@@ -96,17 +102,17 @@ <h2>Hook Input</h2>
 <h3>Input Fields by Event Type</h3>
 
 <table>
-  <thead><tr><th>Field</th><th>pre_tool_use</th><th>post_tool_use</th><th>session_start</th><th>session_end</th></tr></thead>
+  <thead><tr><th>Field</th><th>pre_tool_use</th><th>post_tool_use</th><th>session_start</th><th>session_end</th><th>on_user_input</th></tr></thead>
   <tbody>
-    <tr><td><code>session_id</code></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr>
-    <tr><td><code>cwd</code></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr>
-    <tr><td><code>hook_event_name</code></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr>
-    <tr><td><code>tool_name</code></td><td>✓</td><td>✓</td><td></td><td></td></tr>
-    <tr><td><code>tool_use_id</code></td><td>✓</td><td>✓</td><td></td><td></td></tr>
-    <tr><td><code>tool_input</code></td><td>✓</td><td>✓</td><td></td><td></td></tr>
-    <tr><td><code>tool_response</code></td><td></td><td>✓</td><td></td><td></td></tr>
-    <tr><td><code>source</code></td><td></td><td></td><td>✓</td><td></td></tr>
-    <tr><td><code>reason</code></td><td></td><td></td><td></td><td>✓</td></tr>
+    <tr><td><code>session_id</code></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr>
+    <tr><td><code>cwd</code></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr>
+    <tr><td><code>hook_event_name</code></td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td></tr>
+    <tr><td><code>tool_name</code></td><td>✓</td><td>✓</td><td></td><td></td><td></td></tr>
+    <tr><td><code>tool_use_id</code></td><td>✓</td><td>✓</td><td></td><td></td><td></td></tr>
+    <tr><td><code>tool_input</code></td><td>✓</td><td>✓</td><td></td><td></td><td></td></tr>
+    <tr><td><code>tool_response</code></td><td></td><td>✓</td><td></td><td></td><td></td></tr>
+    <tr><td><code>source</code></td><td></td><td></td><td>✓</td><td></td><td></td></tr>
+    <tr><td><code>reason</code></td><td></td><td></td><td></td><td>✓</td><td></td></tr>
   </tbody>
 </table>
 
diff --git a/examples/hooks.yaml b/examples/hooks.yaml
@@ -94,3 +94,13 @@ agents:
       session_end:
         - type: command
           command: echo "👋 Session ended at $(date)"
+
+      # ============================================================
+      # USER INPUT HOOKS - Run when agent needs user input
+      # ============================================================
+      on_user_input:
+        # Example: Notify when user input is requested
+        - type: command
+          command: |
+            # Send notification (macOS only - remove or adapt for other platforms)
+            osascript -e 'display notification "ready!" with title "cagent"'
diff --git a/pkg/config/latest/types.go b/pkg/config/latest/types.go
@@ -1211,6 +1211,9 @@ type HooksConfig struct {
 
 	// SessionEnd hooks run when a session ends
 	SessionEnd []HookDefinition `json:"session_end,omitempty" yaml:"session_end,omitempty"`
+
+	// OnUserInput hooks run when the agent needs user input
+	OnUserInput []HookDefinition `json:"on_user_input,omitempty" yaml:"on_user_input,omitempty"`
 }
 
 // IsEmpty returns true if no hooks are configured
@@ -1221,7 +1224,8 @@ func (h *HooksConfig) IsEmpty() bool {
 	return len(h.PreToolUse) == 0 &&
 		len(h.PostToolUse) == 0 &&
 		len(h.SessionStart) == 0 &&
-		len(h.SessionEnd) == 0
+		len(h.SessionEnd) == 0 &&
+		len(h.OnUserInput) == 0
 }
 
 // HookMatcherConfig represents a hook matcher with its hooks.
@@ -1277,6 +1281,13 @@ func (h *HooksConfig) validate() error {
 		}
 	}
 
+	// Validate OnUserInput hooks
+	for i, hook := range h.OnUserInput {
+		if err := hook.validate("on_user_input", i); err != nil {
+			return err
+		}
+	}
+
 	return nil
 }
 
diff --git a/pkg/hooks/config.go b/pkg/hooks/config.go
@@ -62,5 +62,14 @@ func FromConfig(cfg *latest.HooksConfig) *Config {
 		})
 	}
 
+	// Convert OnUserInput
+	for _, h := range cfg.OnUserInput {
+		result.OnUserInput = append(result.OnUserInput, Hook{
+			Type:    HookType(h.Type),
+			Command: h.Command,
+			Timeout: h.Timeout,
+		})
+	}
+
 	return result
 }
diff --git a/pkg/hooks/executor.go b/pkg/hooks/executor.go
@@ -191,6 +191,17 @@ func (e *Executor) ExecuteSessionEnd(ctx context.Context, input *Input) (*Result
 	return e.executeHooks(ctx, e.config.SessionEnd, input, EventSessionEnd)
 }
 
+// ExecuteOnUserInput runs on-user-input hooks
+func (e *Executor) ExecuteOnUserInput(ctx context.Context, input *Input) (*Result, error) {
+	if e.config == nil || len(e.config.OnUserInput) == 0 {
+		return &Result{Allowed: true}, nil
+	}
+
+	input.HookEventName = EventOnUserInput
+
+	return e.executeHooks(ctx, e.config.OnUserInput, input, EventOnUserInput)
+}
+
 // executeHooks runs a list of hooks in parallel and aggregates results
 func (e *Executor) executeHooks(ctx context.Context, hooks []Hook, input *Input, eventType EventType) (*Result, error) {
 	// Deduplicate hooks by command
@@ -415,3 +426,8 @@ func (e *Executor) HasSessionStartHooks() bool {
 func (e *Executor) HasSessionEndHooks() bool {
 	return e.config != nil && len(e.config.SessionEnd) > 0
 }
+
+// HasOnUserInputHooks returns true if there are any on-user-input hooks configured
+func (e *Executor) HasOnUserInputHooks() bool {
+	return e.config != nil && len(e.config.OnUserInput) > 0
+}
diff --git a/pkg/hooks/hooks_test.go b/pkg/hooks/hooks_test.go
@@ -89,6 +89,13 @@ func TestConfigIsEmpty(t *testing.T) {
 			},
 			expected: false,
 		},
+		{
+			name: "with on_user_input",
+			config: Config{
+				OnUserInput: []Hook{{Type: HookTypeCommand}},
+			},
+			expected: false,
+		},
 	}
 
 	for _, tt := range tests {
@@ -480,6 +487,25 @@ func TestExecuteSessionEnd(t *testing.T) {
 	assert.True(t, result.Allowed)
 }
 
+func TestExecuteOnUserInput(t *testing.T) {
+	t.Parallel()
+
+	config := &Config{
+		OnUserInput: []Hook{
+			{Type: HookTypeCommand, Command: "echo 'user input needed'", Timeout: 5},
+		},
+	}
+
+	exec := NewExecutor(config, t.TempDir(), nil)
+	input := &Input{
+		SessionID: "test-session",
+	}
+
+	result, err := exec.ExecuteOnUserInput(t.Context(), input)
+	require.NoError(t, err)
+	assert.True(t, result.Allowed)
+}
+
 func TestExecuteHooksWithContextCancellation(t *testing.T) {
 	t.Parallel()
 
diff --git a/pkg/hooks/types.go b/pkg/hooks/types.go
@@ -28,6 +28,10 @@ const (
 	// SessionEnd is triggered when a session terminates.
 	// Can perform cleanup, logging, persist session state.
 	EventSessionEnd EventType = "session_end"
+
+	// OnUserInput is triggered when the agent needs input from the user.
+	// Can log, notify, or perform actions before user interaction.
+	EventOnUserInput EventType = "on_user_input"
 )
 
 // HookType represents the type of hook action
@@ -81,14 +85,18 @@ type Config struct {
 
 	// SessionEnd hooks run when a session ends
 	SessionEnd []Hook `json:"session_end,omitempty" yaml:"session_end,omitempty"`
+
+	// OnUserInput hooks run when the agent needs user input
+	OnUserInput []Hook `json:"on_user_input,omitempty" yaml:"on_user_input,omitempty"`
 }
 
 // IsEmpty returns true if no hooks are configured
 func (c *Config) IsEmpty() bool {
 	return len(c.PreToolUse) == 0 &&
 		len(c.PostToolUse) == 0 &&
 		len(c.SessionStart) == 0 &&
-		len(c.SessionEnd) == 0
+		len(c.SessionEnd) == 0 &&
+		len(c.OnUserInput) == 0
 }
 
 // Input represents the JSON input passed to hooks via stdin
diff --git a/pkg/runtime/runtime.go b/pkg/runtime/runtime.go
@@ -615,6 +615,33 @@ func (r *LocalRuntime) getHooksExecutor(a *agent.Agent) *hooks.Executor {
 	return hooks.NewExecutor(hooksCfg, r.workingDir, r.env)
 }
 
+// executeOnUserInputHooks executes on-user-input hooks for the current agent
+func (r *LocalRuntime) executeOnUserInputHooks(ctx context.Context, sessionID, logContext string) {
+	a, _ := r.team.Agent(r.currentAgent)
+	if a == nil {
+		return
+	}
+
+	hooksExec := r.getHooksExecutor(a)
+	if hooksExec == nil || !hooksExec.HasOnUserInputHooks() {
+		return
+	}
+
+	slog.Debug("Executing on-user-input hooks", "context", logContext)
+	input := &hooks.Input{
+		SessionID: sessionID,
+		Cwd:       r.workingDir,
+	}
+
+	result, err := hooksExec.ExecuteOnUserInput(ctx, input)
+	if err != nil {
+		slog.Warn("On-user-input hook execution failed", "error", err)
+	} else {
+		slog.Debug("On-user-input hooks executed successfully")
+	}
+	_ = result // Hook result not used
+}
+
 // getAgentModelID returns the model ID for an agent, or empty string if no model is set.
 func getAgentModelID(a *agent.Agent) string {
 	if model := a.Model(); model != nil {
@@ -867,6 +894,8 @@ func (r *LocalRuntime) finalizeEventChannel(ctx context.Context, sess *session.S
 
 	events <- StreamStopped(sess.ID, r.currentAgent)
 
+	r.executeOnUserInputHooks(ctx, sess.ID, "stream stopped")
+
 	telemetry.RecordSessionEnd(ctx)
 }
 
@@ -1619,6 +1648,8 @@ func (r *LocalRuntime) askUserForConfirmation(
 	slog.Debug("Tools not approved, waiting for resume", "tool", toolName, "session_id", sess.ID)
 	events <- ToolCallConfirmation(toolCall, tool, a.Name())
 
+	r.executeOnUserInputHooks(ctx, sess.ID, "tool confirmation")
+
 	select {
 	case req := <-r.resumeChan:
 		switch req.Type {
@@ -2022,6 +2053,8 @@ func (r *LocalRuntime) elicitationHandler(ctx context.Context, req *mcp.ElicitPa
 		return tools.ElicitationResult{}, fmt.Errorf("no events channel available for elicitation")
 	}
 
+	r.executeOnUserInputHooks(ctx, "", "elicitation")
+
 	slog.Debug("Sending elicitation request event to client", "message", req.Message, "mode", req.Mode, "requested_schema", req.RequestedSchema, "url", req.URL)
 	slog.Debug("Elicitation request meta", "meta", req.Meta)
 

Original file line number	Diff line number	Diff line change
`@@ -390,6 +390,13 @@`
`390`	`390`	`"items": {`
`391`	`391`	`"$ref": "#/definitions/HookDefinition"`
`392`	`392`	`}`
	`393`	`+ },`
	`394`	`+ "on_user_input": {`
	`395`	`+ "type": "array",`
	`396`	`+ "description": "Hooks that run when the agent needs user input. Can send notifications or log events.",`
	`397`	`+ "items": {`
	`398`	`+ "$ref": "#/definitions/HookDefinition"`
	`399`	`+ }`
`393`	`400`	`}`
`394`	`401`	`},`
`395`	`402`	`"additionalProperties": false`
Original file line number	Diff line number	Diff line change
`@@ -1211,6 +1211,9 @@ type HooksConfig struct {`
`1211`	`1211`
`1212`	`1212`	`// SessionEnd hooks run when a session ends`
`1213`	`1213`	SessionEnd []HookDefinition `json:"session_end,omitempty" yaml:"session_end,omitempty"`
	`1214`	`+`
	`1215`	`+ // OnUserInput hooks run when the agent needs user input`
	`1216`	+ OnUserInput []HookDefinition `json:"on_user_input,omitempty" yaml:"on_user_input,omitempty"`
`1214`	`1217`	`}`
`1215`	`1218`
`1216`	`1219`	`// IsEmpty returns true if no hooks are configured`
`@@ -1221,7 +1224,8 @@ func (h *HooksConfig) IsEmpty() bool {`
`1221`	`1224`	`return len(h.PreToolUse) == 0 &&`
`1222`	`1225`	`len(h.PostToolUse) == 0 &&`
`1223`	`1226`	`len(h.SessionStart) == 0 &&`
`1224`		`- len(h.SessionEnd) == 0`
	`1227`	`+ len(h.SessionEnd) == 0 &&`
	`1228`	`+ len(h.OnUserInput) == 0`
`1225`	`1229`	`}`
`1226`	`1230`
`1227`	`1231`	`// HookMatcherConfig represents a hook matcher with its hooks.`
`@@ -1277,6 +1281,13 @@ func (h *HooksConfig) validate() error {`
`1277`	`1281`	`}`
`1278`	`1282`	`}`
`1279`	`1283`
	`1284`	`+ // Validate OnUserInput hooks`
	`1285`	`+ for i, hook := range h.OnUserInput {`
	`1286`	`+ if err := hook.validate("on_user_input", i); err != nil {`
	`1287`	`+ return err`
	`1288`	`+ }`
	`1289`	`+ }`
	`1290`	`+`
`1280`	`1291`	`return nil`
`1281`	`1292`	`}`
`1282`	`1293`
Original file line number	Diff line number	Diff line change
`@@ -62,5 +62,14 @@ func FromConfig(cfg latest.HooksConfig) Config {`
`62`	`62`	`})`
`63`	`63`	`}`
`64`	`64`
	`65`	`+ // Convert OnUserInput`
	`66`	`+ for _, h := range cfg.OnUserInput {`
	`67`	`+ result.OnUserInput = append(result.OnUserInput, Hook{`
	`68`	`+ Type: HookType(h.Type),`
	`69`	`+ Command: h.Command,`
	`70`	`+ Timeout: h.Timeout,`
	`71`	`+ })`
	`72`	`+ }`
	`73`	`+`
`65`	`74`	`return result`
`66`	`75`	`}`