@assuredloop/orca-bot-kit 0.20.0 → 0.22.0

package/README.md

@@ -344,6 +344,20 @@ settings ([ADR 0022](docs/adr/0022-kit-hooks-live-in-the-bot-folder.md)). Your o
 settings in those files are kept. Codex asks you to trust a hooks file the first
 time it sees one; answer its question in the tab.
 
+A Claude bot gets one more hook there. Claude Code's own messaging reaches every
+Claude session on the machine, so after a session sends a native message to an
+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)).
+
+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
+hook, which Codex runs outside its sandbox right after the command, decides it and
+types it, or says why not ([ADR 0034](docs/adr/0034-orca-is-the-host.md)). Codex
+asks you to trust a hook it has not seen before, so a Codex bot made before this
+hook asks again once.
+
 So: kill a tab, or reboot, and `obk up` brings the session back with the
 conversation it was having, rather than starting a new one. Clear a session —
 `/clear` on Claude Code, `/new` on Codex — and the kit writes down the new id,

package/package.json

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

package/rules/temporary.md

@@ -4,18 +4,17 @@ title: Temporary sessions of your own
 applies: all
 ---
 
-For a piece of work that wants a helper, a long-lived session may make a
-temporary session of its own bot, without asking Bot Father:
+For a piece of work that wants a helper, a session may make a temporary
+session of its own bot, without asking Bot Father:
 `"${OBK_CLI:-obk}" temp make --bots <bots> --name <name> --prompt <the task>`,
 run in your own tab. It takes your settings unless you say otherwise, and gets
-a work dir, a tab and a mailbox.
+a work dir, a tab and a mailbox. A temporary session may make one of its own,
+one at a time; one made by a temporary session makes none.
 
 A new tab can stop on a first-run screen. Answer it yourself, from the table
 the command's output points to.
 
-Retire it when its work is done:
+Retire it when its work is done, and what it made goes with it:
 `"${OBK_CLI:-obk}" temp retire --bots <bots> --name <name>`. Before you make
-another, first retire any of yours whose work is done.
-
-You manage only the temporary sessions you made; a temporary session makes
-none of its own. Every other session is Bot Father's to make, change or retire.
+another, first retire any of yours whose work is done. You manage only the
+temporary sessions you made; every other session is Bot Father's.

package/src/book.js

@@ -32,7 +32,8 @@ const HEADER = `# What Orca calls this bot on this machine, and where each of it
 # the bot, with when, so the conversations it had are still accounted for.
 #
 # \`temporary\` marks a session another session of this bot made with
-# \`obk temp make\`: which session made it, and when. Its maker retires it.
+# \`obk temp make\`: which session made it, and when, and the role and option
+# of bot.yaml's temp_roles it was made in, if any. Its maker retires it.
 `;
 
 export const bookFile = (home) => path.join(home, 'sessions.yaml');

package/src/bot.js

@@ -159,6 +159,8 @@ export function readBot(home, name = path.basename(home)) {
     // The permission rules the user said yes to, judged where they are written
     // (src/permissions.js), as `rules` is judged by the build.
     allow: bot.allow,
+    // The roles its temporary sessions can be made in, judged by tempRoles.
+    ...(bot.temp_roles === undefined ? {} : { temp_roles: bot.temp_roles }),
     // A paused bot is one `obk up` leaves closed; its sessions keep their book.
     ...(bot.paused === true ? { paused: true } : {}),
     sessions: sessions.map((session) => {
@@ -495,7 +497,7 @@ export const SESSION_FIELDS = [
 ];
 
 /** Everything the top of a bot's own file can hold. */
-const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'allow', 'sessions', 'paused'];
+const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'allow', 'sessions', 'paused', 'temp_roles'];
 
 /**
  * The keys in a bot's file that the kit does not know, and so that nothing
@@ -519,6 +521,81 @@ export function unknownKeys(home, name = path.basename(home)) {
   ];
 }
 
+/** What a role's option can set, and what a role written as a mapping can hold (#465). */
+const OPTION_FIELDS = ['name', 'for', 'harness', 'model', 'effort', 'context'];
+const ROLE_FIELDS = ['options', 'cap', 'prompt_file'];
+
+/**
+ * The roles a bot's temporary sessions can be made in, from `temp_roles` in its
+ * file (#465), each read into one form: `{ name, options, cap, prompt_file,
+ * trouble }`. A role is written as a list of options, the first its default,
+ * or as a mapping that holds that list as `options` beside a `cap` and a
+ * `prompt_file`. `trouble` is each thing wrong with the role, as a sentence;
+ * a role with any is not one to make a session in. A `temp_roles` that is not
+ * a mapping at all is thrown. The file is the user's, so nothing here is put
+ * right: `obk health` says it, and `obk temp make` refuses the role.
+ */
+export function tempRoles(home, bot) {
+  const file = path.join(home, BOT_YAML);
+  const given = bot.temp_roles;
+  if (given === undefined || given === null) return [];
+  if (typeof given !== 'object' || Array.isArray(given)) {
+    throw new Error(`${file} has a temp_roles that is not a mapping of role names to roles, so the bot has no roles to make a temporary session in.`);
+  }
+  return Object.entries(given).map(([name, written]) => readRole(home, file, name, written));
+}
+
+function readRole(home, file, name, written) {
+  const trouble = [];
+  const say = (what) => trouble.push(`${file}: the temporary-session role ${name} ${what}`);
+  const role = Array.isArray(written) ? { options: written } : written;
+  if (!NAME.test(name)) say('cannot be a role\'s name: a name is lower-case letters, digits and single hyphens, and it begins the name of each session made in it.');
+  if (role === null || typeof role !== 'object') {
+    say('is neither a list of options nor a mapping with options in it.');
+    return { name, options: [], trouble };
+  }
+  for (const key of Object.keys(role).filter((one) => !ROLE_FIELDS.includes(one))) {
+    say(`has a key the kit does not know, ${key}, so nothing reads it. A role written as a mapping can have ${ROLE_FIELDS.join(', ')}.`);
+  }
+  const options = Array.isArray(role.options) ? role.options : [];
+  if (options.length === 0) say('has no options. Give it a list of them, the first being its default.');
+  const seen = new Set();
+  options.forEach((option, at) => {
+    if (option === null || typeof option !== 'object' || Array.isArray(option) || option.name === undefined || option.name === null || option.name === '') {
+      say(`has an option with no name, number ${at + 1} of its options.`);
+      return;
+    }
+    const called = `${name}:${option.name}`;
+    if (typeof option.name !== 'string' || !NAME.test(option.name)) say(`has an option ${option.name} whose name is not a word of lower-case letters, digits and single hyphens, so ${called} cannot be asked for. Write the name in quotes if YAML reads it as something else.`);
+    if (seen.has(option.name)) say(`has two options called ${option.name}, and ${called} would name either.`);
+    seen.add(option.name);
+    for (const key of Object.keys(option).filter((one) => !OPTION_FIELDS.includes(one))) {
+      say(`has an option ${option.name} with a setting the kit does not know, ${key}, so nothing reads it and a session made in ${called} would not get it. An option can set ${OPTION_FIELDS.join(', ')}.`);
+    }
+    if (option.harness !== undefined && option.harness !== null && !HARNESSES.includes(option.harness)) {
+      say(`has an option ${option.name} that runs on ${option.harness}, and the harnesses are ${HARNESSES.join(' and ')}.`);
+    }
+  });
+  if (role.cap !== undefined && !(Number.isInteger(role.cap) && role.cap > 0)) {
+    say(`has a cap of ${JSON.stringify(role.cap)}, and a cap is a whole number of open sessions, 1 or more.`);
+  }
+  if (role.prompt_file !== undefined) {
+    const prompt = path.resolve(home, String(role.prompt_file));
+    try {
+      readFileSync(prompt, 'utf8');
+    } catch (error) {
+      say(`has its prompt in ${role.prompt_file}, and that file cannot be read (${error.code}): ${prompt}. Write it, or point the role at the file you meant.`);
+    }
+  }
+  return {
+    name,
+    options,
+    ...(role.cap === undefined ? {} : { cap: role.cap }),
+    ...(role.prompt_file === undefined ? {} : { prompt_file: role.prompt_file }),
+    trouble,
+  };
+}
+
 /** A session's settings, in that order, without the ones left out. */
 function ordered(session) {
   const entry = {};

package/src/cli.js

@@ -17,18 +17,19 @@ 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 { 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';
 
@@ -90,28 +91,47 @@ Usage:
                             session with the conversation it was having.
   obk retire --bots <path> --bot <bot> [--session <name>]
                             End a session: close its tab and take it off the
-                            bot, keeping its conversations in the book. Or end
-                            a bot: close its tabs, remove its Orca project and
-                            move its folder to retired/. It will not retire a
-                            bot whose Orca 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>
+                            bot, keeping its conversations in the book, and
+                            first do the same for the temporary sessions it
+                            made, and theirs. Or end a bot: close its tabs,
+                            remove its Orca project and move its folder to
+                            retired/. It will not retire a bot whose Orca
+                            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> [--role <role>[:<option>]]
                 (--prompt <text> | --prompt-file <path>) [--harness claude|codex]
                 [--model <m>] [--effort <e>] [--context <c>]
                 [--approval ${APPROVALS.join('|')}] [--extra-arg=<arg>]...
-                            Run in a long-lived session's own tab: make a
-                            temporary session of that session's bot for a piece
-                            of work, and bring it up. It takes your harness,
-                            model, effort, context and approval unless you say
-                            otherwise; on another harness than yours it takes
-                            only your approval. It works in work/<session>, and
-                            has the task as its start prompt. The book records
-                            it as temporary, made by you.
+                            Run in a session's own tab: make a temporary
+                            session of that session's bot for a piece of work,
+                            and bring it up. A temporary session makes one at
+                            a time, and one it made makes none. It takes your
+                            harness, model, effort, context and approval unless
+                            you say otherwise; on another harness than yours
+                            it takes only your approval. It works in
+                            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
                             long-lived session, or one another session made.
+                            Like obk retire, it first retires the temporary
+                            sessions that session made.
   obk temp trust-hooks --bots <path> --name <session>
                             Run in the maker's own tab: answer the hooks review
                             of a Codex temporary session it made with "Trust
@@ -230,6 +250,17 @@ Usage:
                             For the kit's own hook, not for typing: it reads
                             what the harness says about a session starting on
                             standard input and writes it into the book.
+  obk session sent --bots <path> --bot <bot>
+                            For the kit's own hook, not for typing: after a
+                            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
@@ -269,8 +300,11 @@ const COMMANDS = {
   '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'],
 };
@@ -293,6 +327,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. */
@@ -347,6 +382,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' },
@@ -394,6 +430,11 @@ async function run(argv) {
     throw new Error(`--harness is ${HARNESSES.join(' or ')}, and got: ${values.harness}`);
   }
 
+  // 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));
   if (command === RECORD) return record(bots, values.bot);
@@ -457,8 +498,48 @@ const ANSWER_IT = [
   '             Anything you do not recognise gets no keypress: take it to the user.',
 ];
 
-/** The one command a harness runs rather than a person: the kit's hook. */
+/** 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
+ * reads, as Claude Code's `additionalContext`, or nothing. Never a decision,
+ * and never anything but exit 0 (ADR 0032).
+ */
+function sent(bots) {
+  try {
+    const warning = sentWarning(bots, JSON.parse(readFileSync(0, 'utf8')));
+    if (warning !== undefined) {
+      process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: warning } })}\n`);
+    }
+  } catch {
+    // Nothing: a hook does not disturb the session it runs in.
+  }
+  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.
@@ -571,6 +652,7 @@ const commands = {
       return {
         answer: { bots, ...retired },
         lines: [
+          ...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`,
           ...leftLines(retired.promptsLeft),
@@ -611,21 +693,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();
@@ -633,6 +735,7 @@ const commands = {
     return {
       answer: { bots, ...retired },
       lines: [
+        ...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`,
         ...leftLines(retired.promptsLeft),
@@ -1070,6 +1173,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}`;
   }
@@ -1106,6 +1212,13 @@ function settingsOf(values) {
 /** The tabs a command closed, one line each. */
 const closedLines = (closed) => closed.map((tab) => `closed     ${tab.bot} ${tab.name}  tab ${tab.tabId}  terminal ${tab.terminal}`);
 
+/** The temporary sessions a retire took along with the one it named, each as it went (#464). */
+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`,
+  ...leftLines(gone.promptsLeft),
+]);
+
 /** 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/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))

package/src/hooks.js

@@ -42,6 +42,33 @@ const TIMEOUT = 10;
 export const hookCommand = (bots, bot, cli = ownCli()) =>
   `${shellWord(cli)} session record --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
+/**
+ * Claude Code's second kit hook: after a native `SendMessage`, a warning when
+ * it went outside the bots folder (ADR 0032). Claude Code only, since Codex has
+ * no native messaging.
+ */
+const SENT_EVENT = 'PostToolUse';
+const SENT_MATCHER = 'SendMessage';
+
+/** What the send hook runs, by the kit's own path, as `hookCommand` does. */
+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
@@ -63,7 +90,8 @@ export function installHook(home, harness, { bots, bot }) {
   // path is corrected rather than doubled, an entry under an event the kit no
   // longer asks about is taken out, and a hook of the user's beside the kit's
   // stays where they put it.
-  const wanted = { ...settings, hooks: withKitHook(settings.hooks, file, mine) };
+  const started = withKitHook(settings.hooks, file, mine);
+  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.
@@ -110,6 +138,28 @@ 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 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 ${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 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 ${tool.event} hook for ${tool.matcher}, without which ${tool.missing}. obk up puts it back.`,
+        };
+      }
+    }
   } catch (error) {
     return { where: file, says: `${error.message} ${stale}` };
   }
@@ -180,6 +230,80 @@ function withKitHook(hooks, file, mine) {
   return { ...events, [EVENT]: [...(events[EVENT] ?? []), { hooks: [mine] }] };
 }
 
+/**
+ * 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 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 (programOf(hook?.command, pattern) === undefined) return [hook];
+        if (event !== wantedEvent || group.matcher !== matcher || placed) return [];
+        placed = true;
+        return [mine];
+      });
+      return entries.length === 0 ? [] : [{ ...group, hooks: entries }];
+    });
+    return kept.length === 0 ? [] : [[event, kept]];
+  }));
+  if (placed) return events;
+  return { ...events, [wantedEvent]: [...(events[wantedEvent] ?? []), { matcher, hooks: [mine] }] };
+}
+
+/** 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 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 = programOf(hook?.command, pattern);
+        if (program !== undefined) return program;
+      }
+    }
+  }
+  return undefined;
+}
+
 /**
  * The kit's own hook entry, wherever it sits and whatever sits beside it: a
  * command of exactly the shape `hookCommand` writes, for any bots folder and
@@ -194,6 +318,8 @@ const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
 /** One word as `shellWord` writes it: bare, or single-quoted with `'\''` inside. */
 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';