@oar-sh/oar 0.9.20 → 0.9.22

package/server/claude-cloud-worker/claude-cloud-session-process.mjs

@@ -178,6 +178,18 @@ export function createClaudeCloudSessionRunner({
   // Background work is over and nothing has moved for this long: ask the
   // session whether the agent is still going to say something.
   backgroundQuietMs = 45_000,
+  // Between turns, while the cloud may still be working on something no
+  // relay turn owns (its last known status was not idle, or a turn ended here
+  // without its `result`), the session is read again this often: the relay
+  // waits on that answer before it replaces this worker (releaseHold).
+  statusRecheckMs = 20_000,
+  // A session that stays not idle this long is no longer read (one warning
+  // line); the next delivery starts the reads again. The hold stays: the
+  // relay does not replace a worker whose session it last saw working.
+  statusRecheckGiveUpMs = 2 * 60 * 60_000,
+  // How often the stored binding is asked for again at start when the relay
+  // does not answer (attachOnStart); three tries in all.
+  bindingRetryMs = 5_000,
 } = {}) {
   const publisher = createClaudeTurnPublisher({ api, dbg });
   // The account's usage limit as the sandbox's Claude Code reports it: the
@@ -211,10 +223,23 @@ export function createClaudeCloudSessionRunner({
   // - `attributionRequestId`: the request whose answer is still to come.
   // - `model`: the model this process last gave the sandbox (the create's,
   //   or a later set_model); undefined while it does not know.
+  // - `workerStatus`: the session's `worker_status` at the last read of it
+  //   ('idle' when the cloud has nothing running), null while unknown.
   let session = null;
   let turn = null;
   let stream = null;
   let idleTimer = null;
+  let statusTimer = null;
+  // A read of the session between turns that may attach it (syncSession):
+  // a delivery waits for it, so the two never read the log at once.
+  let pendingSync = null;
+  // When the current run of status rechecks began (null: none runs), and
+  // whether it was given up (statusRecheckGiveUpMs).
+  let recheckSince = null;
+  let recheckGivenUp = false;
+  // A turn the session started by itself is being registered with the relay.
+  let openingStrayTurn = false;
+  let disposed = false;
   // Events are handled one at a time and in order; posting a user message
   // takes a place in the same line, so no event of the turn it starts is
   // looked at before the turn's start is known.
@@ -249,6 +274,7 @@ export function createClaudeCloudSessionRunner({
       attribution: undefined,
       attributionRequestId: null,
       model: undefined,
+      workerStatus: null,
     };
   }
 
@@ -275,6 +301,33 @@ export function createClaudeCloudSessionRunner({
     return Boolean(turn);
   }
 
+  /**
+   * Why the relay may not stop this worker and launch a fresh one now, or ''
+   * when it may (the hold names of the relay's STEERING_RELEASE_HOLDS):
+   * - 'turn': a turn runs here, delivered or one the session started itself
+   *   (from the moment the relay is asked for its row).
+   * - 'background': no turn runs here, but the cloud may still be working on
+   *   one: a turn that ended here without its `result` (a Stop the cloud did
+   *   not confirm, the background-hold ceiling, a turn the relay would not
+   *   register), or a session whose last known status is not idle. A worker
+   *   replaced then would lose what that work still writes: the count lives
+   *   only in this process, and a fresh one reads on from the stored cursor
+   *   as if nothing were running.
+   * A session this process has not read yet holds nothing.
+   */
+  function releaseHold() {
+    if (turn || openingStrayTurn) return 'turn';
+    if (!session) return '';
+    if (session.unfinishedTurns > 0) return 'background';
+    if (session.workerStatus && session.workerStatus !== 'idle') return 'background';
+    return '';
+  }
+
+  /** Remember what a read of the session said about the cloud's work. */
+  function noteSessionRead(workerStatus) {
+    if (session) session.workerStatus = workerStatus || null;
+  }
+
   // ---------------------------------------------------------------------------
   // Relay-facing publishing
 
@@ -456,6 +509,7 @@ export function createClaudeCloudSessionRunner({
         let workerStatus = '';
         try {
           ({ workerStatus } = readCloudSessionUsage(await withTimeout(cloud.getSession(session.id), sessionReadTimeoutMs)));
+          noteSessionRead(workerStatus);
         } catch (error) {
           dbg('cloud session read failed', error?.message || String(error));
         }
@@ -532,6 +586,9 @@ export function createClaudeCloudSessionRunner({
     if (!response?.messageId) {
       dbg('stray cloud turn not registered; skipping it until its result');
       session.unfinishedTurns += 1;
+      // No turn here will end the wait on its `result`; the session's
+      // status will.
+      scheduleStatusRecheck();
       return null;
     }
     const message = {
@@ -569,6 +626,7 @@ export function createClaudeCloudSessionRunner({
         endTurn(t);
         if (turn === t) turn = null;
         scheduleIdleClose();
+        scheduleStatusRecheck();
       }
     })();
     return t;
@@ -592,7 +650,14 @@ export function createClaudeCloudSessionRunner({
     // continuation of its own, so the chat shows it.
     if (!t && session.attached && sequence !== null && session.unfinishedTurns === 0
       && sequence > session.cursorSeq && startsStrayTurn(event, payload, type)) {
-      t = await openStrayTurn(sequence, payload, type);
+      // The relay is asked for a row first: the turn runs already, and the
+      // release holds meanwhile as it will once the row is there.
+      openingStrayTurn = true;
+      try {
+        t = await openStrayTurn(sequence, payload, type);
+      } finally {
+        openingStrayTurn = false;
+      }
       if (!t) return;
     }
 
@@ -963,12 +1028,159 @@ export function createClaudeCloudSessionRunner({
   async function confirmUnfinishedTurns() {
     try {
       const { workerStatus } = readCloudSessionUsage(await withTimeout(cloud.getSession(session.id), sessionReadTimeoutMs));
+      noteSessionRead(workerStatus);
       if (workerStatus === 'idle') session.unfinishedTurns = 0;
     } catch (error) {
       dbg('cloud session read failed', error?.message || String(error));
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Between turns: the session's status, and the attach at start
+
+  /**
+   * The session's status, read once (bounded); null when the read failed, in
+   * which case what was known before stays.
+   */
+  async function readWorkerStatus() {
+    try {
+      const { workerStatus } = readCloudSessionUsage(await withTimeout(cloud.getSession(session.id), sessionReadTimeoutMs));
+      noteSessionRead(workerStatus);
+      return workerStatus || null;
+    } catch (error) {
+      dbg('cloud session read failed', error?.message || String(error));
+      return null;
+    }
+  }
+
+  /**
+   * Read the session again later while it holds the release with no turn
+   * here to end the wait (a turn's end schedules this itself), or while the
+   * session bound at start is not attached yet.
+   */
+  function scheduleStatusRecheck() {
+    if (statusTimer || disposed || !session || turn) return;
+    if (session.attached && !releaseHold()) {
+      recheckSince = null;
+      return;
+    }
+    if (recheckGivenUp) return;
+    if (recheckSince === null) {
+      recheckSince = now();
+    } else if (now() - recheckSince >= statusRecheckGiveUpMs) {
+      // Not forever: a session stuck in a working state would be read every
+      // statusRecheckMs for the life of the worker.
+      recheckGivenUp = true;
+      dbg(
+        `warning: the cloud session has not been idle for ${Math.round(statusRecheckGiveUpMs / 60_000)} min;`,
+        'no more status reads until the next delivery, and the relay does not replace this worker meanwhile',
+      );
+      return;
+    }
+    statusTimer = setTimeoutImpl(() => {
+      statusTimer = null;
+      void syncSession();
+    }, statusRecheckMs);
+    statusTimer?.unref?.();
+  }
+
+  function clearStatusRecheck() {
+    if (statusTimer) clearTimeoutImpl(statusTimer);
+    statusTimer = null;
+  }
+
+  /**
+   * Between turns: read the session, and act on an idle one. An idle cloud
+   * has no `result` left to send, so the turns that ended here without one
+   * are done with (as confirmUnfinishedTurns does before a send). An idle
+   * session bound at start but not attached yet is read on from the stored
+   * cursor up to now and its stream opened, so a turn the session starts by
+   * itself from here on is followed as a continuation, as the worker before
+   * this one did. A session that is working is not attached: the turn it
+   * runs may be a delivered one a dead worker left behind, which the relay
+   * delivers again and the delivery follows from the log (catchUp); taken
+   * for a turn of the session's own, it would be published twice.
+   * A delivery waits for this (pendingSync).
+   */
+  function syncSession() {
+    if (pendingSync) return pendingSync;
+    if (disposed || !session || turn || openingStrayTurn) return Promise.resolve(false);
+    const run = (async () => {
+      let attachedNow = false;
+      const status = await readWorkerStatus();
+      if (!disposed && session && !turn && status === 'idle') {
+        session.unfinishedTurns = 0;
+        if (!session.attached) {
+          await catchUp();
+          if (!disposed && session && !session.attached) {
+            session.attached = true;
+            ensureStream();
+            attachedNow = true;
+            dbg('cloud event stream opened between turns', `after=${session.lastSeq}`);
+          }
+        }
+      }
+      return attachedNow;
+    })();
+    pendingSync = run
+      .catch((error) => {
+        dbg('cloud session sync failed', error?.message || String(error));
+        return false;
+      })
+      .finally(() => {
+        pendingSync = null;
+        scheduleStatusRecheck();
+      });
+    return pendingSync;
+  }
+
+  /** The binding the relay stores for this conversation, or null. */
+  async function readStoredBinding() {
+    const routePath = `/api/claude-cloud-session?conversationId=${encodeURIComponent(sdkSessionId)}`;
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        return await api('GET', routePath);
+      } catch (error) {
+        // A relay without the route answers 404 for good: the first delivery
+        // binds the session, as before.
+        if (Number(error?.status) === 404 || attempt >= 3 || disposed) {
+          dbg('stored cloud session not read', error?.message || String(error));
+          return null;
+        }
+        await sleep(bindingRetryMs);
+      }
+    }
+  }
+
+  /**
+   * At worker start: bind the cloud session the relay stores for this
+   * conversation and open its event stream from the stored cursor, before
+   * any delivery. The worker this one replaces kept its stream open for its
+   * whole life (idleCloseMs = 0) and so mirrored the turns the session
+   * starts by itself (a message sent on claude.ai, the agent's closing turn
+   * after background work); without this a fresh worker would see none of
+   * them until its first delivery. A conversation with no cloud session yet
+   * has nothing to attach: its first delivery creates one. A session that is
+   * working at start is read again every statusRecheckMs and attached once
+   * idle (syncSession says why not before).
+   *
+   * Resolves true when the stream was opened.
+   */
+  async function attachOnStart() {
+    if (session || turn || disposed || pendingSync) return false;
+    const run = (async () => {
+      const binding = await readStoredBinding();
+      const id = String(binding?.sessionId || '').trim();
+      if (!id || session || disposed) return false;
+      session = newSession(id, { cursor: toCloudSequence(binding.lastSequence) ?? 0 });
+      return true;
+    })();
+    // A delivery that arrives meanwhile waits until the binding is known.
+    pendingSync = run.catch(() => false).finally(() => { pendingSync = null; });
+    if (!await pendingSync) return false;
+    return syncSession();
+  }
+
   /**
    * Before a message goes into a session that exists: hand the sandbox the
    * commit attribution the relay delivered, unless this process already did.
@@ -1173,6 +1385,7 @@ export function createClaudeCloudSessionRunner({
       dbg('cloud session read failed', error?.message || String(error));
     }
     if (usage.sessionUrl) session.url = usage.sessionUrl;
+    if (usage.workerStatus !== undefined) noteSessionRead(usage.workerStatus);
     const costUsd = usage.costUsd ?? state.result?.totalCostUsd ?? null;
     await reportSession(message, {
       ...(costUsd !== null ? { costUsd } : {}),
@@ -1318,7 +1531,19 @@ export function createClaudeCloudSessionRunner({
       dbg('turn already active; rejecting concurrent deliver', message.id);
       return false;
     }
+    // The session is being read between turns (the attach at start, or a
+    // status check): this delivery binds and reads it after that, never
+    // beside it. A turn the session started meanwhile takes precedence.
+    while (pendingSync) await pendingSync;
+    if (turn) {
+      dbg('turn already active; rejecting concurrent deliver', message.id);
+      return false;
+    }
     clearIdleClose();
+    clearStatusRecheck();
+    // A delivery starts the status reads afresh, also after they were given up.
+    recheckSince = null;
+    recheckGivenUp = false;
     const t = openTurn(message);
     const relayHoldMs = Number(pending?.settings?.backgroundTaskTimeoutMs);
     if (Number.isFinite(relayHoldMs) && relayHoldMs > 0) t.holdMs = relayHoldMs;
@@ -1337,11 +1562,14 @@ export function createClaudeCloudSessionRunner({
       endTurn(t);
       turn = null;
       scheduleIdleClose();
+      scheduleStatusRecheck();
     }
   }
 
   async function dispose() {
+    disposed = true;
     clearIdleClose();
+    clearStatusRecheck();
     if (turn) endTurn(turn);
     const entry = stream;
     stream = null;
@@ -1353,6 +1581,8 @@ export function createClaudeCloudSessionRunner({
     getActiveQueueMessageId,
     getActiveQueueAttempt,
     isTurnActive,
+    releaseHold,
+    attachOnStart,
     dispose,
   };
 }

package/server/claude-cloud-worker/claude-cloud-session-worker.mjs

@@ -14,6 +14,8 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { createWorkerKeepalive } from '../../shared/worker-runtime/worker-keepalive.mjs';
+import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
@@ -21,6 +23,7 @@ import { createClaudeCloudCredentials } from '../../shared/claude-cloud/credenti
 import { createClaudeCloudClient } from '../../shared/claude-cloud/api-client.mjs';
 import { resolveClaudeCloudBaseUrl } from '../../shared/claude-cloud/base-url.mjs';
 import { createClaudeCloudSessionRunner } from './claude-cloud-session-process.mjs';
+import { buildClaudeCloudSteeringState } from './claude-cloud-worker-steering.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
 // stdout/stderr into it. A no-op wherever the launcher redirects instead.
@@ -51,6 +54,10 @@ async function main() {
 
   const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
     || path.resolve(__dirname, '..', 'config.json');
+  // The code this process started on, read once from the repo root and kept
+  // for its whole life: the relay recycles a worker whose build differs from
+  // its own, and a tree that moves on under us must not change our answer.
+  const buildId = resolveBuildId(path.resolve(__dirname, '..', '..')).id;
   const serverUrl = resolveRelayServerUrl({ configPath });
   const token = loadTokenFromConfig(configPath);
   const defaultModel = String(process.env.CLAUDE_CLOUD_RELAY_MODEL || '').trim();
@@ -101,17 +108,33 @@ async function main() {
   let heartbeatTimer = null;
   const heartbeat = createHeartbeatController({
     api,
+    buildId,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
     getHeartbeatTimer: () => heartbeatTimer,
     setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
     getActiveQueueMessageId: () => runner.getActiveQueueMessageId(),
+    // No steering here; the snapshot tells the relay when it may replace
+    // this worker: between turns, with no turn that ended here without its
+    // result, and with the cloud session idle at its last read. Anything else
+    // is cloud work whose output only this process would still publish. The
+    // cloud session lives on in the cloud; the fresh worker binds it at start
+    // and re-opens its event stream from the cursor the relay stores
+    // (runner.attachOnStart below), so the turns the session starts by
+    // itself are still followed.
+    getSteeringState: () => buildClaudeCloudSteeringState(runner),
   });
 
+  // One timer for the heartbeat and the socket's readiness refresh: 10 s
+  // while working, 30 s while idle on a relay that allows it.
+  let keepalive = null;
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
+    readyRefreshMs: 0,
+    onRelayFrame: () => keepalive?.nudge(),
     token,
     dbg,
+    buildId,
     getSessionReady: () => true,
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
@@ -125,10 +148,12 @@ async function main() {
       }
     },
   });
+  keepalive = createWorkerKeepalive({ heartbeat, link: wsLink, busyMs: HEARTBEAT_MS });
 
   const shutdown = async (signal) => {
     dbg(`shutting down (${signal})`);
     try { wsLink.stop(); } catch {}
+    try { keepalive.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
     // The cloud session is left as it is: a turn in flight keeps running
@@ -144,9 +169,13 @@ async function main() {
     getActiveQueueMessageIds: () => [runner.getActiveQueueAttempt()],
   });
 
-  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} model=${defaultModel || 'default'}`);
-  heartbeat.startHeartbeat();
+  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
+  keepalive.start();
   wsLink.start();
+  // Not awaited: deliveries wait for it inside the runner, and a relay that
+  // cannot say which cloud session this is leaves the binding to the first
+  // delivery, as before.
+  runner.attachOnStart().catch((error) => dbg('cloud session attach at start failed', error?.message || String(error)));
 }
 
 main().catch((error) => {

package/server/claude-cloud-worker/claude-cloud-worker-steering.mjs

@@ -0,0 +1,34 @@
+/**
+ * The heartbeat steering snapshot of the Claude Cloud worker. It steers
+ * nothing (`supported: false`, so the composer offers no mid-turn steering and
+ * reads neither the hold nor the cancellable ids); it is sent for the release
+ * fields, which tell the relay whether it may stop this worker and launch a
+ * fresh one now (its recycle after a deploy).
+ *
+ * The rule is the runner's (`releaseHold()` in claude-cloud-session-process.mjs):
+ * not while a turn runs here, not while a turn that ended here without its
+ * `result` may still run in the cloud, and not while the cloud session's last
+ * known status is not idle. The generic snapshot of the other small mains
+ * (shared/worker-runtime/simple-steering-state.mjs) knows only the turn; the
+ * cloud session can be busy with no relay turn at all.
+ *
+ * `runner` is the object createClaudeCloudSessionRunner returns.
+ */
+export function buildClaudeCloudSteeringState(runner) {
+  const attempt = runner?.getActiveQueueAttempt?.() || null;
+  const messageId = String(attempt?.id || '').trim() || null;
+  const turnActive = runner?.isTurnActive?.() === true || Boolean(messageId);
+  // A runner without the hold function still never says yes mid-turn.
+  const hold = String(runner?.releaseHold?.() || '').trim() || (turnActive ? 'turn' : '');
+  return {
+    turnActive,
+    canSteer: false,
+    holdReason: null,
+    messageId,
+    supported: false,
+    cancellableIds: [],
+    releasable: !hold,
+    releaseHold: hold || null,
+    backgroundTaskCount: 0,
+  };
+}

package/server/claude-worker/claude-sdk-adapter.mjs

@@ -2,6 +2,7 @@ import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
 
 import { formatClaudeBackgroundCommandLimitLabel } from '../../shared/claude-background-command-limit.mjs';
 import { parseThinkingDisplay } from '../../shared/claude-thinking.mjs';
+import { PERSON_ONLY_QUESTION_SOURCE } from '../../shared/relay-asks.mjs';
 import { MEDIA_EMBED_INSTRUCTION_TEXT } from '../../shared/media-embed-instructions.mjs';
 import { REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS } from '../../shared/remote-relay-tool-core.mjs';
 import { createPreviewToolDefinition } from './claude-preview-tool.mjs';
@@ -631,11 +632,151 @@ export async function readPlanUsage(turn, dbg = () => {}, { timeoutMs = 10000 }
   }
 }
 
+// Asks Claude Code marks as person-only: a removal of a workspace or system
+// directory, a target it cannot resolve. No rule, mode or automatic approval
+// may answer them, so allow-all parity stops here. The SDK does not forward
+// the wire's `classifier_approvable`, so the safety-check kinds count only
+// together with `suppressAlwaysAllowRule`; a sensitive-file safety check
+// (an edit under .git/ or .claude/) carries no such flag and stays allowed.
+// A user's `permissions.ask` rule (`matchedAskRule`) changes nothing: the
+// flags decide, and an ask that rule forced without them stays allowed.
+const PERSON_ONLY_REASON_TYPES = new Set(['safetyCheck', 'subcommandResults']);
+export const PERSON_ONLY_ALLOW_CHOICE = 'Allow once';
+export const PERSON_ONLY_DENY_CHOICE = 'Deny';
+export { PERSON_ONLY_QUESTION_SOURCE };
+// The card's first line is fixed text: the relay's console log prints the
+// first 60 characters of a question, and the command must not reach it.
+const PERSON_ONLY_QUESTION_LEAD = 'Claude Code marks this as person-only: no rule or automatic approval may allow it. Allow it once?';
+const PERSON_ONLY_RATIONALE = 'Claude Code needs a person to approve this before it runs. Nothing runs until you choose.';
+// The card shows the whole command or nothing: a cut could hide the removal.
+export const PERSON_ONLY_COMMAND_MAX = 8000;
+export const PERSON_ONLY_TOO_LONG_MESSAGE = 'Not run: too long to show for approval; issue the removal as a short command of its own.';
+const PERSON_ONLY_REASON_MAX = 400;
+const PERSON_ONLY_TYPED_ANSWER_MAX = 500;
+
+export function isPersonOnlyAsk(options) {
+  if (!options || typeof options !== 'object') return false;
+  if (options.defaultToNo === true) return true;
+  return PERSON_ONLY_REASON_TYPES.has(options.decisionReasonType)
+    && options.suppressAlwaysAllowRule === true;
+}
+
+// Characters that hide or reorder text: C0 and C1 controls, bidi controls,
+// zero-width characters and the Unicode line separators. On the card each
+// one shows as a visible \u{XXXX} escape (the body is pre-wrap plain text).
+const INVISIBLE_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g;
+
+function escapeInvisible(text) {
+  return String(text ?? '').replace(INVISIBLE_CHARACTERS, (char) => (
+    `\\u{${char.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}}`
+  ));
+}
+
+// The CLI's reason may carry ANSI colour (sdk.d.ts): drop well-formed
+// sequences, then escape what is left, newlines included (one line).
+function reasonLine(value) {
+  const text = String(value ?? '')
+    .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .trim();
+  return capText(escapeInvisible(text), PERSON_ONLY_REASON_MAX);
+}
+
+function capText(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}… (${text.length - max} more characters)`;
+}
+
+function personOnlySubject(input) {
+  if (typeof input?.command === 'string') return { label: 'command', text: input.command };
+  for (const key of ['file_path', 'notebook_path', 'path']) {
+    if (typeof input?.[key] === 'string') return { label: 'path', text: input[key] };
+  }
+  let json = '';
+  try { json = JSON.stringify(input ?? {}); } catch { json = ''; }
+  return { label: 'input', text: json };
+}
+
+// Each line escaped and behind "│ ", each line break marked "⏎", so no line
+// of the command can pass for the card's own text.
+function subjectLines(text) {
+  return String(text ?? '').split('\n').map(escapeInvisible);
+}
+
+function subjectTooLong(input) {
+  return subjectLines(personOnlySubject(input).text).join('\n').length > PERSON_ONLY_COMMAND_MAX;
+}
+
+export function personOnlyQuestionText(toolName, input, decisionReason) {
+  const subject = personOnlySubject(input);
+  const lines = subjectLines(subject.text);
+  const parts = [PERSON_ONLY_QUESTION_LEAD];
+  const reason = reasonLine(decisionReason);
+  if (reason) parts.push(`Reason: ${reason}`);
+  const count = lines.length > 1 ? `, ${lines.length} lines` : '';
+  parts.push(`${toolName || 'Tool'} ${subject.label}${count}:\n│ ${lines.join(' ⏎\n│ ')}`);
+  return parts.join('\n\n');
+}
+
+function personOnlyDenyMessage(decisionReason, why) {
+  const reason = reasonLine(decisionReason);
+  return `Not run: Claude Code marks this as person-only${reason ? ` (${reason})` : ''}, and ${why}. `
+    + 'Do not work around it by splitting, scripting or re-issuing it through another tool.';
+}
+
+// Allow/Deny card over the question bridge, no typed replies. Only the exact
+// "Allow once" allows, and never with `updatedPermissions`: the next such ask
+// asks again.
+async function askPersonOnly({ askUserBridge, toolName, input, options, signal, dbg }) {
+  const reason = options?.decisionReason;
+  const kind = options?.decisionReasonType || 'defaultToNo';
+  const deny = (why, outcome) => {
+    dbg('person-only ask', toolName, kind, outcome);
+    return { behavior: 'deny', message: personOnlyDenyMessage(reason, why) };
+  };
+  if (signal?.aborted) return deny('the turn was stopped', 'aborted');
+  if (subjectTooLong(input)) {
+    dbg('person-only ask', toolName, kind, 'too-long');
+    return { behavior: 'deny', message: PERSON_ONLY_TOO_LONG_MESSAGE };
+  }
+  if (!askUserBridge) return deny('the relay could not show the question', 'no-bridge');
+  const question = personOnlyQuestionText(toolName, input, reason);
+  let result;
+  try {
+    result = await askUserBridge.handleAskUserQuestion({
+      questions: [{
+        question,
+        header: 'Safety check',
+        options: [{ label: PERSON_ONLY_ALLOW_CHOICE }, { label: PERSON_ONLY_DENY_CHOICE }],
+      }],
+    }, {
+      signal,
+      source: PERSON_ONLY_QUESTION_SOURCE,
+      rationale: PERSON_ONLY_RATIONALE,
+      allowFreeform: false,
+    });
+  } catch (error) {
+    if (signal?.aborted) return deny('the turn was stopped', 'aborted');
+    dbg('person-only ask bridge failed', error?.message || String(error));
+    return deny('the relay could not show the question', 'bridge-failed');
+  }
+  if (signal?.aborted) return deny('the turn was stopped', 'aborted');
+  if (result?.timedOut) return deny('no answer came before the timeout', 'timed-out');
+  const answer = String(result?.answers?.[question] ?? '').trim();
+  if (answer === PERSON_ONLY_ALLOW_CHOICE) {
+    dbg('person-only ask', toolName, kind, 'allowed');
+    return { behavior: 'allow', updatedInput: input };
+  }
+  if (!answer || answer === PERSON_ONLY_DENY_CHOICE) return deny('the user denied it', 'denied');
+  return deny(`the user denied it: ${capText(escapeInvisible(answer), PERSON_ONLY_TYPED_ANSWER_MAX)}`, 'denied-other');
+}
+
 /**
  * Build the `canUseTool` callback for one turn. Everything is auto-allowed
- * (parity with the Copilot workers' `--allow-all` posture); the only
- * interceptions are AskUserQuestion (bridged to relay question cards) and
- * ExitPlanMode (surfaces the plan_ready board).
+ * (parity with the Copilot workers' `--allow-all` posture) except the asks
+ * Claude Code marks as person-only (an Allow/Deny relay card, see
+ * isPersonOnlyAsk); the other interceptions are AskUserQuestion (bridged to
+ * relay question cards) and ExitPlanMode (surfaces the plan_ready board).
  *
  * ExitPlanMode is DENIED after the board is posted: allowing it tells the CLI
  * the user approved the plan, and the same turn rolls straight into
@@ -658,8 +799,12 @@ export function createCanUseTool({
   onExitPlanMode,
   dbg = () => {},
 } = {}) {
-  return async function canUseTool(toolName, input, { signal } = {}) {
+  return async function canUseTool(toolName, input, options = {}) {
+    const signal = options?.signal;
     const normalizedToolName = String(toolName || '').trim();
+    if (isPersonOnlyAsk(options)) {
+      return askPersonOnly({ askUserBridge, toolName: normalizedToolName, input, options, signal, dbg });
+    }
     try {
       if (normalizedToolName === 'AskUserQuestion' && askUserBridge) {
         const { answers } = await askUserBridge.handleAskUserQuestion(input, { signal });