1 files changed, 32 insertions, 2 deletions

diff --git a/makima/src/llm/contract_tools.rs b/makima/src/llm/contract_tools.rs
index 7a3d09a..07de1fe 100644
--- a/makima/src/llm/contract_tools.rs
+++ b/makima/src/llm/contract_tools.rs
@@ -203,7 +203,7 @@ pub static CONTRACT_TOOLS: once_cell::sync::Lazy<Vec<Tool>> = once_cell::sync::L
         },
         Tool {
             name: "advance_phase".to_string(),
-            description: "Advance the contract to the NEXT phase in sequence. Phases progress: research -> specify -> plan -> execute -> review. You can ONLY advance forward one step. Always use suggest_phase_transition first to check readiness and find the correct next phase.".to_string(),
+            description: "Advance the contract to the NEXT phase in sequence. Phases progress: research -> specify -> plan -> execute -> review. You can ONLY advance forward one step. Always use suggest_phase_transition first to check readiness and find the correct next phase. If the contract has phase_guard enabled, this will first return a pending_confirmation status with phase deliverables for user review. Call again with confirmed=true to complete the transition, or with feedback to request changes.".to_string(),
             parameters: json!({
                 "type": "object",
                 "properties": {
@@ -211,6 +211,14 @@ pub static CONTRACT_TOOLS: once_cell::sync::Lazy<Vec<Tool>> = once_cell::sync::L
                         "type": "string",
                         "enum": ["specify", "plan", "execute", "review"],
                         "description": "The next phase to transition to. Must be exactly one step ahead of current phase (e.g., research->specify, specify->plan, plan->execute, execute->review)"
+                    },
+                    "confirmed": {
+                        "type": "boolean",
+                        "description": "Set to true to confirm the phase transition when phase_guard is enabled. If omitted or false, returns deliverables for review."
+                    },
+                    "feedback": {
+                        "type": "string",
+                        "description": "User feedback when requesting changes instead of confirming the transition. The feedback will be passed back to the task to address."
                     }
                 },
                 "required": ["new_phase"]
@@ -500,7 +508,13 @@ pub enum ContractToolRequest {
     // Phase management
     GetPhaseInfo,
     SuggestPhaseTransition,
-    AdvancePhase { new_phase: String },
+    AdvancePhase {
+        new_phase: String,
+        /// Whether the user has confirmed the phase transition (for phase_guard)
+        confirmed: bool,
+        /// User feedback when they request changes instead of confirming
+        feedback: Option<String>,
+    },
 
     // Repository management
     ListDaemonDirectories,
@@ -870,12 +884,28 @@ fn parse_advance_phase(call: &super::tools::ToolCall) -> ContractToolExecutionRe
         return error_result("Invalid phase. Must be one of: research, specify, plan, execute, review");
     }
 
+    // Parse optional confirmed flag (defaults to false for initial phase_guard check)
+    let confirmed = call
+        .arguments
+        .get("confirmed")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
+    // Parse optional feedback (for when user requests changes)
+    let feedback = call
+        .arguments
+        .get("feedback")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+
     ContractToolExecutionResult {
         success: true,
         message: format!("Advancing to '{}' phase...", new_phase),
         data: None,
         request: Some(ContractToolRequest::AdvancePhase {
             new_phase: new_phase.to_string(),
+            confirmed,
+            feedback,
         }),
         pending_questions: None,
     }