feat(orchestrator): add human action reporting

- define the `report_human_action` tool/schema/parser/response so the orchestrator can request manual intervention and describe it in the tool log
- track reported human actions inside `TaskManager`, log them, and format a highlighted reminder when the run finishes
- update orchestrator logging/mocks and prompts to surface the “human action recorded” message so users know when manual steps remain

Author: dbmrq

prompts/orchestrator.txt

@@ -37,6 +37,16 @@ Skip tasks when they are:
 - No longer relevant to the goal
 - Blocked by external factors that cannot be resolved
 
+## HUMAN ACTION REPORTING:
+
+When you encounter work that cannot be automated, use `report_human_action()` to record what the user needs to do manually. Examples:
+- Creating API tokens or secrets (requires web interface)
+- Setting up external service accounts
+- Making decisions that require human judgment
+- Pushing git tags or creating releases (if not appropriate to automate)
+
+Provide clear, actionable descriptions. These will be displayed prominently at the end of the run so the user knows exactly what manual steps remain.
+
 ## REFLECTION & ADAPTATION:
 
 After each batch of agents completes, reflect on their results before proceeding:

prompts/planner.txt

@@ -23,4 +23,5 @@ You are part of a multi-agent orchestration pipeline. Your job is to decompose l
 - Your plan will be followed by AI agents, not humans. Keep that in mind. This means human time frames and effort limitations don't matter. Large refactors are possible if justified. And instructions should be clearest for the things that AI agents easily get wrong.
 - If you are already provided with a full plan, or if you find one in the codebase, adjust it to fit into the criteria above, then use the MCP tools to record it.
 - Try to stay within ~50% of your context. If you're asked to plan for something that would require more than that, either (1) create very broad tasks that encompass the whole request, or (2) create tasks for the immediate next steps, and then create a single broad task for everything else. The broad tasks will be further decomposed by other agents following the same process.
+- For requests that encompass many different files, consider ways to automate the changes. E.g.: a first task could be to create a script that applies changes to the whole codebase; a second task could be to run the script, verify the results and fix any undesirable side-effects; a third task could be to look only at remaining files to check if there was something that the script didn't catch.
 - When you are done, **always** use the provided MCP tool to signal completion.

src/agents/config.rs

@@ -102,6 +102,7 @@ pub const ORCHESTRATOR_CONFIG: AgentToolConfig = AgentToolConfig {
         "create_task",
         "skip_tasks",
         "list_tasks",
+        "report_human_action",
     ],
     removed_auggie_tools: &[
         // No file editing - orchestrator delegates to implementers

src/app/orchestrator.rs

@@ -554,6 +554,12 @@ impl App {
                                 .await;
                             let _ = response_tx.send(response);
                         }
+                        ToolCall::ReportHumanAction { ref description, ref task_id } => {
+                            let response = self
+                                .handle_report_human_action(description, task_id.as_ref(), &request.request_id, writer)
+                                .await;
+                            let _ = response_tx.send(response);
+                        }
                     }
                 }
 
@@ -772,6 +778,41 @@ impl App {
         response
     }
 
+    /// Handle the `report_human_action` tool call.
+    ///
+    /// Records an action that requires manual user intervention.
+    async fn handle_report_human_action(
+        &self,
+        description: &str,
+        task_id: Option<&String>,
+        request_id: &str,
+        writer: &mut AgentWriter,
+    ) -> ToolResponse {
+        let depth = self.current_scope.depth();
+        let preview = truncate_for_log(description, 50);
+        let _ = writer
+            .write_mcp_tool_call("report_human_action", &preview)
+            .await;
+        tracing::info!("[L{}] 📋 report_human_action: {}", depth, preview);
+
+        // Add to task manager
+        {
+            let mut tm = self.task_manager.write().await;
+            tm.add_human_action(description.to_string(), task_id.cloned());
+        }
+
+        let response = ToolResponse::success(
+            request_id.to_string(),
+            "Human action recorded. It will be displayed prominently at the end of the run."
+                .to_string(),
+        );
+        let _ = writer
+            .write_mcp_tool_result("report_human_action", true, "Action recorded")
+            .await;
+
+        response
+    }
+
     /// Handle the `skip_tasks` tool call.
     ///
     /// Marks tasks as skipped if they are in `NotStarted` status.
@@ -839,11 +880,14 @@ impl App {
                             errors.push(msg);
                         }
                         TaskStatus::Failed { .. } => {
-                            let msg = format!(
-                                "Task '{task_id}' has already failed and cannot be skipped"
+                            // Failed tasks don't need to be skipped - they already have a
+                            // definitive status. This is not an error, just informational.
+                            tracing::info!(
+                                "ℹ️ Task '{}' has already failed (no skip needed)",
+                                task_id
                             );
-                            tracing::warn!("⚠️ {}", msg);
-                            errors.push(msg);
+                            // Don't add to errors - failed tasks are already accounted for
+                            // in task reconciliation, so the orchestrator can proceed.
                         }
                         TaskStatus::Skipped { .. } => {
                             tracing::info!("⏭️ Task '{}' is already skipped", task_id);

src/main.rs

@@ -759,6 +759,14 @@ async fn main() -> Result<()> {
         }
     }
 
+    // Print human action items if any exist
+    {
+        let task_manager = app.task_manager().read().await;
+        if let Some(human_actions) = task_manager.format_human_actions_required() {
+            println!("{human_actions}");
+        }
+    }
+
     if result.success {
         println!("\n✅ Task completed successfully!");
     } else {

src/mcp_server/handlers/mod.rs

@@ -110,7 +110,8 @@ fn handle_tools_list(id: Option<&Value>) -> Value {
                     tool_schemas::complete_schema_orchestrator(),
                     tool_schemas::create_task_schema_orchestrator(),
                     tool_schemas::skip_tasks_schema(),
-                    tool_schemas::list_tasks_schema()
+                    tool_schemas::list_tasks_schema(),
+                    tool_schemas::report_human_action_schema()
                 ]
             })
         }
@@ -197,6 +198,16 @@ async fn handle_tool_call(
             Ok(tc) => tc,
             Err(msg) => return Ok(Some(invalid_params_error(id.as_ref(), "list_tasks", msg))),
         },
+        "report_human_action" => match tool_parsing::parse_report_human_action(arguments) {
+            Ok(tc) => tc,
+            Err(msg) => {
+                return Ok(Some(invalid_params_error(
+                    id.as_ref(),
+                    "report_human_action",
+                    msg,
+                )))
+            }
+        },
         _ => {
             tracing::warn!("⚠️  Unknown tool requested: {}", name);
             return Ok(Some(method_not_found_error(
@@ -210,6 +221,7 @@ async fn handle_tool_call(
                     "set_goal",
                     "skip_tasks",
                     "list_tasks",
+                    "report_human_action",
                 ],
             )));
         }
@@ -366,7 +378,7 @@ mod tests {
 
         let tool_names = extract_tool_names(&response);
 
-        // Orchestrator should have: decompose, spawn_agents, complete, create_task, skip_tasks
+        // Orchestrator should have: decompose, spawn_agents, complete, create_task, skip_tasks, list_tasks, report_human_action
         assert!(
             tool_names.contains("decompose"),
             "Orchestrator should have decompose tool"
@@ -391,12 +403,16 @@ mod tests {
             tool_names.contains("list_tasks"),
             "Orchestrator should have list_tasks tool"
         );
+        assert!(
+            tool_names.contains("report_human_action"),
+            "Orchestrator should have report_human_action tool"
+        );
 
         // Verify exact count
         assert_eq!(
             tool_names.len(),
-            6,
-            "Orchestrator should have exactly 6 tools, got: {tool_names:?}",
+            7,
+            "Orchestrator should have exactly 7 tools, got: {tool_names:?}",
         );
     }
 

src/mcp_server/handlers/response.rs

@@ -138,6 +138,9 @@ pub fn build_response_text_with_state(
         ToolCall::ListTasks { status_filter } => {
             build_list_tasks_response(status_filter.as_deref(), response)
         }
+        ToolCall::ReportHumanAction { description, .. } => {
+            build_report_human_action_response(description, response)
+        }
     }
 }
 
@@ -162,6 +165,28 @@ fn build_list_tasks_response(status_filter: Option<&str>, response: &ToolRespons
     }
 }
 
+fn build_report_human_action_response(description: &str, response: &ToolResponse) -> String {
+    if response.success {
+        let preview = if description.len() > 60 {
+            format!("{}...", &description[..57])
+        } else {
+            description.to_string()
+        };
+        format!(
+            "✅ Human action recorded: \"{preview}\"\n\n\
+             This will be displayed prominently at the end of the run."
+        )
+    } else {
+        let error_msg = response.error.as_deref().unwrap_or(&response.summary);
+        format!(
+            "❌ Failed to record human action: {error_msg}\n\n\
+             ## How to Fix\n\
+             - Ensure the description is a non-empty string\n\
+             - Try calling the tool again with a valid description"
+        )
+    }
+}
+
 fn build_decompose_response(
     task_id: Option<&String>,
     task: Option<&String>,

src/mcp_server/handlers/tool_parsing.rs

@@ -188,3 +188,23 @@ pub fn parse_list_tasks(arguments: &serde_json::Map<String, Value>) -> ParseResu
 
     Ok(ToolCall::ListTasks { status_filter })
 }
+
+/// Parse the `report_human_action` tool call arguments.
+pub fn parse_report_human_action(arguments: &serde_json::Map<String, Value>) -> ParseResult {
+    let description = if let Some(d) = arguments.get("description").and_then(|v| v.as_str()) {
+        d.to_string()
+    } else {
+        tracing::warn!("⚠️  report_human_action tool missing 'description' argument");
+        return Err("requires 'description' string argument");
+    };
+
+    let task_id = arguments
+        .get("task_id")
+        .and_then(|v| v.as_str())
+        .map(String::from);
+
+    Ok(ToolCall::ReportHumanAction {
+        description,
+        task_id,
+    })
+}

src/mcp_server/handlers/tool_schemas.rs

@@ -229,7 +229,7 @@ pub fn create_task_schema_orchestrator() -> Value {
 pub fn skip_tasks_schema() -> Value {
     json!({
         "name": "skip_tasks",
-        "description": "<usecase>Skip one or more tasks that are no longer needed.</usecase>\n<instructions>Use this when tasks become unnecessary (e.g., already done by another task, no longer relevant, or blocked permanently). Skipped tasks will not be executed and will be marked as skipped in the plan.</instructions>\n<on_error>If a task_id is not found, use list_tasks() to see available task IDs. If a task cannot be skipped because it's already completed or in progress, no action is needed - the task will proceed as planned. Provide a reason to help future agents understand why the task was skipped.</on_error>",
+        "description": "<usecase>Skip one or more tasks that are no longer needed.</usecase>\n<instructions>Use this when tasks become unnecessary (e.g., already done by another task, no longer relevant, or blocked permanently). Skipped tasks will not be executed and will be marked as skipped in the plan.</instructions>\n<on_error>If a task_id is not found, use list_tasks() to see available task IDs. If a task cannot be skipped because it's already completed, in progress, or has already failed, no action is needed - the task already has a definitive status. Failed tasks do not need to be skipped; they are already accounted for in task reconciliation. Provide a reason to help future agents understand why the task was skipped.</on_error>",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -266,3 +266,25 @@ pub fn list_tasks_schema() -> Value {
         }
     })
 }
+
+/// Generate the `report_human_action` tool definition.
+pub fn report_human_action_schema() -> Value {
+    json!({
+        "name": "report_human_action",
+        "description": "<usecase>Report that something requires manual user intervention.</usecase>\n<instructions>Use this when you encounter work that cannot be automated and needs the user to take action manually. Examples: creating API tokens, setting up external services, making decisions that require human judgment, pushing git tags. The description should be clear and actionable - tell the user exactly what they need to do. These will be prominently displayed at the end of the run.</instructions>\n<on_error>If the description is too vague, be more specific about what action is needed, where to do it, and why it's necessary.</on_error>",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "Clear, actionable description of what the user needs to do manually. Include specific steps if possible."
+                },
+                "task_id": {
+                    "type": "string",
+                    "description": "Optional task ID this action relates to (e.g., 'task003'). Helps provide context."
+                }
+            },
+            "required": ["description"]
+        }
+    })
+}

src/mcp_server/server.rs

@@ -369,11 +369,11 @@ mod tests {
         let resp = response.unwrap();
         let tools = resp["result"]["tools"].as_array().unwrap();
 
-        // Orchestrator has 6 tools: decompose, spawn_agents, complete, create_task, skip_tasks, list_tasks
+        // Orchestrator has 7 tools: decompose, spawn_agents, complete, create_task, skip_tasks, list_tasks, report_human_action
         assert_eq!(
             tools.len(),
-            6,
-            "Expected 6 orchestrator tools, got: {:?}",
+            7,
+            "Expected 7 orchestrator tools, got: {:?}",
             tools
                 .iter()
                 .map(|t| t["name"].as_str().unwrap_or("?"))
@@ -388,6 +388,7 @@ mod tests {
         assert!(tool_names.contains(&"create_task"));
         assert!(tool_names.contains(&"skip_tasks"));
         assert!(tool_names.contains(&"list_tasks"));
+        assert!(tool_names.contains(&"report_human_action"));
     }
 
     #[tokio::test]