fix: resolve Allow/Deny buttons not triggering CLI approval (#106)

* fix: resolve Allow/Deny buttons not triggering CLI approval (farouqaldori#98)

Four fixes addressing the permission approval flow not reaching the CLI:

1. Generate fallback UUID when tool_use_id is missing from PermissionRequest
   events, preventing silent socket closure that left UI buttons unable to
   send approval back to the CLI.

2. Increase socket read window from 200ms to 2s with early exit on complete
   JSON, preventing truncated reads on large tool_input payloads.

3. Flush stdout in Python hook script to ensure hookSpecificOutput JSON
   reaches Claude Code without buffering delays.

4. Guard against race condition where Stop/SessionEnd events clean up
   permissions before the user has time to respond (2s grace period).

Also includes enhanced diagnostic logging (Swift .warning level for failures,
conditional stderr logging in Python via CLAUDE_ISLAND_DEBUG=1) and fixes
for @inline(always) -> @inline(__always) and .signaled -> .unhandledException
build compatibility issues.

Closes farouqaldori#98

* fix: resolve CI failures before code review (PR #106)

- Revert TerminationStatus case from `.unhandledException` to `.signaled` to match swift-subprocess 0.4 API (CI resolves latest compatible version)
- Bump swift-subprocess minimum version constraint from 0.2.0 to 0.4.0 to ensure consistent API resolution locally and in CI

* fix: address code review comments (PR #106, iteration 1)

- readClientData: remove 10ms quiet-period early break and require
  complete-JSON validation (looksLikeCompleteJSON) before exiting the
  poll loop; widen poll slice to 100ms within the existing 2s cap.
  Prevents truncation of multi-packet hook payloads that could
  reintroduce the "Processing…" hang from farouqaldori#98.
- sendPermissionResponse + sendPermissionResponseBySession: introduce
  writeAllBytes helper that loops until all bytes are sent, retries
  on EINTR, and waits for POLLOUT on EAGAIN/EWOULDBLOCK within a 2s
  deadline. permissionFailureHandler is now only invoked on truly
  unrecoverable writes, eliminating spurious failures on partial
  writes to the non-blocking socket.

* fix: address code review comments (PR #106, iteration 2)

- claude-island-state.py send_event: replace single sock.recv(4096)
  with an EOF-accumulating loop so permission responses that span
  multiple kernel reads (normal on SOCK_STREAM; guaranteed when the
  `reason` field pushes the JSON past 4KB) are decoded correctly.
  The Swift side (writeAllBytes + close) uses EOF as the terminator,
  so recv-until-zero is the authoritative contract. Eliminates the
  silent fallback to "ask" that caused intermittent Allow/Deny loss.

* fix: address code review comments (PR #106, iteration 3)

- claude-island-state.py send_event: include UnicodeDecodeError in the
  except tuple around response.decode()/json.loads. Without it, a
  mid-multibyte UTF-8 truncation would crash the hook process and skip
  the intended None → "{}"/"ask" fallback in handle_permission_response.

* fix: address code review comments (PR #106, iteration 4)

- HookSocketServer.acceptConnection: update stale "200ms" comment to
  reflect readClientData's current 2s cap, so the accept-queue
  head-of-line risk is accurately documented.

* fix: address code review comments (PR #106, iteration 5)

- cleanupPendingPermissions: schedule a follow-up cleanup for entries
  skipped under the <2s age guard (via queue.asyncAfter) so Stop events
  on brand-new permissions no longer leave the Python hook blocked on
  its 300s recv. Retry atomically removes the entry only if the
  toolUseID still maps to the same sessionID, guarding against session
  reuse and double-close races.
- readClientData poll loop: explicitly handle POLLHUP/POLLERR/POLLNVAL
  to exit promptly on peer close or invalid fd; previously the loop
  spun until the 2s cap when poll returned >0 without POLLIN. POLLIN
  is still checked first so pending data is drained before exit.
- writeAllBytes: assign EIO to finalErrno when write() returns 0 (POSIX
  doesn't guarantee errno is meaningful in that case), so logs and
  diagnostics show a stable code instead of a stale/0 value. Move the
  errno capture for negative returns into the n<0 branch where it's
  defined to be valid.

* fix: address code review comments (PR #106, iteration 6)

- readClientData: retry read() on EINTR instead of treating it as a
  fatal error. Symmetric with the existing poll() EINTR handling;
  prevents signal-induced truncation of multi-packet JSON payloads.
- cleanupPendingPermissionsRetry: stop invoking permissionFailureHandler.
  Stop hook events are authoritative for session phase (drive to .idle
  via determinePhase); letting the deferred retry fire the handler ~2s
  later could override .idle back to .waitingForApproval via
  SessionStore.processSocketFailure's findNextPendingTool. Both cleanup
  paths (main + retry) are now silent FD-close, consistent with Stop
  owning phase management. The handler still fires from the genuine
  failure sites: handlePermissionSocketDisconnect, cleanupTimedOutPermission,
  and sendPermissionResponse* write-failure branches.

* fix: address code review comments (PR #106, iteration 7)

- cleanupPendingPermissions main loop: call markPermissionResponded
  alongside the pendingPermissions removal, matching all other
  removal sites (cleanupPendingPermissionsRetry, cleanupSpecificPermission,
  handlePermissionSocketDisconnect, sendPermissionResponse*). Late
  approve/deny responses for a Stop-cancelled session now classify
  as .alreadyResponded (quiet) instead of .notFound (warning), and
  dedupe behavior is consistent across all paths.

* fix: address code review comments (PR #106, iteration 8)

- claude-island-state.py send_event: make the debug log path resilient
  to malformed bytes by using response.decode(errors='replace') in the
  _log f-string (which is evaluated eagerly regardless of DEBUG flag).
  Pass response bytes directly to json.loads, which handles UTF-8/16/32
  BOM detection itself, eliminating the redundant strict decode. Debug
  mode can no longer perturb functional parsing. The except tuple with
  UnicodeDecodeError is retained as a defensive net.

---------

Co-authored-by: Taylor Watson <taylor.watson@soti.net>
Co-authored-by: engels74 <141435164+engels74@users.noreply.github.com>

Author: 3 people

ClaudeIsland.xcodeproj/project.pbxproj

@@ -386,7 +386,7 @@
 			repositoryURL = "https://github.com/swiftlang/swift-subprocess";
 			requirement = {
 				kind = upToNextMajorVersion;
-				minimumVersion = 0.2.0;
+				minimumVersion = 0.4.0;
 			};
 		};
 		FD33FD712EDF32D7002A6548 /* XCRemoteSwiftPackageReference "swift-markdown" */ = {

ClaudeIsland/Core/NotchGeometry.swift

@@ -38,7 +38,7 @@ struct NotchGeometry: Sendable {
     }
 
     /// Check if a point is in the notch area (with padding for easier interaction)
-    @inline(always)
+    @inline(__always)
     func isPointInNotch(_ point: CGPoint) -> Bool {
         self.notchScreenRect.insetBy(dx: -10, dy: -5).contains(point)
     }
@@ -49,7 +49,7 @@ struct NotchGeometry: Sendable {
     }
 
     /// Check if a point is outside the opened panel (for closing)
-    @inline(always)
+    @inline(__always)
     func isPointOutsidePanel(_ point: CGPoint, size: CGSize) -> Bool {
         !self.openedScreenRect(for: size).contains(point)
     }

ClaudeIsland/Models/SessionPhase.swift

@@ -97,7 +97,7 @@ nonisolated enum SessionPhase: Sendable {
     // swiftlint:disable attributes
 
     /// Whether this phase indicates the session needs user attention
-    @inline(always) var needsAttention: Bool {
+    @inline(__always) var needsAttention: Bool {
         switch self {
         case .waitingForApproval,
              .waitingForInput:
@@ -108,7 +108,7 @@ nonisolated enum SessionPhase: Sendable {
     }
 
     /// Whether this phase indicates active processing
-    @inline(always) var isActive: Bool {
+    @inline(__always) var isActive: Bool {
         switch self {
         case .processing,
              .compacting:
@@ -119,7 +119,7 @@ nonisolated enum SessionPhase: Sendable {
     }
 
     /// Whether this is a waitingForApproval phase
-    @inline(always) nonisolated var isWaitingForApproval: Bool {
+    @inline(__always) nonisolated var isWaitingForApproval: Bool {
         if case .waitingForApproval = self {
             return true
         }

ClaudeIsland/Resources/claude-island-state.py

@@ -38,6 +38,14 @@
 from pathlib import Path
 from typing import NotRequired, TypedDict, TypeIs, cast
 
+_DEBUG = os.environ.get("CLAUDE_ISLAND_DEBUG") == "1"
+
+
+def _log(msg: str, /) -> None:
+    """Log to stderr when CLAUDE_ISLAND_DEBUG=1. Does not affect stdout JSON."""
+    if _DEBUG:
+        print(f"[claude-island] {msg}", file=sys.stderr, flush=True)
+
 
 # TypedDict definitions for JSON structures
 class HookEventData(TypedDict, total=False):
@@ -349,15 +357,37 @@ def send_event(state: SessionState, /) -> PermissionResponse | None:
         with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
             sock.settimeout(CONNECT_TIMEOUT_SECONDS)
             sock.connect(str(SOCKET_PATH))
-            sock.sendall(json.dumps(state.to_dict()).encode())
+            _log(f"connected to {SOCKET_PATH}")
+            payload = json.dumps(state.to_dict()).encode()
+            sock.sendall(payload)
+            _log(
+                f"sent {len(payload)} bytes (event={state.event}, status={state.status})"
+            )
             if state.status == "waiting_for_approval":
                 sock.settimeout(PERMISSION_RECV_TIMEOUT_SECONDS)
-                if response := sock.recv(4096):
-                    parsed = cast(object, json.loads(response.decode()))
+                _log("waiting for permission response...")
+                # Accumulate bytes until the Swift side closes the socket (EOF).
+                # SOCK_STREAM may split the JSON payload across multiple recv()
+                # calls, and longer `reason` strings can exceed a single 4KB
+                # chunk. Swift's sendPermissionResponse always close(2)s the
+                # client fd after writing, so EOF is the authoritative terminator.
+                chunks: list[bytes] = []
+                while chunk := sock.recv(4096):
+                    chunks.append(chunk)
+                response = b"".join(chunks)
+                if response:
+                    _log(
+                        f"received {len(response)} bytes: {response.decode(errors='replace')}"
+                    )
+                    parsed = cast(object, json.loads(response))
                     if is_permission_response(parsed):
                         return parsed
+                    _log(f"response failed validation: {parsed}")
+                else:
+                    _log("empty response (socket closed)")
             return None
-    except OSError, json.JSONDecodeError:
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        _log(f"error: {exc}")
         return None
 
 
@@ -461,7 +491,7 @@ def handle_permission_response(response: PermissionResponse | None, /) -> None:
     """
     if not response:
         # No response or "ask" - let Claude Code show its normal UI
-        print("{}")
+        print("{}", flush=True)
         return
 
     decision = response.get("decision", "ask")
@@ -475,7 +505,8 @@ def handle_permission_response(response: PermissionResponse | None, /) -> None:
                     "decision": {"behavior": "allow"},
                 }
             }
-            print(json.dumps(output))
+            _log(f"allow -> {json.dumps(output)}")
+            print(json.dumps(output), flush=True)
             sys.exit(0)
 
         case "deny":
@@ -488,12 +519,14 @@ def handle_permission_response(response: PermissionResponse | None, /) -> None:
                     },
                 }
             }
-            print(json.dumps(output))
+            _log(f"deny -> {json.dumps(output)}")
+            print(json.dumps(output), flush=True)
             sys.exit(0)
 
         case _decision:
             # "ask" or unknown - let Claude Code show its normal UI
-            print("{}")
+            _log(f"unknown decision: {_decision}")
+            print("{}", flush=True)
 
 
 def main() -> None:
@@ -514,9 +547,13 @@ def main() -> None:
     # Determine status early (pure computation, no I/O)
     status, extras = determine_status(event, data)
 
+    _log(
+        f"event={event} session={session_id[:8]} status={status} has_tool_use_id={'tool_use_id' in extras}"
+    )
+
     # Skip certain events (e.g. stale PreToolUse registration)
     if status == "skip":
-        print("{}")
+        print("{}", flush=True)
         sys.exit(0)
 
     # Resolve PID, TTY, build state
@@ -545,7 +582,7 @@ def main() -> None:
     if status == "waiting_for_approval":
         handle_permission_response(response)
     else:
-        print("{}")
+        print("{}", flush=True)
 
 
 if __name__ == "__main__":