@assuredloop/orca-bot-kit 0.25.1 → 0.25.3

package/README.md

@@ -350,6 +350,11 @@ address that is none of your bots folder's sessions, the hook tells it so, and
 names the address `obk message to` would have given. The message goes either
 way ([ADR 0032](docs/adr/0032-a-native-message-outside-the-fleet-is-warned-about.md)).
 
+And a third: at the end of each turn, it tells the session once about fleet
+mail the kit sent it that is still unread, without typing into its tab
+([ADR 0035](docs/adr/0035-messaging-transport.md)). It asks Orca only when the kit
+knows of mail for that session.
+
 A Codex bot gets one more hook too. Inside Codex's sandbox the kit cannot always
 tell whether the receiver of a message has its harness in front, as for a Claude
 session busy running a command, so `obk message send` leaves that nudge, and the
@@ -555,7 +560,7 @@ verdict: which of these matter, and in what order, is for you or for Bot Father.
 ## Sessions and bots that talk
 
 Ask the kit how to reach a session, and it answers with the road and the
-address ([ADR 0030](docs/adr/0030-messaging-transport.md)):
+address ([ADR 0035](docs/adr/0035-messaging-transport.md)):
 
 ```sh
 obk message to    --bots /path/to/my-bots --to api-bot/daily
@@ -598,11 +603,17 @@ mailbox where it was and says so, and the harness starts all the same. A check
 holds its turn for 40 seconds at most: with more mail than it reads in that
 time, it shows what it read and says the rest is still waiting.
 
-Nothing in a mailbox wakes anybody, so `message send` also types one line into
-the receiver's tab telling it to look. Both harnesses take a typed line as the
-next thing to do rather than cutting into what they are doing, which is the
-whole of "queued, not interrupting". A session that is not up is not typed
-into at all; its message waits.
+Nothing in a mailbox wakes anybody, so each message gets one signal that tells
+the receiver to look. Orca's own notice comes first: Orca types it into an idle
+tab. The kit watches an idle receiver for up to 8 seconds, and reads the
+receiver's own record of its turns. When Orca's notice is there, the kit types
+nothing. When no turn started, the kit types its own line. A Claude session busy
+with a turn gets nothing typed: its hook tells it at the end of the turn. A busy
+Codex session gets the kit's line, which Codex takes into the turn it is having.
+The send says which signal went. A session that is not up is not typed into at
+all; its message waits. When a session is retired, the kit says how many
+messages sent to it were not read with `obk message check`, and who sent them
+([ADR 0035](docs/adr/0035-messaging-transport.md)).
 
 A message longer than 4 KiB is written to a file beside your bots folder and
 named in the message, so a long one arrives whole without landing a document in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/clear.js

@@ -19,7 +19,7 @@ import { botDir, readBot } from './bot.js';
 import { claudeTranscript, codexRollout } from './conversations.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 import { eachLine, firstLine } from './lines.js';
-import { findProject, orca, QUESTION_ON_SCREEN, questionIn, screenRows, tabs, tabToTypeInto, TIMED_OUT } from './orca.js';
+import { FEEDBACK_PANEL, feedbackPanelIn, findProject, orca, QUESTION_ON_SCREEN, questionIn, screenRows, tabs, tabToTypeInto, TIMED_OUT } from './orca.js';
 import { botsNamed, sessionsOf, typeListLine } from './up.js';
 
 /** The harness's own command for each, as typed into its input line. Codex's clear is `/new` (tech notes, section 3). */
@@ -201,7 +201,7 @@ async function enter(it, verb, before = () => {}) {
         if (typing === undefined) throw new Error(`${it.name}: ${TYPING_HELD}. Run this again in a moment.`);
         before();
       },
-      cannot: (wrong) => (verb === 'compact' && wrong.menu ? ` ${harnessName(it.harness)} here cannot compact: its menu does not offer ${COMMANDS[verb][it.harness]}.` : ''),
+      cannot: (wrong) => (verb === 'compact' && wrong.menu && it.harness === 'codex' ? ` ${harnessName(it.harness)} here cannot compact: its menu does not offer ${COMMANDS[verb][it.harness]}.` : ''),
     });
     return { ...typed, typing };
   } catch (error) {
@@ -223,14 +223,18 @@ async function enter(it, verb, before = () => {}) {
 export async function typeCommand(it, command, { before = () => {}, check = menuWrong, cannot = () => '', deadline = Infinity } = {}) {
   // On Codex, what is typed cannot be read back once its menu is open, so
   // nothing may be in its input line before: no draft for the command to join.
-  const emptyLine = (rows) => {
-    if (it.harness !== 'codex') return;
+  // On Claude Code, Orca gives a draft in the line beside the screen (#510).
+  const emptyLine = ({ rows, draft }) => {
+    if (it.harness !== 'codex') {
+      if (draft !== undefined) throw new Error(`${it.name}: nothing was typed, because its input line holds a draft: it reads "${draft}".${shownEnd(rows)}`);
+      return;
+    }
     const line = rows.findLast((row) => /^ *›/.test(row))?.trim();
     if (!CODEX_EMPTY.includes(line)) {
       throw new Error(`${it.name}: nothing was typed, because its input line is not empty: it reads "${line ?? 'nothing'}".${shownEnd(rows)}`);
     }
   };
-  emptyLine((await idleTab(it)).rows);
+  emptyLine(await idleTab(it));
   const version = it.harness === 'codex' ? codexVersion(readBook(it.home).sessions[it.session]?.session) : undefined;
 
   before();
@@ -238,7 +242,7 @@ export async function typeCommand(it, command, { before = () => {}, check = menu
   // with no wait, before the first key (#480 review).
   const ready = lookAt(it);
   if (ready.why !== undefined) throw new Error(`${it.name}: nothing was typed, because ${ready.why}.`);
-  emptyLine(ready.rows);
+  emptyLine(ready);
   const { handle } = ready;
   const typedAt = Date.now();
   // One character a send, each after a look through the gate, so nothing goes
@@ -329,7 +333,7 @@ async function idleTab(it) {
 }
 
 /**
- * One look through the typing gate at the session's tab: `{ handle }` when
+ * One look through the typing gate at the session's tab: `{ handle, rows, draft }` when
  * nothing on its screen asks a question and nothing says it is at work, and,
  * with `idle`, Orca's tui-idle answered ok; or `{ why }`, naming the signal,
  * with `moved` when the book holds another tab for the session now, or, where
@@ -350,8 +354,8 @@ function lookAt(it, { idle = true } = {}) {
   const found = tabToTypeInto(it.home, it.tabId, idle ? LOOK_MS : CHAR_LOOK_MS);
   if (found.blocked !== undefined) {
     return {
-      why: found.blocked === QUESTION_ON_SCREEN
-        ? 'a question of its harness\'s own is on its screen'
+      why: found.blocked === FEEDBACK_PANEL ? PANEL_WHY
+        : found.blocked === QUESTION_ON_SCREEN ? 'a question of its harness\'s own is on its screen'
         : `a question is waiting on its screen: Orca says ${found.blocked}`,
     };
   }
@@ -364,7 +368,7 @@ function lookAt(it, { idle = true } = {}) {
   const signal = signalIn(found.rows);
   if (signal !== undefined) return { why: signal };
   if (idle && !found.idle) return { why: 'it is busy with a turn: Orca\'s tui-idle did not answer ok' };
-  return { handle: found.handle, rows: found.rows };
+  return { handle: found.handle, rows: found.rows, draft: found.draft };
 }
 
 /**
@@ -384,27 +388,38 @@ async function typedWrong(handle, harness, command, version, check) {
     // a question that shows on it stops it at once (review of c1e5ba4).
     const signal = seen.rows === undefined ? undefined : signalIn(seen.rows);
     if (signal !== undefined) return { why: signal, rows: seen.rows };
-    const wrong = seen.rows === undefined ? { why: `its screen could not be read (${seen.unreadable})` } : check(seen.rows, harness, command, version);
+    const wrong = seen.rows === undefined ? { why: `its screen could not be read (${seen.unreadable})` } : check(seen.rows, harness, command, version, seen.draft);
     if (wrong === undefined || Date.now() >= until) return wrong && { ...wrong, rows: seen.rows };
     await pause(ASK_MS);
   }
 }
 
+/**
+ * Why nothing goes in while Claude Code's panel of feedback drafts is open
+ * (#502): it reads single keys from the input line, and one sends a draft to
+ * Anthropic, so only the user answers it.
+ */
+const PANEL_WHY = 'its panel of feedback drafts is open above its input box, and the kit does not answer it, since a draft sent from it goes to Anthropic: it clears once the user reviews, sends or dismisses the drafts in that tab';
+
 /** Why `rows` say not to type now, as the look says it, or undefined: a turn at work, or a question. */
 function signalIn(rows) {
   const working = rows.find((row) => AT_WORK.some((marker) => marker.test(row)));
   if (working !== undefined) return `it is busy with a turn: its screen shows "${working.trim()}"`;
+  if (feedbackPanelIn(rows)) return PANEL_WHY;
   if (questionIn(rows)) return 'a question of its harness\'s own is on its screen';
   return undefined;
 }
 
-function menuWrong(rows, harness, command, version) {
+function menuWrong(rows, harness, command, version, draft) {
   const at = rows.findLastIndex((row) => /^ *[›❯]/.test(row));
   if (at < 0) return { why: 'its screen shows no input line' };
   // Claude Code 2.1.288 puts a non-breaking space after its pointer (live run 4).
   const line = rows[at].replaceAll('\u00a0', ' ').trim();
   if (harness === 'codex') return codexMenuWrong(rows, at, line, command, version);
-  if (line !== `${POINTER[harness]} ${command}`) return { why: `its input line reads "${line}"` };
+  // Orca 1.4.223 gives the line's text as the draft, and Claude Code 2.1.296's
+  // line on the screen then reads its pointer alone (#510, probe 4).
+  const text = draft === undefined ? line : `${POINTER[harness]} ${draft}`;
+  if (text !== `${POINTER[harness]} ${command}`) return { why: `its input line reads "${text}"` };
   return claudeMenuWrong(rows, at, command);
 }
 
@@ -412,15 +427,19 @@ function menuWrong(rows, harness, command, version) {
  * Claude Code 2.1.288 draws its slash menu above its input box's top rule, a
  * row of ─: a row per command, starting with it, its description wrapped onto
  * rows set far in (live run 4). No pointer marks a selection, so the first
- * command row there has to be the command.
+ * command row there has to be the command. Claude Code 2.1.296 starts the
+ * selected row with its pointer, `  ❯ /compact`, and that row has to be the
+ * command (#510, probes 1 and 2). The menu's pointer is above the rule, the
+ * input line's below it, so the one is never taken for the other.
  */
 function claudeMenuWrong(rows, at, command) {
   const rule = rows.slice(0, at).findLastIndex((row) => /^\s*─{3}/.test(row));
   const menu = [];
-  for (let up = rule - 1; up >= 0 && (/^ {1,4}\/\S/.test(rows[up]) || /^ {20,}\S/.test(rows[up])); up -= 1) menu.unshift(rows[up]);
-  const first = menu.find((row) => /^ {1,4}\//.test(row));
-  if (rule < 0 || first === undefined) return { why: 'no menu of commands came up above its input box', menu: true };
-  if (first.trim().split(/\s+/)[0] !== command) return { why: `the first row of its menu is "${first.trim()}"`, menu: true };
+  for (let up = rule - 1; up >= 0 && (/^ {1,4}(?:❯ +)?\/\S/.test(rows[up]) || /^ {20,}\S/.test(rows[up])); up -= 1) menu.unshift(rows[up]);
+  const pointed = menu.find((row) => /^ {1,4}❯ +\//.test(row));
+  const selected = pointed === undefined ? menu.find((row) => /^ {1,4}\//.test(row)) : pointed.replace(/^ *❯ +/, '');
+  if (rule < 0 || selected === undefined) return { why: 'no menu of commands came up above its input box', menu: true };
+  if (selected.trim().split(/\s+/)[0] !== command) return { why: `the ${pointed === undefined ? 'first' : 'selected'} row of its menu is "${selected.trim()}"`, menu: true };
   return undefined;
 }
 

package/src/cli.js

@@ -18,14 +18,14 @@ import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { nameSession } from './name.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
-import { checkMail, decideLeftNudges, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
+import { checkMail, decideLeftNudges, lookUp, noMailboxYet, sendMessage, sessionInTab, stillUnread, WATCH_MS } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE, TERMINAL_ENV } from './orca.js';
 import { allowCommand, allowIn, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
 import { clearSession, compactSession } from './clear.js';
-import { retireBot, retireSession } from './retire.js';
+import { retireBot, retireSession, unreadWords } from './retire.js';
 import { sentWarning } from './sent.js';
 import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
@@ -281,6 +281,11 @@ Usage:
                             nudges a send there left because it could not
                             tell from inside Codex's sandbox, and types each
                             one or says why not.
+  obk session mail --bots <path> --bot <bot>
+                            For the kit's own hook, not for typing: at the end
+                            of a Claude session's turn, it tells the session
+                            once about each fleet mail the kit sent it that is
+                            still unread. It types nothing into the tab.
   obk session name --bots <path> --bot <bot>
                             For the kit's own hook, not for typing: after a
                             Codex session's turn, it names the session's thread
@@ -329,6 +334,7 @@ const COMMANDS = {
   'session record': ['bots', 'bot'],
   'session sent': ['bots', 'bot'],
   'session nudge': ['bots', 'bot'],
+  'session mail': ['bots', 'bot'],
   'session name': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
   'temp make': ['bots', 'name'],
@@ -463,6 +469,7 @@ async function run(argv) {
   // there included, so it goes before anything that can complain (ADR 0032).
   if (command === SENT) return sent(path.resolve(values.bots));
   if (command === NUDGE) return nudgeLeft();
+  if (command === MAIL) return mailHook(path.resolve(values.bots), values.bot);
   if (command === NAME) return nameThread(path.resolve(values.bots), values.bot);
 
   // One fleet, one identity, whatever spelling of its path was given (#164).
@@ -534,6 +541,7 @@ const ANSWER_IT = [
 const RECORD = 'session record';
 const SENT = 'session sent';
 const NUDGE = 'session nudge';
+const MAIL = 'session mail';
 const NAME = 'session name';
 
 /**
@@ -559,11 +567,11 @@ function sent(bots) {
  * what became of each, as Codex's `additionalContext` (#350, ADR 0034). Silent
  * when nothing was left, never a decision, and never anything but exit 0.
  */
-function nudgeLeft() {
+async function nudgeLeft() {
   try {
     const said = JSON.parse(readFileSync(0, 'utf8'));
     if (said?.hook_event_name !== 'PostToolUse') return 0;
-    const decided = decideLeftNudges(process.env[TAB_ENV]);
+    const decided = await decideLeftNudges(process.env[TAB_ENV]);
     if (decided.length > 0) {
       const words = decided.map((one) => `Your mail "${one.subject}" to ${one.to}: ${one.nudged ? "the kit's hook nudged its tab, from outside Codex's sandbox:" : "the kit's hook looked at its tab from outside Codex's sandbox, and"} ${nudgeLine(one, one.to).trim()}`);
       process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: words.join('\n') } })}\n`);
@@ -574,6 +582,24 @@ function nudgeLeft() {
   return 0;
 }
 
+/**
+ * What the kit's Claude Code Stop hook does at a turn end (#509, ADR 0035): tell
+ * the session once about fleet mail still unread, as the Stop event's
+ * additional context, which the session goes on with. Not a block: Claude Code
+ * 2.1.296 draws a block's reason in red as "Stop hook error", and its additional
+ * context as "Stop hook feedback". Nothing typed into the tab; never anything
+ * but exit 0; silent whenever it cannot be sure.
+ */
+function mailHook(bots, bot) {
+  try {
+    const reason = stillUnread(sameFleet(bots), bot, JSON.parse(readFileSync(0, 'utf8')), process.env[TAB_ENV], process.env[TERMINAL_ENV]);
+    if (reason !== undefined) process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'Stop', additionalContext: reason } })}\n`);
+  } catch {
+    // Nothing: a hook does not disturb the session it runs in.
+  }
+  return 0;
+}
+
 /**
  * What the kit's Codex Stop hook does at a turn end: name the session's thread
  * after its bot and session, once it is idle (#480). Silent, never a decision,
@@ -703,6 +729,7 @@ const commands = {
           ...withLines(retired.retiredWith, retired.session),
           ...closedLines(retired.closed),
           `retired    ${retired.bot} ${retired.session}: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+          ...unreadLines(retired.unread),
           ...leftLines(retired.promptsLeft),
         ],
       };
@@ -732,6 +759,7 @@ const commands = {
           retired.windowReloaded ? "reloaded   Orca's window, so its sidebar no longer shows the project" : RELOAD_LINE,
         ]),
         `retired    ${retired.bot}: moved to ${path.relative(bots, retired.moved)}, with its book, charter and memory`,
+        ...(retired.unread ?? []).flatMap((one) => unreadLines(one, `${retired.bot}/${one.session}`)),
         ...leftLines(retired.promptsLeft),
       ],
     };
@@ -788,6 +816,7 @@ const commands = {
         ...withLines(retired.retiredWith, retired.session),
         ...closedLines(retired.closed),
         `retired    ${retired.bot} ${retired.session}, a temporary session of ${retired.maker}'s: off ${path.join('bots', retired.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+        ...unreadLines(retired.unread),
         ...leftLines(retired.promptsLeft),
       ],
     };
@@ -1081,10 +1110,10 @@ const commands = {
     };
   },
 
-  'message send'(bots, values) {
+  async 'message send'(bots, values) {
     const tab = callerTab(bots, values.from === undefined);
     refuseWhenOrcaIsDown();
-    const answer = sendMessage(bots, {
+    const answer = await sendMessage(bots, {
       to: values.to,
       from: values.from,
       tab,
@@ -1248,13 +1277,26 @@ function toLines(answer, bots, where) {
  * about the message.
  */
 function nudgeLine(answer, where) {
+  const seconds = answer.watchedMs === undefined ? '' : ` in ${Math.max(Math.round(answer.watchedMs / 1000), 1)} s`;
+  if (answer.signal === 'orca') return `             Orca's notice reached it${seconds}, so no line was typed: it reads the mail from there.`;
+  if (answer.signal === 'hook') {
+    return answer.because === 'busy'
+      ? "             it is busy with a turn, so nothing was typed into its tab: its own hook tells it about the mail when that turn ends."
+      : `             a turn of other work started in its tab${seconds}, not Orca's notice, so nothing was typed: its own hook tells it about the mail when that turn ends.`;
+  }
+  const why = {
+    'no-turn': `no turn started in its tab in ${WATCH_SECONDS} s, so the kit's line was typed`,
+    busy: "it is busy with a turn, and Codex takes a line into the turn it is having, so the kit's line was typed",
+    'other-turn': "a turn of other work started in its tab, not Orca's notice, so the kit's line was typed",
+  }[answer.because];
+  const head = why === undefined ? '             ' : `             ${why}: `;
   if (answer.nudged && answer.nudgeWatched === false) {
-    return `             its tab was typed into, and Orca could not say whether it was taken: ${answer.nudgeUnseen} The message waits in its mailbox for its next check either way.`;
+    return `${head}its tab was typed into, and Orca could not say whether it was taken: ${answer.nudgeUnseen} The message waits in its mailbox for its next check either way.`;
   }
   if (answer.nudged && answer.nudgeUnseen !== undefined) {
-    return '             its tab was typed into, but Orca did not see the line start a turn: it may be queued behind the work in hand, or lost. The message waits in its mailbox for its next check either way.';
+    return `${head}its tab was typed into, but Orca did not see the line start a turn: it may be queued behind the work in hand, or lost. The message waits in its mailbox for its next check either way.`;
   }
-  if (answer.nudged) return '             its tab was told to look; it will read it when it is done with what it is doing.';
+  if (answer.nudged) return `${head}its tab was told to look; it will read it when it is done with what it is doing.`;
   if (answer.blocked !== undefined) {
     return `             its tab has something waiting to be answered (${answer.blocked}), so nothing was typed into it. Settle that, and the mail is there.`;
   }
@@ -1267,6 +1309,9 @@ function nudgeLine(answer, where) {
   return `             ${where} is not up, so nothing was typed anywhere: the message waits in its mailbox.`;
 }
 
+/** The watch before the kit's line, as the send says it (#509, ADR 0035). */
+const WATCH_SECONDS = WATCH_MS / 1000;
+
 /**
  * What there is to say about the work dir this command was given: one finding
  * when it leads out of the bot home, through `..` or a link or as a path
@@ -1301,9 +1346,13 @@ const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab
 const withLines = (retiredWith, session) => retiredWith.flatMap((gone) => [
   ...closedLines(gone.closed),
   `retired    ${gone.bot} ${gone.session}, a temporary session of ${gone.maker}'s, along with ${session}: off ${path.join('bots', gone.bot, 'bot.yaml')}, and its conversations kept in the book under retired`,
+  ...unreadLines(gone.unread),
   ...leftLines(gone.promptsLeft),
 ]);
 
+/** The mail a retired session did not read, as far as the kit knows (#509). */
+const unreadLines = (unread, who = 'it') => (unread === undefined ? [] : [`unread     ${unreadWords(unread, who)}`]);
+
 /** What a retire could not remove, and how to: nothing reads these files now (#393). */
 const leftLines = (left = []) => left.flatMap(({ file, reason }) => [
   `left       ${file}: it could not be removed (${reason}). Nothing reads it now.`,

package/src/conversations.js

@@ -159,6 +159,43 @@ export function heldAsUserTurn(harness, file, text) {
   return held;
 }
 
+/**
+ * Where the harness keeps the conversation `id` of this bot home, and how long
+ * that record is now: `{ harness, file, size }`, so a later look reads only
+ * what was written after this moment. Undefined when there is no id, no
+ * record, or it cannot be read (#509).
+ */
+export function recordMark(harness, home, id) {
+  if (typeof id !== 'string' || id === '') return undefined;
+  try {
+    const file = harness === 'codex' ? codexRollout(id) : claudeTranscript(home, id);
+    if (file === undefined) return undefined;
+    const found = statSync(file);
+    return found.isFile() ? { harness, file, size: found.size } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether a turn of the user's written after `mark` holds `text` anywhere in
+ * it (#509). A record that cannot be read says no: not seeing a thing is not
+ * seeing it.
+ */
+export function userTurnSince(mark, text) {
+  if (mark === undefined || mark === null) return false;
+  let held = false;
+  try {
+    eachLine(mark.file, (line) => {
+      held = line !== undefined && userTexts(mark.harness, line).some((said) => said.includes(text));
+      return held;
+    }, { from: mark.size });
+  } catch {
+    return false;
+  }
+  return held;
+}
+
 /** The texts of one record line, when it is a turn of the user's. */
 function userTexts(harness, line) {
   let parsed;

package/src/health.js

@@ -96,7 +96,7 @@ export function orcaSettingFindings() {
 const unreadableSettings = (where) => finding(
   'orca',
   where,
-  `The kit could not read Orca's own settings at ${where}, so it cannot say whether Orca adds default launch arguments of its own. When those carry a permission bypass, every session Orca launches, relaunches or resumes runs in that mode whatever approval level the kit asked for.`,
+  `The kit could not read Orca's own settings at ${where}, so it cannot say whether Orca adds default launch arguments of its own. It looks for them in profile-state.db in each Orca profile, or in orca-data.json for an older Orca. When those carry a permission bypass, every session Orca launches, relaunches or resumes runs in that mode whatever approval level the kit asked for.`,
 );
 
 /** Whether a line of arguments carries `flag` as a word of its own. */

package/src/hooks.js

@@ -54,6 +54,20 @@ const SENT_MATCHER = 'SendMessage';
 export const sentCommand = (bots, bot, cli = ownCli()) =>
   `${shellWord(cli)} session sent --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
+/**
+ * Claude Code's third kit hook: at each turn end, it tells the session once
+ * about fleet mail the kit sent it that is still unread (#509, ADR 0035).
+ * Claude Code only: on Codex a new hook entry puts every session on "Hooks
+ * need review", and that waits for #511. It asks Orca only when the kit's hint
+ * holds mail for the session, and gives Orca at most ten seconds of its thirty.
+ */
+const MAIL_EVENT = 'Stop';
+const MAIL_TIMEOUT = 30;
+
+/** What the mail hook runs, by the kit's own path, as `hookCommand` does. */
+export const mailCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session mail --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+
 /**
  * Codex's second kit hook: after each command its shell tool ran, outside
  * Codex's sandbox, it decides the mail nudges a send in that command could not
@@ -250,7 +264,7 @@ function withKitHook(hooks, file, mine) {
 
 /** Each harness's kit hooks beside its session hook, as `toolHookOf` gives each. */
 const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
-  (harness === 'claude' ? ['sent'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
+  (harness === 'claude' ? ['sent', 'mail'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
 
 /**
  * One of the kit's hooks beside its session hook: Claude Code's after a native
@@ -259,6 +273,15 @@ const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
  * goes, how the kit knows its own, and what is lost without it.
  */
 function toolHookOf(kind, bots, bot, cli = ownCli()) {
+  if (kind === 'mail') {
+    return {
+      kind,
+      event: MAIL_EVENT,
+      pattern: KIT_MAIL,
+      mine: { type: 'command', command: mailCommand(bots, bot, cli), timeout: MAIL_TIMEOUT },
+      missing: 'a Claude session busy when fleet mail came is never told about it at the end of its turn, and nothing is typed into its tab either (#509)',
+    };
+  }
   if (kind === 'name') {
     return {
       kind,
@@ -355,6 +378,7 @@ const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
 const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const KIT_MAIL = new RegExp(String.raw`^(${WORD}) session mail --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 
 /** The program a bot made before the kit named itself by path runs. */

package/src/launch.js

@@ -51,7 +51,7 @@ export const harnessOf = (session, botHarness) => (set(session.harness) ? sessio
 
 /**
  * A session's name on Claude Code, which is also the address another Claude
- * session writes to (ADR 0030). It goes on the launch line as `-n`, and it is
+ * session writes to (ADR 0035). It goes on the launch line as `-n`, and it is
  * re-applied every time the session is started: a resume keeps the name by
  * itself (tech notes, section 2), and the kit does not depend on that.
  *
@@ -224,7 +224,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
 
   if (harness === 'claude') {
     // The name is the address other Claude sessions write to, so it goes on
-    // every launch line, a resume included (ADR 0030).
+    // every launch line, a resume included (ADR 0035).
     if (address !== undefined) words.push('-n', address);
     // The context window rides on the model name: `sonnet[1m]`.
     if (set(session.model)) words.push('--model', set(session.context) ? `${session.model}[${session.context}]` : session.model);