@assuredloop/orca-bot-kit 0.21.0 → 0.23.0

package/src/cli.js

@@ -17,19 +17,20 @@ import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
-import { checkMail, lookUp, noMailboxYet, sendMessage, sessionInTab } from './message.js';
+import { checkMail, decideLeftNudges, lookUp, noMailboxYet, sendMessage, sessionInTab } 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 { sentWarning } from './sent.js';
 import { readRoster } from './roster.js';
 import { buildAgents, buildRules, CODEX_CAP } from './rules.js';
 import { addSkill, buildSkills, linkSkills, removeSkill } from './skills.js';
 import { addSource, fetchSources } from './sources.js';
-import { makeTemp, retireTemp, trustHooks } from './temp.js';
+import { listRoles, makeTemp, optionsLine, retireTemp, trustHooks } from './temp.js';
 import { readUsage } from './usage.js';
 import { BOT_FATHER, bringUp, ownMailbox } from './up.js';
 
@@ -99,7 +100,7 @@ Usage:
                             project holds a tab your book does not name, and
                             moves the folder only once Orca no longer lists
                             the project.
-  obk temp make --bots <path> --name <session>
+  obk temp make --bots <path> --name <session> [--role <role>[:<option>]]
                 (--prompt <text> | --prompt-file <path>) [--harness claude|codex]
                 [--model <m>] [--effort <e>] [--context <c>]
                 [--approval ${APPROVALS.join('|')}] [--extra-arg=<arg>]...
@@ -113,6 +114,19 @@ Usage:
                             work/<session>, and has the task as its start
                             prompt. The book records it as temporary, made by
                             you.
+                            --role takes the harness, model, effort and context
+                            of an option of a role in the bot's temp_roles, the
+                            role's first option when none is named, and the
+                            role's prompt file when no task is given; a flag
+                            still wins, and what the option leaves out is
+                            taken as above. The session is named
+                            <role>-<session>. A role's cap, if it has one,
+                            counts its open sessions. The answer says where
+                            each setting came from.
+  obk temp roles --bots <path>
+                            Run in a session's own tab: list the roles of your
+                            bot's temp_roles, each option with what it is for,
+                            and each role's cap and open sessions.
   obk temp retire --bots <path> --name <session>
                             Run in the maker's own tab: retire a temporary
                             session it made, as obk retire does. It refuses a
@@ -191,6 +205,18 @@ Usage:
                             one command that closes a tab, it closes only the
                             tabs your book names, and it will not close one
                             whose conversation the book cannot name.
+  obk session clear --bots <path> --bot <bot> --session <name>
+                            Start the session on a new conversation: /clear on
+                            Claude Code, /new on Codex. It waits up to 30 s for
+                            the session to be idle, types nothing into a busy
+                            one or one with a question on its screen, and
+                            answers once the book holds the new conversation.
+                            The kit's hook gives it its start prompt again.
+  obk session compact --bots <path> --bot <bot> --session <name>
+                            Compact the session's conversation with /compact,
+                            as safely as session clear, and answer once the
+                            harness's record shows it, or after 5 minutes that
+                            it is not confirmed yet.
   obk health --bots <path> [--bot <bot>]
                             Say what is wrong with your setup: configuration
                             that will not work, a skill that is not where its
@@ -242,6 +268,12 @@ Usage:
                             Claude session's native message, it warns the
                             session when the address was none of this bots
                             folder's own. It never stops a message.
+  obk session nudge --bots <path> --bot <bot>
+                            For the kit's own hook, not for typing: after a
+                            Codex session's shell command, it decides the mail
+                            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 mailbox --bots <path> --bot <bot> --session <name>
                             For the kit's own launch line, not for typing: run
                             in the session's own tab, it gives the session its
@@ -277,13 +309,17 @@ const COMMANDS = {
   'source add': ['bots', 'name', 'repo', 'ref'],
   'session add': ['bots', 'bot', 'name'],
   'session change': ['bots', 'bot', 'session'],
+  'session clear': ['bots', 'bot', 'session'],
+  'session compact': ['bots', 'bot', 'session'],
   'message to': ['bots', 'to'],
   'message send': ['bots', 'to', 'subject'],
   'message check': ['bots'],
   'session record': ['bots', 'bot'],
   'session sent': ['bots', 'bot'],
+  'session nudge': ['bots', 'bot'],
   'session mailbox': ['bots', 'bot', 'session'],
   'temp make': ['bots', 'name'],
+  'temp roles': ['bots'],
   'temp retire': ['bots', 'name'],
   'temp trust-hooks': ['bots', 'name'],
 };
@@ -306,6 +342,7 @@ const NEEDED = {
   to: '--to <bot>/<session>: which session to write to',
   from: '--from <bot>/<session>: which session is writing',
   subject: '--subject <text>: what the message is about',
+  role: '--role <role>[:<option>]: which role of the bot\'s temp_roles',
 };
 
 /** The flags that name something. A name that is empty names nothing. */
@@ -360,6 +397,7 @@ async function run(argv) {
       ...Object.fromEntries(SETTINGS.map(([flag]) => [flag, { type: 'string' }])),
       'extra-arg': { type: 'string', multiple: true },
       'run-on': { type: 'string' },
+      role: { type: 'string' },
       json: { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
       version: { type: 'boolean' },
@@ -410,6 +448,7 @@ async function run(argv) {
   // The send hook is quiet whatever it is given, a bots folder that is not
   // 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();
 
   // One fleet, one identity, whatever spelling of its path was given (#164).
   const bots = command === 'init' ? path.resolve(values.bots) : sameFleet(path.resolve(values.bots));
@@ -477,6 +516,7 @@ const ANSWER_IT = [
 /** The commands a harness runs rather than a person: the kit's hooks. */
 const RECORD = 'session record';
 const SENT = 'session sent';
+const NUDGE = 'session nudge';
 
 /**
  * What the kit's send hook says after a native message: a warning the session
@@ -495,6 +535,27 @@ function sent(bots) {
   return 0;
 }
 
+/**
+ * What the kit's Codex hook does after a shell command: decide the nudges a
+ * send in this tab left for it, outside Codex's sandbox, and say to the session
+ * 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() {
+  try {
+    const said = JSON.parse(readFileSync(0, 'utf8'));
+    if (said?.hook_event_name !== 'PostToolUse') return 0;
+    const decided = 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`);
+    }
+  } catch {
+    // Nothing: a hook does not disturb the session it runs in.
+  }
+  return 0;
+}
+
 /**
  * What the kit's hook does with what the harness told it, and what it answers.
  *
@@ -647,21 +708,41 @@ const commands = {
     const tab = callerTab(bots, true);
     refuseWhenOrcaIsDown();
     const given = { name: values.name };
-    for (const [flag, key] of [['harness', 'harness'], ['model', 'model'], ['effort', 'effort'], ['approval', 'approval'], ['prompt', 'prompt'], ['prompt-file', 'prompt_file']]) {
+    for (const [flag, key] of [['harness', 'harness'], ['model', 'model'], ['effort', 'effort'], ['approval', 'approval'], ['prompt', 'prompt'], ['prompt-file', 'prompt_file'], ['role', 'role']]) {
       if (values[flag] !== undefined) given[key] = values[flag];
     }
     if (values.context !== undefined) given.context = asNumberOrText(values.context);
     if (values['extra-arg'] !== undefined) given.extra_args = values['extra-arg'];
     const made = await makeTemp(bots, { tab, ...given });
     const { tabs, rules, skills, permissions, paused, projects } = made.up;
-    const answer = { bots, bot: made.bot, session: made.session, maker: made.maker, settings: made.settings, created: [], completed: [], rules, skills, permissions, tabs, paused, projects };
+    const answer = {
+      bots, bot: made.bot, session: made.session, maker: made.maker, ...(made.role === undefined ? {} : { role: made.role }), settings: made.settings, chosen: made.chosen,
+      created: [], completed: [], rules, skills, permissions, tabs, paused, projects,
+    };
     const retire = `${shellWord(ownCli())} temp retire --bots ${shellWord(bots)} --name ${made.session}`;
     return {
       answer,
-      lines: tabLines(answer, `Made ${made.bot}/${made.session}, a temporary session of ${made.maker}'s, working in work/${made.session}. Retire it when its work is done:  ${retire}`),
+      lines: [
+        ...(made.role === undefined ? [] : [`role       ${made.role.name}:${made.role.option}${made.role.for === undefined ? '' : `, for ${made.role.for}`}. Its options: ${optionsLine(made.role.options)}`]),
+        ...Object.entries(made.chosen).map(([setting, one]) => `${setting.padEnd(9)}  ${one.value === undefined ? `the ${one.from}` : `${one.value}, from ${one.from === 'flag' ? `--${setting}` : `the ${one.from}`}`}`),
+        ...tabLines(answer, `Made ${made.bot}/${made.session}, a temporary session of ${made.maker}'s, working in work/${made.session}. Retire it when its work is done:  ${retire}`),
+      ],
     };
   },
 
+  'temp roles'(bots) {
+    const tab = callerTab(bots, true);
+    const listed = listRoles(bots, { tab });
+    const lines = listed.roles.length === 0
+      ? [`${listed.bot} has no roles for temporary sessions: its bot.yaml has no temp_roles.`]
+      : listed.roles.flatMap((role) => [
+        `role       ${role.name}${role.cap === undefined ? '' : `, cap ${role.cap}`}, open: ${role.open.length === 0 ? 'none' : role.open.join(', ')}${role.prompt_file === undefined ? '' : `, prompt file ${role.prompt_file}`}`,
+        ...role.options.map((option) => `  ${option.default ? 'default' : 'option '}  ${role.name}:${option.name}${option.for === undefined ? '' : `, for ${option.for}`}: ${['harness', 'model', 'effort', 'context'].filter((key) => option[key] !== undefined).map((key) => `${key} ${option[key]}`).join(', ') || 'all as you have them'}`),
+        ...(role.trouble ?? []).map((says) => `  trouble  ${says}`),
+      ]);
+    return { answer: { bots, ...listed }, lines };
+  },
+
   async 'temp retire'(bots, values) {
     const tab = callerTab(bots, true);
     refuseWhenOrcaIsDown();
@@ -1070,6 +1151,28 @@ const commands = {
       ],
     };
   },
+
+  async 'session clear'(bots, values) {
+    refuseWhenOrcaIsDown();
+    const cleared = await clearSession(bots, { bot: values.bot, session: values.session });
+    const after = cleared.was === null ? '' : `, in place of ${cleared.was}`;
+    return {
+      answer: { bots, cleared },
+      lines: [`cleared    ${cleared.bot} ${cleared.session}: the book holds its new conversation ${cleared.now}${after}.`],
+    };
+  },
+
+  async 'session compact'(bots, values) {
+    refuseWhenOrcaIsDown();
+    const compacted = await compactSession(bots, { bot: values.bot, session: values.session });
+    const what = `${compacted.bot} ${compacted.session}`;
+    return {
+      answer: { bots, compacted },
+      lines: [compacted.confirmed
+        ? `compacted  ${what}: the harness's record of its conversation ${compacted.conversation} shows the compaction.`
+        : `asked      ${what} to compact: /compact went in, and after 5 minutes the harness's record shows no compaction, so it is not confirmed yet. Look at its tab.`],
+    };
+  },
 };
 
 /**
@@ -1107,6 +1210,9 @@ function nudgeLine(answer, where) {
   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.`;
   }
+  if (answer.nudgeLeft) {
+    return `             it is queued, and its tab could not be told to look from here: ${answer.nudgeTrouble}. So the nudge is left for this session's hook, which looks at the tab from outside Codex's sandbox when this command is done, and says what it did.`;
+  }
   if (answer.nudgeTrouble !== undefined) {
     return `             it is queued, and its tab could not be told to look: ${answer.nudgeTrouble}`;
   }

package/src/health.js

@@ -22,7 +22,7 @@ import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
 import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
-import { botDir, botNames, botsDir, readBot, unknownKeys } from './bot.js';
+import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
 import { bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
@@ -190,6 +190,7 @@ function aboutBot(bots, name, setups, sessions) {
   return [
     ...unknownKeys(home, name).map(said('config')),
     ...sessionSettings(home, bot).map(said('config')),
+    ...rolesTrouble(home, bot).map(said('config')),
     ...agentsTrouble(bots, home, bot).map(said('config')),
     ...hooksOf(bots, home, bot).map(said('config')),
     ...permissionsTrouble(home, bot).map(said('config')),
@@ -209,6 +210,16 @@ function sessionSettings(home, bot) {
   });
 }
 
+/** What is wrong with the roles the bot's temporary sessions are made in (#465). */
+function rolesTrouble(home, bot) {
+  const where = path.join(home, 'bot.yaml');
+  try {
+    return tempRoles(home, bot).flatMap((role) => role.trouble.map((says) => ({ where, says })));
+  } catch (error) {
+    return [{ where, says: error.message }];
+  }
+}
+
 /** The kit's own hook, in the file of every harness this bot's sessions run on. */
 const hooksOf = (bots, home, bot) => [...new Set(bot.sessions.map((session) => harnessOf(session, bot.harness)))]
   .filter((harness) => HARNESSES.includes(harness))
@@ -311,13 +322,10 @@ function runningOn(bots, home, bot, book, handles, sessions) {
 
     if (rules.state === 'older') {
       const agents = path.join(home, 'AGENTS.md');
-      // A clear on Claude Code reads the instructions again, as a start does
-      // (tech notes, section 2); whether a new conversation on Codex does is
-      // not established, so a start is all that is offered there.
-      const how = harness === 'claude'
-        ? `A Claude Code session reads it again at a /clear in its tab, or when it starts: ${restart}`
-        : `A Codex session reads it when it starts: ${restart}`;
-      found.push(finding('session', agents, `${bot.name}'s session ${session.name} is running on older rules: ${agents} has changed since the kit noted which version this session read. ${how}`, bot.name));
+      // A clear reads the instructions again, as a start does, on both
+      // harnesses (tech notes, sections 2 and 3; #391).
+      const clear = `${shellWord(ownCli())} session clear --bots ${shellWord(bots)} --bot ${bot.name} --session ${session.name}`;
+      found.push(finding('session', agents, `${bot.name}'s session ${session.name} is running on older rules: ${agents} has changed since the kit noted which version this session read. A session reads it again when it is cleared: ${clear}, or when it starts: ${restart}`, bot.name));
     }
   }
   return found;

package/src/hooks.js

@@ -54,6 +54,21 @@ 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`;
 
+/**
+ * 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
+ * (#350, ADR 0034). Codex only, since only Codex runs its commands where `ps`
+ * does not start. It types into another session's tab, which takes Orca a few
+ * seconds a nudge, so it is given longer than the others.
+ */
+const NUDGE_EVENT = 'PostToolUse';
+const NUDGE_MATCHER = 'Bash';
+const NUDGE_TIMEOUT = 30;
+
+/** What the nudge hook runs, by the kit's own path, as `hookCommand` does. */
+export const nudgeCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session nudge --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+
 /**
  * Make sure the bot at `home` has the kit's SessionStart hook for `harness`.
  * Returns the file it wrote, relative to the bot home, or undefined when the
@@ -76,8 +91,7 @@ export function installHook(home, harness, { bots, bot }) {
   // longer asks about is taken out, and a hook of the user's beside the kit's
   // stays where they put it.
   const started = withKitHook(settings.hooks, file, mine);
-  const sentHook = { type: 'command', command: sentCommand(bots, bot), timeout: TIMEOUT };
-  const wanted = { ...settings, hooks: harness === 'claude' ? withSentHook(started, sentHook) : started };
+  const wanted = { ...settings, hooks: withToolHook(started, toolHookOf(harness, bots, bot)) };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -124,24 +138,25 @@ export function hookTrouble(home, harness, { bots, bot }) {
     }
     const program = running ?? ownCli();
     wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
-    // The send hook is judged on its own: the session hook may be right while
-    // the warning after a native message is missing (ADR 0032).
-    if (harness === 'claude' && isDeepStrictEqual(settings, wanted)) {
-      const sentRunning = sentProgramIn(settings);
-      // A send hook that runs a kit no longer there is as quiet as a missing
-      // one: `|| true` hides it, and no warning is ever given (#451 review).
-      if (sentRunning !== undefined && sentRunning !== BARE && !existsSync(sentRunning)) {
+    // The harness's second hook is judged on its own: the session hook may be
+    // right while the warning after a native message (ADR 0032), or the nudge
+    // a Codex sender left (ADR 0034), is missing.
+    if (isDeepStrictEqual(settings, wanted)) {
+      const tool = toolHookOf(harness, bots, bot);
+      const toolRunning = programIn(settings, tool.pattern);
+      // One that runs a kit no longer there is as quiet as a missing one:
+      // `|| true` hides it (#451 review).
+      if (toolRunning !== undefined && toolRunning !== BARE && !existsSync(toolRunning)) {
         return {
           where: file,
-          says: `${file} holds the kit's PostToolUse hook for SendMessage, but it runs ${sentRunning}, which is not there any more, so a session is never warned when its native message goes outside this bots folder (ADR 0032). obk up puts back one that runs the kit you have.`,
+          says: `${file} holds the kit's ${tool.event} hook for ${tool.matcher}, but it runs ${toolRunning}, which is not there any more, so ${tool.missing}. obk up puts back one that runs the kit you have.`,
         };
       }
-      const sentProgram = sentRunning ?? program;
-      const withSent = { ...settings, hooks: withSentHook(settings.hooks, { type: 'command', command: sentCommand(bots, bot, sentProgram), timeout: TIMEOUT }) };
-      if (!isDeepStrictEqual(settings, withSent)) {
+      const withTool = { ...settings, hooks: withToolHook(settings.hooks, toolHookOf(harness, bots, bot, toolRunning ?? program)) };
+      if (!isDeepStrictEqual(settings, withTool)) {
         return {
           where: file,
-          says: `${file} does not hold the kit's PostToolUse hook for SendMessage, which warns a session when its native message went outside this bots folder (ADR 0032). obk up puts it back.`,
+          says: `${file} does not hold the kit's ${tool.event} hook for ${tool.matcher}, without which ${tool.missing}. obk up puts it back.`,
         };
       }
     }
@@ -216,21 +231,46 @@ function withKitHook(hooks, file, mine) {
 }
 
 /**
- * The hooks with the kit's send hook in a `PostToolUse` group matched to
- * `SendMessage`, and everything else as the user left it, as `withKitHook`
- * keeps the session hook: one entry of the kit's, written in place where it
- * already sits in such a group, taken out of anywhere else, and added in a
- * group of its own when there is none. A group the kit empties goes.
+ * Each harness's second kit hook, after one of its tools: Claude Code's after a
+ * native `SendMessage` (ADR 0032), Codex's after its shell tool (ADR 0034).
+ * The entry, where it goes, how the kit knows its own, and what is lost
+ * without it.
  */
-function withSentHook(hooks, mine) {
+function toolHookOf(harness, bots, bot, cli = ownCli()) {
+  if (harness === 'claude') {
+    return {
+      event: SENT_EVENT,
+      matcher: SENT_MATCHER,
+      pattern: KIT_SENT,
+      mine: { type: 'command', command: sentCommand(bots, bot, cli), timeout: TIMEOUT },
+      missing: 'a session is never warned when its native message goes outside this bots folder (ADR 0032)',
+    };
+  }
+  return {
+    event: NUDGE_EVENT,
+    matcher: NUDGE_MATCHER,
+    pattern: KIT_NUDGE,
+    mine: { type: 'command', command: nudgeCommand(bots, bot, cli), timeout: NUDGE_TIMEOUT },
+    missing: "mail a session sends from inside Codex's sandbox never tells a receiver the kit could not see from there, such as a Claude session busy with a command (ADR 0034)",
+  };
+}
+
+/**
+ * The hooks with the kit's tool hook in a group of its event matched to its
+ * tool, and everything else as the user left it, as `withKitHook` keeps the
+ * session hook: one entry of the kit's, written in place where it already sits
+ * in such a group, taken out of anywhere else, and added in a group of its own
+ * when there is none. A group the kit empties goes.
+ */
+function withToolHook(hooks, { event: wantedEvent, matcher, pattern, mine }) {
   let placed = false;
   const events = Object.fromEntries(Object.entries(hooks).flatMap(([event, groups]) => {
     if (!Array.isArray(groups)) return [[event, groups]];
     const kept = groups.flatMap((group) => {
       if (!Array.isArray(group?.hooks)) return [group];
       const entries = group.hooks.flatMap((hook) => {
-        if (!isSentHook(hook)) return [hook];
-        if (event !== SENT_EVENT || group.matcher !== SENT_MATCHER || placed) return [];
+        if (programOf(hook?.command, pattern) === undefined) return [hook];
+        if (event !== wantedEvent || group.matcher !== matcher || placed) return [];
         placed = true;
         return [mine];
       });
@@ -239,27 +279,24 @@ function withSentHook(hooks, mine) {
     return kept.length === 0 ? [] : [[event, kept]];
   }));
   if (placed) return events;
-  return { ...events, [SENT_EVENT]: [...(events[SENT_EVENT] ?? []), { matcher: SENT_MATCHER, hooks: [mine] }] };
+  return { ...events, [wantedEvent]: [...(events[wantedEvent] ?? []), { matcher, hooks: [mine] }] };
 }
 
-
-/** Whether a hook entry is the kit's send hook, run by a kit, for any bots folder and bot. */
-const isSentHook = (hook) => sentProgramOf(hook?.command) !== undefined;
-
-function sentProgramOf(command) {
-  const found = typeof command === 'string' ? KIT_SENT.exec(command) : null;
+/** The program a command of the kit's of this pattern runs, unquoted, or undefined for any other command. */
+function programOf(command, pattern) {
+  const found = typeof command === 'string' ? pattern.exec(command) : null;
   if (found === null) return undefined;
   const program = unquoted(found[1]);
   return isKitCli(program) ? program : undefined;
 }
 
-/** What the kit's send hook in these settings runs, or undefined when there is none. */
-function sentProgramIn(settings) {
+/** What the kit's hook of this pattern in these settings runs, or undefined when there is none. */
+function programIn(settings, pattern) {
   for (const groups of Object.values(settings.hooks ?? {})) {
     if (!Array.isArray(groups)) continue;
     for (const group of groups) {
       for (const hook of Array.isArray(group?.hooks) ? group.hooks : []) {
-        const program = sentProgramOf(hook?.command);
+        const program = programOf(hook?.command, pattern);
         if (program !== undefined) return program;
       }
     }
@@ -282,6 +319,7 @@ const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
 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$`);
 
 /** The program a bot made before the kit named itself by path runs. */
 const BARE = 'obk';

package/src/lines.js

@@ -25,18 +25,21 @@ const LONGEST = 64 * 1024 * 1024;
 /**
  * Each line of `file`, in order, to `onLine`: its text, or `undefined` for a
  * line too long to hold. A line `onLine` answers `true` to is the last one
- * read. Throws what the file system throws when the file cannot be opened or
- * read.
+ * read. With `from`, reading starts at that byte, for a caller that wants only
+ * what was written after it (#391). Throws what the file system throws when
+ * the file cannot be opened or read.
  */
-export function eachLine(file, onLine) {
+export function eachLine(file, onLine, { from = 0 } = {}) {
   const fd = openSync(file, 'r');
   try {
     const decoder = new StringDecoder('utf8');
     const buffer = Buffer.allocUnsafe(CHUNK);
     let pending = '';
     let tooLong = false;
+    let position = from;
     for (;;) {
-      const read = readSync(fd, buffer, 0, CHUNK, null);
+      const read = readSync(fd, buffer, 0, CHUNK, position);
+      position += read;
       const text = read === 0 ? decoder.end() : decoder.write(buffer.subarray(0, read));
       let start = 0;
       for (let at = text.indexOf('\n'); at !== -1; at = text.indexOf('\n', start)) {

package/src/message.js

@@ -15,7 +15,8 @@
 // one line into the receiver's tab. Both harnesses queue a typed line while
 // they are busy, which is what PRD 6.9 means by queued and not interrupting.
 
-import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import { MAILBOX_WAIT_MS, readBook, takeMailboxTurn } from './book.js';
@@ -172,7 +173,7 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
     id: message.id,
     thread: message.thread_id ?? thread,
     file: written.file,
-    ...nudge(to, from, subject),
+    ...nudge(to, from, subject, tab),
   };
 }
 
@@ -452,14 +453,14 @@ const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '
  * it is nobody sending to a session before its first screens are answered,
  * which is the caller's work either way.
  */
-function nudge(to, from, subject) {
+function nudge(to, from, subject, tab) {
   if (to.tab === undefined) return { nudged: false };
 
   try {
     const found = lookAt(to);
     if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
     // A line that lands in a shell is run there, with the sender's subject in it.
-    if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure };
+    if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure, ...(found.psUnread ? leftForHook(to, from, subject, tab) : {}) };
     if (found.handle === undefined) return { nudged: false };
 
     const sent = typeIntoTab(
@@ -485,6 +486,82 @@ function nudge(to, from, subject) {
   }
 }
 
+/**
+ * The nudge a Codex sender could not decide, left for its own hook (#350, ADR
+ * 0034): `{ nudgeLeft: true }`, or nothing when it is not left.
+ *
+ * Inside Codex's sandbox `ps` does not start, and for a Claude receiver busy
+ * with a command Orca's runtime cannot see past it either. Codex runs its
+ * hooks outside the sandbox, and the kit's `PostToolUse` hook runs right after
+ * the command that made this send, in the same tab, where `ps` runs. So the
+ * send leaves the nudge where that hook looks, the system temp folder under the
+ * tab's id, which the sandbox lets it write and the hook reads. Only for a
+ * Codex session sending from its own tab, and only where `ps` could not read
+ * the receiver's tab: anywhere else no hook would see it, or would see no more
+ * than the send did.
+ */
+function leftForHook(to, from, subject, tab) {
+  if (tab === undefined || from.tab !== tab || from.harness !== 'codex') return {};
+  try {
+    const dir = leftDir(tab);
+    mkdirSync(dir, { recursive: true });
+    const left = { bots: to.bots, to: `${to.bot}/${to.session}`, from: `${from.bot}/${from.session}`, subject };
+    // Written under a name the hook does not take, then put in place whole: a
+    // hook running beside this send never takes a file still being written.
+    const name = path.join(dir, `${stamp()}.${process.pid}`);
+    writeFileSync(`${name}.writing`, `${JSON.stringify(left)}\n`);
+    renameSync(`${name}.writing`, `${name}.json`);
+    return { nudgeLeft: true };
+  } catch {
+    return {};
+  }
+}
+
+/** Where the nudges left from one tab wait for its hook. */
+const leftDir = (tab) => path.join(os.tmpdir(), 'obk-nudges', encodeURIComponent(tab));
+
+/**
+ * What the kit's Codex hook does after each shell command (#350): decide every
+ * nudge a send in this tab left, oldest first, with the gate the send uses, and
+ * type it or not. Each is taken out before it is looked at, so it is decided
+ * once, by one hook. Returns `{ to, subject, ...what the nudge came to }` for
+ * each, as the send's own answer says it.
+ */
+export function decideLeftNudges(tab) {
+  if (tab === undefined) return [];
+  const dir = leftDir(tab);
+  let names;
+  try {
+    names = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
+  } catch {
+    return [];
+  }
+  return names.flatMap((name) => {
+    const taking = path.join(dir, `${name}.taking`);
+    // Another hook took it first: it is that hook's to decide, and to remove.
+    try {
+      renameSync(path.join(dir, name), taking);
+    } catch {
+      return [];
+    }
+    let left;
+    try {
+      left = JSON.parse(readFileSync(taking, 'utf8'));
+    } catch {
+      return [];
+    } finally {
+      rmSync(taking, { force: true });
+    }
+    try {
+      const to = findSession(left.bots, left.to);
+      const from = findSession(left.bots, left.from);
+      return [{ to: left.to, subject: left.subject, ...nudge(to, from, left.subject) }];
+    } catch (error) {
+      return [{ to: left.to, subject: left.subject, nudged: false, nudgeTrouble: error.message }];
+    }
+  });
+}
+
 /** Orca's words about a line it did not see start a turn, or what its receipt says when it gives none. */
 function unseen(sent) {
   const warnings = Array.isArray(sent?.warnings) ? sent.warnings.filter((warning) => typeof warning === 'string') : [];

package/src/orca-reload.applescript

@@ -1,5 +1,5 @@
 -- Run by the kit as `osascript orca-reload.applescript <Orca.app path>`, after
--- a project was removed (#343, ADR 0031).
+-- a project was removed (#343, ADR 0034).
 --
 -- Orca's window keeps a removed project in its sidebar until the window is
 -- rebuilt (stablyai/orca#23224; once a release fixes it, this can go behind a

package/src/orca-runtime.cjs

@@ -2,7 +2,7 @@
 // CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-runtime.cjs <client> <method> <params> <wait>`.
 //
 // It makes one call to Orca's runtime, through Orca's own client, for a method
-// Orca's CLI does not offer (ADR 0031): `project.update`, which makes Orca's
+// Orca's CLI does not offer (ADR 0034): `project.update`, which makes Orca's
 // window read its projects again (#224), and `terminal.inspectProcess`, which
 // says who is in front of a tab where `ps` cannot (#298). `params` is JSON. It
 // prints the runtime's answer as JSON and exits 0 only when the runtime took