fix: restore boolean return type for isApproved and add metadata.status fallback

- ResumePlanResponse.isApproved(): Boolean -> boolean (binary compat fix)
- Add metadata.status check in executePlan status extraction
- Status precedence: data.status > metadata.status > top-level > default
- Add 3 tests: nested failure, metadata fallback, null approved handling

Author: saurabhjain1592

src/main/java/com/getaxonflow/sdk/AxonFlow.java

@@ -832,6 +832,7 @@ private PlanResponse parseExecutePlanResponse(Response response, String planId)
         String result = (String) agentResponse.get("result");
 
         // Read status from response data (e.g., "awaiting_approval" for confirm mode)
+        // Precedence: data.status > metadata.status > top-level status > "completed"
         String status = "completed";
         Object dataObj2 = agentResponse.get("data");
         if (dataObj2 instanceof Map) {
@@ -842,6 +843,17 @@ private PlanResponse parseExecutePlanResponse(Response response, String planId)
                 status = (String) dataStatus;
             }
         }
+        if ("completed".equals(status)) {
+            Object metaObj = agentResponse.get("metadata");
+            if (metaObj instanceof Map) {
+                @SuppressWarnings("unchecked")
+                Map<String, Object> metaMap = (Map<String, Object>) metaObj;
+                Object metaStatus = metaMap.get("status");
+                if (metaStatus instanceof String && !((String) metaStatus).isEmpty()) {
+                    status = (String) metaStatus;
+                }
+            }
+        }
         if ("completed".equals(status)) {
             Object topStatus = agentResponse.get("status");
             if (topStatus instanceof String && !((String) topStatus).isEmpty()) {

src/main/java/com/getaxonflow/sdk/types/ResumePlanResponse.java

@@ -99,10 +99,10 @@ public String getWorkflowId() {
     /**
      * Returns whether the plan was approved to continue.
      *
-     * @return true if the plan was approved, null if not applicable
+     * @return true if the plan was approved, false if not approved or not applicable
      */
-    public Boolean isApproved() {
-        return approved;
+    public boolean isApproved() {
+        return Boolean.TRUE.equals(approved);
     }
 
     /**

src/test/java/com/getaxonflow/sdk/AxonFlowTest.java

@@ -418,6 +418,46 @@ void getPlanStatusShouldReturnStatus() {
         assertThat(response.getStatus()).isEqualTo("pending");
     }
 
+    @Test
+    @DisplayName("executePlan should throw when nested data.success is false")
+    void executePlanShouldThrowOnNestedDataFailure() {
+        stubFor(post(urlEqualTo("/api/request"))
+            .willReturn(aResponse()
+                .withStatus(200)
+                .withHeader("Content-Type", "application/json")
+                .withBody("{\"success\":true,\"data\":{\"success\":false,\"error\":\"Step 2 timed out\"}}")));
+
+        assertThatThrownBy(() -> axonflow.executePlan("plan_fail"))
+            .isInstanceOf(PlanExecutionException.class)
+            .hasMessageContaining("Step 2 timed out");
+    }
+
+    @Test
+    @DisplayName("executePlan should use metadata.status when data.status is absent")
+    void executePlanShouldFallbackToMetadataStatus() {
+        // No data.status, but metadata.status is present — should use metadata.status
+        stubFor(post(urlEqualTo("/api/request"))
+            .willReturn(aResponse()
+                .withStatus(200)
+                .withHeader("Content-Type", "application/json")
+                .withBody("{\"success\":true,\"result\":\"done\",\"metadata\":{\"status\":\"awaiting_approval\"}}")));
+
+        PlanResponse response = axonflow.executePlan("plan_meta");
+
+        assertThat(response.getStatus()).isEqualTo("awaiting_approval");
+    }
+
+    @Test
+    @DisplayName("isApproved should return false when approved field is null")
+    void isApprovedShouldReturnFalseWhenNull() {
+        // Construct a ResumePlanResponse with null approved field
+        ResumePlanResponse response = new ResumePlanResponse(
+            "plan_123", "wf_456", "in_progress", null, "Pending review", 2, "Step 2", 5);
+
+        // Must return false (not throw NPE)
+        assertThat(response.isApproved()).isFalse();
+    }
+
     // ========================================================================
     // Orchestrator Health Check
     // ========================================================================