@vellumai/assistant 0.4.2 → 0.4.4

package/src/tools/browser/browser-screencast.ts

@@ -1,10 +1,9 @@
-import { v4 as uuid } from 'uuid';
+import type { ServerMessage } from '../../daemon/ipc-contract.js';
+import { browserManager, SCREENCAST_HEIGHT, SCREENCAST_WIDTH } from './browser-manager.js';
 
-import type { BrowserFrame, BrowserViewSurfaceData, ServerMessage } from '../../daemon/ipc-contract.js';
-import { browserManager, SCREENCAST_HEIGHT,SCREENCAST_WIDTH } from './browser-manager.js';
-
-// Track active screencast sessions
-const activeScreencasts = new Map<string, { surfaceId: string }>();
+// Track which sessions have an active browser page (no PiP surface — the user
+// watches the actual browser window directly).
+const activeBrowserSessions = new Set<string>();
 
 // Registry of sendToClient callbacks per session
 const sessionSenders = new Map<string, (msg: ServerMessage) => void>();
@@ -32,118 +31,55 @@ function getSender(sessionId: string): ((msg: ServerMessage) => void) | undefine
 
 export async function ensureScreencast(
   sessionId: string,
-  sendToClient: (msg: ServerMessage) => void,
+  _sendToClient: (msg: ServerMessage) => void,
 ): Promise<void> {
-  if (activeScreencasts.has(sessionId)) return;
+  if (activeBrowserSessions.has(sessionId)) return;
 
-  const surfaceId = uuid();
-  activeScreencasts.set(sessionId, { surfaceId });
+  activeBrowserSessions.add(sessionId);
 
   try {
-    // Get current page info
-    const page = await browserManager.getOrCreateSessionPage(sessionId);
-    const currentUrl = page.url();
-    const title = await page.title();
-
-    // Send surface show
-    sendToClient({
-      type: 'ui_surface_show',
-      sessionId,
-      surfaceId,
-      surfaceType: 'browser_view',
-      title: 'Browser',
-      data: {
-        sessionId,
-        currentUrl: currentUrl || 'about:blank',
-        status: 'idle',
-        pages: [{ id: sessionId, title: title || 'New Tab', url: currentUrl || 'about:blank', active: true }],
-      } satisfies BrowserViewSurfaceData,
-      display: 'panel',
-    });
-
-    // Start CDP screencast
-    await browserManager.startScreencast(sessionId, (frame) => {
-      sendToClient({
-        type: 'browser_frame',
-        sessionId,
-        surfaceId,
-        frame: frame.data,
-        metadata: frame.metadata,
-      } satisfies BrowserFrame);
-    });
+    // Ensure the page exists (may trigger browser launch/connect)
+    await browserManager.getOrCreateSessionPage(sessionId);
+
+    // No PiP surface or CDP screencast — the user watches the actual
+    // browser window directly (positioned in top-right via positionWindowSidebar).
   } catch (err) {
-    // Dismiss the surface we already showed so the client doesn't have an orphaned panel
-    sendToClient({
-      type: 'ui_surface_dismiss',
-      sessionId,
-      surfaceId,
-    });
     // Roll back so future calls can retry
-    activeScreencasts.delete(sessionId);
+    activeBrowserSessions.delete(sessionId);
     throw err;
   }
 }
 
 export function updateBrowserStatus(
   sessionId: string,
-  sendToClient: (msg: ServerMessage) => void,
-  status: 'navigating' | 'idle' | 'interacting',
-  actionText?: string,
-  currentUrl?: string,
+  _sendToClient: (msg: ServerMessage) => void,
+  _status: 'navigating' | 'idle' | 'interacting',
+  _actionText?: string,
+  _currentUrl?: string,
 ): void {
-  const state = activeScreencasts.get(sessionId);
-  if (!state) return;
-
-  const update: Record<string, unknown> = { status };
-  if (actionText !== undefined) update.actionText = actionText;
-  if (currentUrl !== undefined) update.currentUrl = currentUrl;
-
-  sendToClient({
-    type: 'ui_surface_update',
-    sessionId,
-    surfaceId: state.surfaceId,
-    data: update,
-  });
+  // No-op: PiP surface was removed so there is no ui_surface to update.
+  // The function signature is preserved to avoid churn at callsites.
+  if (!activeBrowserSessions.has(sessionId)) return;
 }
 
 export async function updatePagesList(
   sessionId: string,
-  sendToClient: (msg: ServerMessage) => void,
+  _sendToClient: (msg: ServerMessage) => void,
 ): Promise<void> {
-  const state = activeScreencasts.get(sessionId);
-  if (!state) return;
-
-  const page = await browserManager.getOrCreateSessionPage(sessionId);
-  const currentUrl = page.url();
-  const title = await page.title();
-
-  sendToClient({
-    type: 'ui_surface_update',
-    sessionId,
-    surfaceId: state.surfaceId,
-    data: {
-      currentUrl,
-      pages: [{ id: sessionId, title: title || 'Untitled', url: currentUrl, active: true }],
-    },
-  });
+  // No-op: PiP surface was removed so there is no ui_surface to update.
+  if (!activeBrowserSessions.has(sessionId)) return;
 }
 
 export async function stopBrowserScreencast(
   sessionId: string,
-  sendToClient: (msg: ServerMessage) => void,
+  _sendToClient: (msg: ServerMessage) => void,
 ): Promise<void> {
-  const state = activeScreencasts.get(sessionId);
-  if (!state) return;
+  if (!activeBrowserSessions.has(sessionId)) return;
 
+  // Safe no-op if CDP screencast was never started
   await browserManager.stopScreencast(sessionId);
 
-  sendToClient({
-    type: 'ui_surface_dismiss',
-    sessionId,
-    surfaceId: state.surfaceId,
-  });
-
-  activeScreencasts.delete(sessionId);
+  activeBrowserSessions.delete(sessionId);
 }
 
 export async function getElementBounds(
@@ -175,44 +111,24 @@ export async function getElementBounds(
 
 export function updateHighlights(
   sessionId: string,
-  sendToClient: (msg: ServerMessage) => void,
-  highlights: Array<{ x: number; y: number; w: number; h: number; label: string }>,
+  _sendToClient: (msg: ServerMessage) => void,
+  _highlights: Array<{ x: number; y: number; w: number; h: number; label: string }>,
 ): void {
-  const state = activeScreencasts.get(sessionId);
-  if (!state) return;
-  sendToClient({
-    type: 'ui_surface_update',
-    sessionId,
-    surfaceId: state.surfaceId,
-    data: { highlights },
-  });
+  // No-op: PiP surface was removed so there is no ui_surface to update.
+  if (!activeBrowserSessions.has(sessionId)) return;
 }
 
 export async function stopAllScreencasts(): Promise<void> {
-  const entries = Array.from(activeScreencasts.entries());
-  for (const [sessionId, state] of entries) {
+  for (const sessionId of activeBrowserSessions) {
     try {
       await browserManager.stopScreencast(sessionId);
     } catch { /* best-effort */ }
-    const sender = sessionSenders.get(sessionId);
-    if (sender) {
-      sender({
-        type: 'ui_surface_dismiss',
-        sessionId,
-        surfaceId: state.surfaceId,
-      });
-    }
   }
-  activeScreencasts.clear();
+  activeBrowserSessions.clear();
 }
 
 export function isScreencastActive(sessionId: string): boolean {
-  return activeScreencasts.has(sessionId);
+  return activeBrowserSessions.has(sessionId);
 }
 
 export { getSender };
-
-export function getScreencastSurfaceId(sessionId: string): string | null {
-  const state = activeScreencasts.get(sessionId);
-  return state?.surfaceId ?? null;
-}

package/src/tools/calls/call-start.ts

@@ -1,5 +1,6 @@
 import { startCall } from '../../calls/call-domain.js';
 import { getConfig } from '../../config/loader.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../../runtime/assistant-scope.js';
 import { findActiveSession } from '../../runtime/channel-guardian-service.js';
 import { normalizePhoneNumber } from '../../util/phone.js';
 import type { ToolContext, ToolExecutionResult } from '../types.js';
@@ -16,7 +17,7 @@ export async function executeCallStart(
     ? normalizePhoneNumber(input.phone_number)
     : null;
   if (requestedPhone) {
-    const assistantId = context.assistantId ?? 'self';
+    const assistantId = context.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
     const activeVoiceVerification = findActiveSession(assistantId, 'voice');
     const verificationDestination = activeVoiceVerification?.destinationAddress ?? activeVoiceVerification?.expectedPhoneE164;
     if (verificationDestination === requestedPhone) {

package/src/tools/permission-checker.ts

@@ -207,9 +207,14 @@ export class PermissionChecker {
         }
 
         if (response.decision === 'always_deny') {
-          const ruleSaved = !!(persistentDecisionsAllowed && response.selectedPattern && response.selectedScope);
+          // For non-scoped tools (empty scopeOptions), default to 'everywhere' since
+          // the client has no scope picker and will send undefined.
+          const effectiveDenyScope = scopeOptions.length === 0
+            ? (response.selectedScope ?? 'everywhere')
+            : response.selectedScope;
+          const ruleSaved = !!(persistentDecisionsAllowed && response.selectedPattern && effectiveDenyScope);
           if (ruleSaved) {
-            addRule(name, response.selectedPattern!, response.selectedScope!, 'deny');
+            addRule(name, response.selectedPattern!, effectiveDenyScope!, 'deny');
           }
           const denialReason = ruleSaved ? 'Permission denied by user (rule saved)' : 'Permission denied by user';
           const denialMessage = ruleSaved
@@ -237,7 +242,6 @@ export class PermissionChecker {
           persistentDecisionsAllowed
           && (response.decision === 'always_allow' || response.decision === 'always_allow_high_risk')
           && response.selectedPattern
-          && response.selectedScope
         ) {
           const ruleOptions: {
             allowHighRisk?: boolean;
@@ -253,7 +257,14 @@ export class PermissionChecker {
           }
 
           const hasOptions = Object.keys(ruleOptions).length > 0;
-          addRule(name, response.selectedPattern, response.selectedScope, 'allow', 100, hasOptions ? ruleOptions : undefined);
+          // Only default to 'everywhere' for non-scoped tools (empty scopeOptions).
+          // For scoped tools, require an explicit scope to prevent silent permission widening.
+          const effectiveScope = scopeOptions.length === 0
+            ? (response.selectedScope ?? 'everywhere')
+            : response.selectedScope;
+          if (effectiveScope) {
+            addRule(name, response.selectedPattern, effectiveScope, 'allow', 100, hasOptions ? ruleOptions : undefined);
+          }
         }
 
         return { allowed: true, decision, riskLevel };

package/src/tools/terminal/parser.ts

@@ -132,6 +132,18 @@ function findWasmPath(pkg: string, file: string): string {
     return execDirPath;
   }
 
+  // Use module resolution to find the package. This handles hoisted
+  // dependencies (e.g. global bun installs where web-tree-sitter is at the
+  // top-level node_modules rather than nested under @vellumai/assistant).
+  try {
+    const resolved = require.resolve(`${pkg}/package.json`);
+    const pkgDir = dirname(resolved);
+    const resolvedPath = join(pkgDir, file);
+    if (existsSync(resolvedPath)) return resolvedPath;
+  } catch (err) {
+    log.warn({ err, pkg, file }, 'require.resolve failed for WASM package, falling back to manual resolution');
+  }
+
   const sourcePath = join(dir, '..', '..', '..', 'node_modules', pkg, file);
 
   if (existsSync(sourcePath)) return sourcePath;

package/src/tools/tool-approval-handler.ts

@@ -1,4 +1,6 @@
 import { consumeGrantForInvocation } from '../approvals/approval-primitive.js';
+import { getCanonicalGuardianRequest, updateCanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../runtime/assistant-scope.js';
 import { createOrReuseToolGrantRequest } from '../runtime/tool-grant-request-helper.js';
 import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { getTaskRunRules } from '../tasks/ephemeral-permissions.js';
@@ -10,6 +12,112 @@ import type { ExecutionTarget, Tool, ToolContext, ToolExecutionResult, ToolLifec
 
 const log = getLogger('tool-approval-handler');
 
+/** Default polling interval for inline grant wait (ms). */
+export const TC_GRANT_WAIT_INTERVAL_MS = 500;
+/** Default maximum wait time for inline grant wait (ms). */
+export const TC_GRANT_WAIT_MAX_MS = 60_000;
+
+/**
+ * Inline wait result for trusted-contact grant polling.
+ * - `granted`: a grant was minted and consumed within the wait window.
+ * - `denied`: the guardian explicitly rejected the request.
+ * - `timeout`: the wait budget expired without a decision.
+ * - `aborted`: the session was cancelled during the wait.
+ * - `escalation_failed`: the grant request could not be created.
+ */
+export type InlineGrantWaitOutcome =
+  | { outcome: 'granted'; grant: { id: string } }
+  | { outcome: 'denied'; requestId: string }
+  | { outcome: 'timeout'; requestId: string }
+  | { outcome: 'aborted' }
+  | { outcome: 'escalation_failed'; reason: string };
+
+/**
+ * Wait bounded for a guardian to approve a tool grant request and for the
+ * resulting grant to become consumable. Polls both the canonical request
+ * status (to detect early rejection) and the grant store (to detect approval
+ * and atomically consume the grant).
+ *
+ * Only called for trusted_contact actors with valid guardian bindings.
+ */
+export async function waitForInlineGrant(
+  escalationRequestId: string,
+  consumeParams: Parameters<typeof consumeGrantForInvocation>[0],
+  options?: { maxWaitMs?: number; intervalMs?: number; signal?: AbortSignal },
+): Promise<InlineGrantWaitOutcome> {
+  const maxWait = options?.maxWaitMs ?? TC_GRANT_WAIT_MAX_MS;
+  const interval = options?.intervalMs ?? TC_GRANT_WAIT_INTERVAL_MS;
+  const signal = options?.signal;
+  const deadline = Date.now() + maxWait;
+
+  log.info(
+    {
+      event: 'tc_inline_grant_wait_start',
+      escalationRequestId,
+      toolName: consumeParams.toolName,
+      maxWaitMs: maxWait,
+      intervalMs: interval,
+    },
+    'Starting inline wait for guardian grant decision',
+  );
+
+  while (Date.now() < deadline) {
+    if (signal?.aborted) {
+      return { outcome: 'aborted' };
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, interval));
+
+    if (signal?.aborted) {
+      return { outcome: 'aborted' };
+    }
+
+    // Check if the canonical request was rejected — exit early without
+    // waiting for the full timeout.
+    const request = getCanonicalGuardianRequest(escalationRequestId);
+    if (request && request.status === 'denied') {
+      log.info(
+        {
+          event: 'tc_inline_grant_wait_denied',
+          escalationRequestId,
+          toolName: consumeParams.toolName,
+          elapsedMs: maxWait - (deadline - Date.now()),
+        },
+        'Guardian denied tool grant request during inline wait',
+      );
+      return { outcome: 'denied', requestId: escalationRequestId };
+    }
+
+    // Try to consume the grant — if the guardian approved, the canonical
+    // decision primitive will have minted a scoped grant by now.
+    const grantResult = await consumeGrantForInvocation(consumeParams, { maxWaitMs: 0 });
+    if (grantResult.ok) {
+      log.info(
+        {
+          event: 'tc_inline_grant_wait_granted',
+          escalationRequestId,
+          toolName: consumeParams.toolName,
+          grantId: grantResult.grant.id,
+          elapsedMs: maxWait - (deadline - Date.now()),
+        },
+        'Grant found during inline wait — tool execution proceeding',
+      );
+      return { outcome: 'granted', grant: { id: grantResult.grant.id } };
+    }
+  }
+
+  log.info(
+    {
+      event: 'tc_inline_grant_wait_timeout',
+      escalationRequestId,
+      toolName: consumeParams.toolName,
+      maxWaitMs: maxWait,
+    },
+    'Inline grant wait timed out — no guardian decision within budget',
+  );
+  return { outcome: 'timeout', requestId: escalationRequestId };
+}
+
 function isUntrustedGuardianTrustClass(role: ToolContext['guardianTrustClass']): boolean {
   return role === 'trusted_contact' || role === 'unknown';
 }
@@ -39,12 +147,26 @@ export type PreExecutionGateResult =
   | { allowed: true; tool: Tool; grantConsumed?: boolean }
   | { allowed: false; result: ToolExecutionResult };
 
+/** Configuration for the inline grant wait behavior. */
+export interface InlineGrantWaitConfig {
+  /** Maximum time to wait for guardian approval (ms). Defaults to TC_GRANT_WAIT_MAX_MS. */
+  maxWaitMs?: number;
+  /** Polling interval during the wait (ms). Defaults to TC_GRANT_WAIT_INTERVAL_MS. */
+  intervalMs?: number;
+}
+
 /**
  * Handles pre-execution approval gates: abort checks, guardian policy,
  * allowed-tool-set gating, and task-run preflight checks.
  * These run before the interactive permission prompt flow.
  */
 export class ToolApprovalHandler {
+  private inlineGrantWaitConfig: InlineGrantWaitConfig;
+
+  constructor(config?: { inlineGrantWait?: InlineGrantWaitConfig }) {
+    this.inlineGrantWaitConfig = config?.inlineGrantWait ?? {};
+  }
+
   /**
    * Evaluate all pre-execution approval gates for a tool invocation.
    * Returns the resolved Tool if all gates pass, or an early-return
@@ -128,7 +250,7 @@ export class ToolApprovalHandler {
         toolName: name,
         inputDigest,
         consumingRequestId: context.requestId ?? `preexec-${context.sessionId}-${Date.now()}`,
-        assistantId: context.assistantId ?? 'self',
+        assistantId: context.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
         executionChannel: context.executionChannel,
         conversationId: context.conversationId,
         callSessionId: context.callSessionId,
@@ -266,12 +388,15 @@ export class ToolApprovalHandler {
         return { allowed: false, result: { content: 'Cancelled', isError: true } };
       }
 
-      // No matching grant or race condition — deny.
+      // No matching grant or race condition — deny or wait inline.
       //
-      // For verified non-guardian actors with sufficient context, escalate to
-      // the guardian by creating a canonical tool_grant_request. Unverified
-      // actors remain fail-closed with no escalation.
-      let escalationMessage: string | undefined;
+      // For verified non-guardian actors (trusted_contact) with sufficient
+      // context, escalate to the guardian by creating a canonical
+      // tool_grant_request. Then wait bounded for the grant to become
+      // available — this lets the tool call succeed inline after guardian
+      // approval without the requester having to retry manually.
+      //
+      // Unverified actors remain fail-closed with no escalation or wait.
       if (
         context.guardianTrustClass === 'trusted_contact'
         && context.assistantId
@@ -291,24 +416,124 @@ export class ToolApprovalHandler {
           questionText: `Trusted contact is requesting permission to use "${name}"`,
         });
 
-        if ('created' in escalation) {
-          const codeSuffix = escalation.requestCode
-            ? ` (request code: ${escalation.requestCode})`
-            : '';
-          escalationMessage = `Permission denied for "${name}": this action requires guardian approval. `
-            + `A request has been sent to the guardian${codeSuffix}. `
-            + `Please retry after the guardian approves.`;
-        } else if ('deduped' in escalation) {
+        // Only wait inline if the escalation succeeded (created or deduped).
+        // If escalation failed (no binding, missing identity), fall through
+        // to the generic denial path.
+        if ('created' in escalation || 'deduped' in escalation) {
+          // Stamp the canonical request so the approval resolver knows an
+          // inline consumer is waiting. Without this, the resolver would
+          // send a stale "please retry" notification even though the
+          // original invocation is about to resume inline.
+          updateCanonicalGuardianRequest(escalation.requestId, {
+            followupState: 'inline_wait_active:' + Date.now(),
+          });
+
+          const waitResult = await waitForInlineGrant(
+            escalation.requestId,
+            deferredConsumeParams!,
+            {
+              maxWaitMs: this.inlineGrantWaitConfig.maxWaitMs,
+              intervalMs: this.inlineGrantWaitConfig.intervalMs,
+              signal: context.signal,
+            },
+          );
+
+          if (waitResult.outcome === 'granted') {
+            // Clear the inline-wait stamp now that the grant has been consumed.
+            updateCanonicalGuardianRequest(escalation.requestId, {
+              followupState: null,
+            });
+            log.info({
+              toolName: name,
+              sessionId: context.sessionId,
+              conversationId: context.conversationId,
+              trustClass: context.guardianTrustClass,
+              executionTarget,
+              grantId: waitResult.grant.id,
+              escalationRequestId: escalation.requestId,
+            }, 'Inline grant wait succeeded — allowing trusted contact tool invocation');
+            return { allowed: true, tool, grantConsumed: true };
+          }
+
+          if (waitResult.outcome === 'aborted') {
+            // Clear the inline-wait stamp so a later guardian approval
+            // (if the request is still pending) will send the retry notification.
+            updateCanonicalGuardianRequest(escalation.requestId, {
+              followupState: null,
+            });
+            const durationMs = Date.now() - startTime;
+            emitLifecycleEvent({
+              type: 'error',
+              toolName: name,
+              executionTarget,
+              input,
+              workingDir: context.workingDir,
+              sessionId: context.sessionId,
+              conversationId: context.conversationId,
+              requestId: context.requestId,
+              riskLevel,
+              decision: 'error',
+              durationMs,
+              errorMessage: 'Cancelled',
+              isExpected: true,
+              errorCategory: 'tool_failure',
+            });
+            return { allowed: false, result: { content: 'Cancelled', isError: true } };
+          }
+
+          // Clear the inline-wait stamp so a later guardian approval
+          // (if the request is still pending after timeout) will send
+          // the retry notification as expected.
+          updateCanonicalGuardianRequest(escalation.requestId, {
+            followupState: null,
+          });
+
           const codeSuffix = escalation.requestCode
             ? ` (request code: ${escalation.requestCode})`
             : '';
-          escalationMessage = `Permission denied for "${name}": guardian approval is already pending${codeSuffix}. `
-            + `Please retry after the guardian approves.`;
+
+          let escalationMessage: string;
+          if (waitResult.outcome === 'denied') {
+            escalationMessage = `Permission denied for "${name}": the guardian rejected the request${codeSuffix}.`;
+          } else {
+            // timeout
+            escalationMessage = `Permission denied for "${name}": guardian approval was not received in time${codeSuffix}. `
+              + `Please retry after the guardian approves.`;
+          }
+
+          log.warn({
+            toolName: name,
+            sessionId: context.sessionId,
+            conversationId: context.conversationId,
+            trustClass: context.guardianTrustClass,
+            executionTarget,
+            reason: 'guardian_approval_required',
+            grantMissReason: grantResult.reason,
+            waitOutcome: waitResult.outcome,
+            escalationRequestId: escalation.requestId,
+          }, 'Inline grant wait ended without approval — denying trusted contact tool invocation');
+          const durationMs = Date.now() - startTime;
+          emitLifecycleEvent({
+            type: 'permission_denied',
+            toolName: name,
+            executionTarget,
+            input,
+            workingDir: context.workingDir,
+            sessionId: context.sessionId,
+            conversationId: context.conversationId,
+            requestId: context.requestId,
+            riskLevel,
+            decision: 'deny',
+            reason: escalationMessage,
+            durationMs,
+          });
+          return { allowed: false, result: { content: escalationMessage, isError: true } };
         }
-        // If escalation.failed, fall through to generic denial message.
+        // escalation.failed — fall through to generic denial.
       }
 
-      const reason = escalationMessage ?? guardianApprovalDeniedMessage(context.guardianTrustClass, name);
+      // Unknown/unverified actors or escalation failures — generic denial.
+      const reason = guardianApprovalDeniedMessage(context.guardianTrustClass, name);
       log.warn({
         toolName: name,
         sessionId: context.sessionId,
@@ -317,7 +542,7 @@ export class ToolApprovalHandler {
         executionTarget,
         reason: 'guardian_approval_required',
         grantMissReason: grantResult.reason,
-        escalated: !!escalationMessage,
+        escalated: false,
       }, 'Guardian approval gate blocked untrusted actor tool invocation (no matching grant)');
       const durationMs = Date.now() - startTime;
       emitLifecycleEvent({

package/src/workspace/git-service.ts

@@ -16,6 +16,11 @@ const log = getLogger('workspace-git');
  * Strips all GIT_* env vars (e.g. GIT_DIR, GIT_WORK_TREE) that CI runners
  * or parent processes may set, then adds GIT_CEILING_DIRECTORIES to prevent
  * walking up to a parent repo.
+ *
+ * On macOS, augments PATH with common binary directories so the real git
+ * binary is found even when the daemon is launched from a .app bundle with
+ * a minimal PATH. Without this, the macOS /usr/bin/git shim triggers an
+ * "Install Command Line Developer Tools" popup on every git invocation.
  */
 function cleanGitEnv(workspaceDir: string): Record<string, string> {
   const env: Record<string, string> = {};
@@ -25,6 +30,20 @@ function cleanGitEnv(workspaceDir: string): Record<string, string> {
     }
   }
   env.GIT_CEILING_DIRECTORIES = workspaceDir;
+
+  const home = process.env.HOME ?? '';
+  const extraDirs = [
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+    `${home}/.local/bin`,
+  ];
+  const currentPath = env.PATH ?? '';
+  const pathDirs = currentPath.split(':');
+  const missing = extraDirs.filter(d => !pathDirs.includes(d));
+  if (missing.length > 0) {
+    env.PATH = [...missing, currentPath].filter(Boolean).join(':');
+  }
+
   return env;
 }