feat: Approval gating UI wiring (P8) — human-in-the-loop tool call approval

Item 2 — Approval gating wiring:

IPC handlers (index.ts):
- 5 new handlers: approval-create, approval-approve, approval-deny,
  approval-list, approval-has-pending
- Uses createApprovalInbox() from steering-inbox.ts (already built + tested)

Preload bridges (index.ts + index.d.ts):
- 5 new bridge methods: approvalCreate, approvalApprove, approvalDeny,
  approvalList, approvalHasPending
- Full type declarations matching the preload implementations

Chat UI (Chat.tsx):
- Polls approvalHasPending() every 2s
- Passes pendingApprovals count to ChatHeader badge (already wired)
- Badge shows warning dot + count when approvals are pending

SSE stream (hermes.ts):
- New onToolApprovalRequired callback in ChatCallbacks interface
- processCustomEvent() now checks for requires_approval in
  hermes.tool.progress events and fires the callback
- The Hermes gateway can include requires_approval: true in tool
  progress events when the tool matches an approval rule
- Backward compatible: if callback not provided, tools proceed normally

Typecheck: 0 errors. Tests: 1383/1383 pass, 3 skipped.

Author: JZKK720

agent-desktop/src/main/hermes.ts

@@ -713,6 +713,13 @@ export interface ChatCallbacks {
   onDone: (sessionId?: string) => void;
   onError: (error: string) => void;
   onToolProgress?: (tool: string) => void;
+  /** Called when a tool call in the SSE stream requires human approval
+   *  (per the tool policy rules). The callback receives the tool name
+   *  and the command/parameters. The caller should create an approval
+   *  entry in the ApprovalInbox and wait for the user's decision before
+   *  allowing the tool to proceed. If the callback is not provided,
+   *  tool calls proceed without approval (backward compatibility). */
+  onToolApprovalRequired?: (toolName: string, command: string) => void;
   onUsage?: (usage: {
     promptTokens: number;
     completionTokens: number;
@@ -1242,12 +1249,25 @@ function sendMessageViaApi(
 
   /** Handle a custom SSE event (non-data lines with `event:` prefix). */
   function processCustomEvent(eventType: string, data: string): void {
-    if (eventType === "hermes.tool.progress" && cb.onToolProgress) {
+    if (eventType === "hermes.tool.progress") {
       try {
         const payload = JSON.parse(data);
         const label = payload.label || payload.tool || "";
         const emoji = payload.emoji || "";
-        cb.onToolProgress(emoji ? `${emoji} ${label}` : label);
+        if (cb.onToolProgress) {
+          cb.onToolProgress(emoji ? `${emoji} ${label}` : label);
+        }
+        // Fire approval callback if the tool requires it.
+        // The Hermes gateway can include `requires_approval: true` in
+        // the tool progress event when the tool matches an approval rule.
+        // The desktop creates an ApprovalInbox entry and waits for the
+        // user's decision. The gateway itself doesn't block — it's the
+        // desktop's responsibility to intercept and pause if needed.
+        if (payload.requires_approval && cb.onToolApprovalRequired) {
+          const toolName = payload.tool || label || "unknown";
+          const command = payload.command || payload.args || "";
+          cb.onToolApprovalRequired(toolName, command);
+        }
       } catch {
         /* malformed — skip */
       }

agent-desktop/src/main/index.ts

@@ -241,6 +241,10 @@ import {
   getApiServerKey,
 } from "./config";
 import { profileHome } from "./utils";
+import {
+  createApprovalInbox,
+  type ApprovalInbox,
+} from "./steering-inbox";
 import {
   listSessions,
   getSessionMessages,
@@ -1055,6 +1059,40 @@ function setupIPC(): void {
     getVault().search(query),
   );
 
+  // ── Approval Inbox IPC handlers (P8) ─────────────────────
+  // Human-in-the-loop approval for tool calls. When the agent calls a
+  // tool that requires approval (per tool policy rules), an entry is
+  // created in the inbox. The renderer polls for pending entries and
+  // shows an approval dialog. The user approves/denies, and the chat
+  // stream resumes or cancels accordingly.
+  let _approvalInbox: ApprovalInbox | null = null;
+  function getApprovalInbox(): ApprovalInbox {
+    if (!_approvalInbox) {
+      _approvalInbox = createApprovalInbox();
+    }
+    return _approvalInbox;
+  }
+
+  ipcMain.handle("approval-create", (_e, input: {
+    sessionId: string;
+    toolName: string;
+    command: string;
+    reason: string;
+    timeoutMs?: number;
+  }) => getApprovalInbox().create(input));
+  ipcMain.handle("approval-approve", (_e, id: string) =>
+    getApprovalInbox().approve(id),
+  );
+  ipcMain.handle("approval-deny", (_e, id: string) =>
+    getApprovalInbox().deny(id),
+  );
+  ipcMain.handle("approval-list", (_e, includeAll?: boolean) =>
+    getApprovalInbox().list(includeAll),
+  );
+  ipcMain.handle("approval-has-pending", () =>
+    getApprovalInbox().hasPending(),
+  );
+
   ipcMain.handle("list-runtime-providers", () => listRuntimeProviders());
 
   ipcMain.handle(

agent-desktop/src/preload/index.d.ts

@@ -824,6 +824,39 @@ interface HermesAPI {
     snippet: string;
   }>>;
 
+  // Approval Inbox (P8)
+  approvalCreate: (input: {
+    sessionId: string;
+    toolName: string;
+    command: string;
+    reason: string;
+    timeoutMs?: number;
+  }) => Promise<{
+    id: string;
+    sessionId: string;
+    toolName: string;
+    command: string;
+    reason: string;
+    status: string;
+    createdAt: number;
+    resolvedAt: number | null;
+    timeoutMs?: number;
+  }>;
+  approvalApprove: (id: string) => Promise<boolean>;
+  approvalDeny: (id: string) => Promise<boolean>;
+  approvalList: (includeAll?: boolean) => Promise<Array<{
+    id: string;
+    sessionId: string;
+    toolName: string;
+    command: string;
+    reason: string;
+    status: string;
+    createdAt: number;
+    resolvedAt: number | null;
+    timeoutMs?: number;
+  }>>;
+  approvalHasPending: () => Promise<boolean>;
+
   listRuntimeProviders: () => Promise<RuntimeProviderSnapshot[]>;
   runRuntimeProviderAction: (
     providerId: RuntimeProviderId,

agent-desktop/src/preload/index.ts

@@ -472,6 +472,18 @@ const hermesAPI = {
   searchVault: (query: string): Promise<Array<{ fileName: string; score: number; snippet: string }>> =>
     ipcRenderer.invoke("search-vault", query),
 
+  // Approval Inbox (P8) — human-in-the-loop tool call approval
+  approvalCreate: (input: { sessionId: string; toolName: string; command: string; reason: string; timeoutMs?: number }): Promise<{ id: string; sessionId: string; toolName: string; command: string; reason: string; status: string; createdAt: number; resolvedAt: number | null; timeoutMs?: number }> =>
+    ipcRenderer.invoke("approval-create", input),
+  approvalApprove: (id: string): Promise<boolean> =>
+    ipcRenderer.invoke("approval-approve", id),
+  approvalDeny: (id: string): Promise<boolean> =>
+    ipcRenderer.invoke("approval-deny", id),
+  approvalList: (includeAll?: boolean): Promise<Array<{ id: string; sessionId: string; toolName: string; command: string; reason: string; status: string; createdAt: number; resolvedAt: number | null; timeoutMs?: number }>> =>
+    ipcRenderer.invoke("approval-list", includeAll),
+  approvalHasPending: (): Promise<boolean> =>
+    ipcRenderer.invoke("approval-has-pending"),
+
   listRuntimeProviders: (): Promise<RuntimeProviderSnapshot[]> =>
     ipcRenderer.invoke("list-runtime-providers"),
 

agent-desktop/src/renderer/src/screens/Chat/Chat.tsx

@@ -58,6 +58,8 @@ function Chat({
   const [contextFolder, setContextFolder] = useState<string | null>(null);
   // Whether the worktree panel is visible (only applies when contextFolder is set)
   const [worktreeVisible, setWorktreeVisible] = useState<boolean>(true);
+  // Pending approval count for the chat header badge (P8)
+  const [pendingApprovals, setPendingApprovals] = useState(0);
   const dragCounter = useRef(0);
   const chatInputRef = useRef<ChatInputHandle>(null);
   const queueRef = useRef<QueuedMessage[]>([]);
@@ -74,6 +76,25 @@ function Chat({
     };
   }, []);
 
+  // Poll for pending approvals (P8) — every 2s while chat is active
+  useEffect(() => {
+    let cancelled = false;
+    const poll = async (): Promise<void> => {
+      try {
+        const hasPending = await window.hermesAPI.approvalHasPending();
+        if (!cancelled) setPendingApprovals(hasPending ? 1 : 0);
+      } catch {
+        // IPC not available — silently skip
+      }
+    };
+    void poll();
+    const interval = setInterval(() => void poll(), 2000);
+    return (): void => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, []);
+
   const { containerRef, bottomRef } = useChatScroll(messages);
   const modelConfig = useModelConfig(profile);
   const {
@@ -322,6 +343,7 @@ function Chat({
         hasMessages={messages.length > 0}
         contextFolder={contextFolder}
         showContextFolder={!remoteMode}
+        pendingApprovals={pendingApprovals}
         worktreeVisible={worktreeVisible}
         onPickFolder={handlePickFolder}
         onClearFolder={handleClearFolder}