@assuredloop/orca-bot-kit 0.21.0 → 0.22.0

package/README.md

@@ -350,6 +350,14 @@ 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.21.0",
+  "version": "0.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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,7 +17,7 @@ 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';
@@ -29,7 +29,7 @@ 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 +99,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 +113,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
@@ -242,6 +255,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
@@ -282,8 +301,10 @@ const COMMANDS = {
   '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 +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. */
@@ -360,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' },
@@ -410,6 +433,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 +501,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 +520,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 +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();
@@ -1107,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}`;
   }

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

@@ -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/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

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0031). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0034). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -216,7 +216,7 @@ const CLIENT_KILL_MS = 3000;
  *
  * Orca's window re-reads only when its runtime says the projects changed, and
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
- * changes does, and Orca's CLI does not offer it (ADR 0031). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0034). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -227,7 +227,7 @@ export const tellWindow = (projectId) => askRuntime('project.update', { projectI
  * runtime's answer, or undefined when there is none to be had.
  *
  * It goes through Orca's own runtime client out of the installed app, run by
- * Orca's binary the way its `bin/orca` runs its CLI (ADR 0031). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0034). None of that is
  * Orca's published interface, so anything that goes wrong is a quiet
  * undefined: it never throws and is never tried twice.
  */
@@ -264,7 +264,7 @@ const RELOAD_KILL_MS = 5000;
 
 /**
  * Have Orca's window force-reload itself, after a project was removed: true
- * only when it did (#343, ADR 0031).
+ * only when it did (#343, ADR 0034).
  *
  * The window keeps a removed project in its sidebar until it is rebuilt, and
  * `tellWindow` only relabels the row "Unknown" (stablyai/orca#23224; once a
@@ -418,7 +418,7 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Whether the rows of a rendered screen hold a question of the harness's own.
  *
  * Every one seen is a numbered list of choices with the harness's pointer on
- * one (tech notes, section 1; ADR 0031). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0034). The same pointer starts the harness's
  * input line and its echo of the user's past turns, and the input line is the
  * lowest of them whenever it is on screen, so only the lowest pointer row is
  * asked about: a question counts while it stands in the input line's place.
@@ -449,7 +449,8 @@ export function questionIn(rows) {
  * `{}` for a tab with no harness in it (none in the book, none Orca lists, or
  * the shell in front), `{ blocked }` for one with something on screen waiting
  * to be answered, and `{ unsure }`, a sentence, for one the kit cannot tell
- * about. Orca refusing throws, for the caller to report.
+ * about, with `psUnread` where `ps` could not read the tab (#350). Orca
+ * refusing throws, for the caller to report.
  *
  * The one gate for every line the kit types into a running session: the mail
  * nudge and the skills reload. A busy harness passes it, since both harnesses
@@ -497,7 +498,8 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
     const why = seen.front === undefined
       ? seen.unreadable
       : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
-    return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed` };
+    // Where `ps` could not read the tab, a reader that can may yet tell (#350).
+    return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed`, ...(seen.psUnread ? { psUnread: true } : {}) };
   }
   // Orca's reason does not cover every question: it called Codex's update
   // offer idle, and a return typed into it took "Update now" (#329). So the
@@ -554,13 +556,13 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  *
  * `ps` is asked first. Where it cannot read the tab, as inside Codex's
  * sandbox, where it does not start at all, Orca's runtime is asked instead
- * (#298, ADR 0031).
+ * (#298, ADR 0034).
  */
 function frontOf(handle, ptyId, readMs) {
   const read = frontByPs(ptyId, readMs);
   if (read.unreadable === undefined) return read;
   const asked = frontByOrca(handle);
-  return asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` };
+  return { ...(asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` }), psUnread: true };
 }
 
 /**
@@ -590,7 +592,7 @@ function frontByOrca(handle) {
  * Who holds the terminal of the pane `ptyId`, as `ps` says it.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0031).
+ * gives that pid's terminal's foreground process group (ADR 0034).
  * On macOS the pane is `login` with the shell as its child, so the shell is in
  * front when the group is the pane's own or that of a child of a `login` pane.
  * `diagnostics memory` is a diagnostics command and may change, so everything

package/src/temp.js

@@ -5,7 +5,9 @@
 // Any long-lived session can make a temporary session of its own bot for a
 // piece of work, and retire it when the work is done, without Bot Father, who
 // stays the manager of long-lived sessions. A temporary session can make one
-// of its own, one level deep and one at a time (#464, ADR 0033). A temporary session is an ordinary
+// of its own, one level deep and one at a time (#464, ADR 0033). It can be
+// made in a role of its bot's `temp_roles`, which gives its settings, and
+// whose cap limits how many are open (#465). A temporary session is an ordinary
 // session in every other way: in bot.yaml, brought up with a tab and a mailbox,
 // its conversations kept in the book. What makes it temporary is one field of
 // its book entry, `temporary: { maker, made }`, and the book is the one place
@@ -27,8 +29,8 @@ import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
 import { readBook, updateBook } from './book.js';
-import { addSession, dropSession, NAME, readBot } from './bot.js';
-import { harnessOf, isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
+import { addSession, dropSession, NAME, readBot, tempRoles } from './bot.js';
+import { DEFAULT_APPROVAL, harnessOf, isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
 import { sessionInTab } from './message.js';
 import { orca, screenRows, tabs } from './orca.js';
 import { retireSession } from './retire.js';
@@ -39,45 +41,43 @@ const INHERITED = ['model', 'effort', 'context', 'approval'];
 
 /**
  * Make a temporary session of the caller's own bot and bring it up. `given`
- * holds what the caller said: `name`, `prompt` or `prompt_file`, and any of
- * `harness` and the inherited settings. Returns `{ bot, session, maker,
- * settings, up }`, where `up` is what bringing it up answered.
+ * holds what the caller said: `name`, `prompt` or `prompt_file`, any of
+ * `harness` and the inherited settings, and `role`, as `role` or
+ * `role:option`, to take the settings that role's option gives in its bot's
+ * `temp_roles` (#465). Returns `{ bot, session, maker, settings, chosen,
+ * role, up }`: `chosen` says where each setting came from, `role` is there
+ * when one was asked for, and `up` is what bringing it up answered.
  */
 export async function makeTemp(bots, { tab, ...given }) {
   const caller = callerIn(bots, tab, 'make');
   // Checked here, before anything is written, and again under the book's lock
   // below, where two makes at once cannot both pass it.
   refuseNested(bots, caller, readBook(caller.home));
+  const bot = readBot(caller.home, caller.bot);
+  const role = given.role === undefined ? undefined : roleAsked(caller, bot, given.role);
+  const name = role === undefined ? given.name : roleName(caller, bot, role, given.name);
   // The name is a folder under work/ and a file beside the bots folder, so it
   // is held to the rule a bot's name is: one plain name, never a path.
-  if (!NAME.test(given.name)) {
-    throw new Error(`${given.name} cannot be a session's name: a name is lower-case letters, digits and single hyphens, such as review-250. Nothing was made.`);
-  }
-  if (given.prompt === undefined && given.prompt_file === undefined) {
-    throw new Error(`temp make needs the task: --prompt <text> or --prompt-file <path>. Nothing was made.`);
+  if (!NAME.test(name)) {
+    throw new Error(`${name} cannot be a session's name: a name is lower-case letters, digits and single hyphens, such as review-250. Nothing was made.`);
   }
   if (given.prompt !== undefined && given.prompt_file !== undefined) {
     throw new Error(`temp make was given the task twice, as --prompt and as --prompt-file, and a session is told its duty once. Give it one way. Nothing was made.`);
   }
+  if (given.prompt === undefined && given.prompt_file === undefined && role?.prompt_file === undefined) {
+    throw new Error(`temp make needs the task: --prompt <text> or --prompt-file <path>${role === undefined ? '' : `, since the role ${role.name} has no prompt file`}. Nothing was made.`);
+  }
+  if (role !== undefined) refuseCap(caller, role, readBook(caller.home));
 
-  const bot = readBot(caller.home, caller.bot);
   const maker = bot.sessions.find((session) => session.name === caller.session);
-  const settings = { name: given.name };
-  const harness = given.harness ?? maker?.harness;
-  if (harness !== undefined) settings.harness = harness;
-  // On another harness than its maker's, the model, the effort and the context
-  // are that harness's own, and only the approval carries over (#238, PRD 6.4).
-  const same = (harness ?? bot.harness) === harnessOf(maker ?? {}, bot.harness);
-  for (const field of INHERITED) {
-    const value = given[field] ?? (same || field === 'approval' ? maker?.[field] : undefined);
-    if (value !== undefined) settings[field] = value;
-  }
+  const { settings, chosen } = settingsFor(bot, maker, role?.option ?? {}, given);
+  settings.name = name;
   if (given.extra_args !== undefined) settings.extra_args = given.extra_args;
   if (given.prompt !== undefined) settings.prompt = given.prompt;
-  else settings.prompt_file = given.prompt_file;
-  settings.work_dir = `work/${given.name}`;
+  else settings.prompt_file = given.prompt_file ?? role.prompt_file;
+  settings.work_dir = `work/${name}`;
 
-  const written = bot.sessions.some((session) => session.name === given.name) ? undefined : writePromptFirst(bots, caller, settings);
+  const written = bot.sessions.some((session) => session.name === name) ? undefined : writePromptFirst(bots, caller, settings);
   // bot.yaml and the book are written under the book's lock, so that a second
   // make from the same maker waits, and then sees this one (#464). addSession
   // refuses a name the bot already has, and a setting that will not work,
@@ -89,21 +89,23 @@ export async function makeTemp(bots, { tab, ...given }) {
     await updateBook(caller.home, (book) => {
       locked = true;
       refuseNested(bots, caller, book);
+      if (role !== undefined) refuseCap(caller, role, book);
       added = addSession(bots, caller.bot, settings);
-      book.sessions[given.name] = { ...book.sessions[given.name], temporary: { maker: caller.session, made } };
+      const kind = role === undefined ? {} : { role: role.name, option: role.option.name };
+      book.sessions[name] = { ...book.sessions[name], temporary: { maker: caller.session, made, ...kind } };
     });
   } catch (error) {
     // A refusal under the lock has written nothing but the prompt file.
     const refused = locked && added === undefined;
-    const failed = `${caller.bot}/${given.name} could not be recorded in the book as temporary (${error.message})`;
+    const failed = `${caller.bot}/${name} could not be recorded in the book as temporary (${error.message})`;
     // A session in bot.yaml that the book does not call temporary would be a
     // long-lived one to everything that reads it, its maker's retire included,
     // so it is taken back off rather than left that way.
     if (added !== undefined) {
       try {
-        dropSession(bots, caller.bot, given.name);
+        dropSession(bots, caller.bot, name);
       } catch (undo) {
-        throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}`);
+        throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${name}`);
       }
     }
     // Off bot.yaml, nothing is made; a prompt file that stays is only a file,
@@ -120,12 +122,134 @@ export async function makeTemp(bots, { tab, ...given }) {
 
   let up;
   try {
-    up = await bringUp(bots, { bot: caller.bot, session: given.name });
+    up = await bringUp(bots, { bot: caller.bot, session: name });
   } catch (error) {
     const cli = shellWord(ownCli());
-    throw new Error(`${caller.bot}/${given.name} is made, in bot.yaml and in the book as temporary with its maker ${caller.session}, and could not be brought up: ${error.message} Bring it up with  ${cli} up --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}  or retire it with  ${cli} temp retire --bots ${shellWord(bots)} --name ${given.name}`);
+    throw new Error(`${caller.bot}/${name} is made, in bot.yaml and in the book as temporary with its maker ${caller.session}, and could not be brought up: ${error.message} Bring it up with  ${cli} up --bots ${shellWord(bots)} --bot ${caller.bot} --session ${name}  or retire it with  ${cli} temp retire --bots ${shellWord(bots)} --name ${name}`);
+  }
+  return { bot: caller.bot, session: name, maker: caller.session, settings: added.session, chosen, ...(role === undefined ? {} : { role: roleAnswer(role) }), up };
+}
+
+/**
+ * The settings a temporary session is made with, and for each of the ones
+ * that can be inherited, what it got and where from: `chosen` (#465). A flag
+ * wins; then the role's option, on the option's harness, which is the maker's
+ * when the option names none; then the maker, on the maker's harness; and
+ * otherwise the harness's own default. On another harness than its maker's,
+ * only the approval carries over (#238, PRD 6.4).
+ */
+function settingsFor(bot, maker, option, given) {
+  const makers = harnessOf(maker ?? {}, bot.harness);
+  const settings = {};
+  const chosen = {};
+  const pick = (field, ...sources) => {
+    // YAML reads a setting written with no value as null, which gives nothing.
+    const found = sources.find(([, value]) => value !== undefined && value !== null);
+    if (found === undefined) {
+      chosen[field] = { from: 'harness default' };
+      return;
+    }
+    chosen[field] = { value: found[1], from: found[0] };
+    if (found[0] !== 'maker' || field !== 'harness' || maker?.harness !== undefined) settings[field] = found[1];
+  };
+  pick('harness', ['flag', given.harness], ['role', option.harness], ['maker', makers]);
+  const harness = chosen.harness.value;
+  const fromRole = harness === (option.harness ?? makers);
+  const same = harness === makers;
+  for (const field of INHERITED) {
+    pick(
+      field,
+      ['flag', given[field]],
+      ['role', fromRole && field !== 'approval' ? option[field] : undefined],
+      ['maker', same || field === 'approval' ? maker?.[field] : undefined],
+      // A session's approval is never left to the harness (ADR 0015).
+      ['kit default', field === 'approval' ? DEFAULT_APPROVAL : undefined],
+    );
+  }
+  return { settings, chosen };
+}
+
+/**
+ * The role and option `asked` names, as `role` or `role:option`, from the
+ * bot's roles, with the option it takes; or a refusal that names what the bot
+ * has to choose from.
+ */
+function roleAsked(caller, bot, asked) {
+  const [name, optionName, ...more] = asked.split(':');
+  const roles = tempRoles(caller.home, bot);
+  if (roles.length === 0) {
+    throw new Error(`${caller.bot} has no roles for temporary sessions: its bot.yaml has no temp_roles. Make it without --role, or give the bot its roles first. Nothing was made.`);
   }
-  return { bot: caller.bot, session: given.name, maker: caller.session, settings: added.session, up };
+  const role = roles.find((one) => one.name === name);
+  if (role === undefined || more.length > 0) {
+    throw new Error(`${caller.bot} has no role ${asked}. Its roles are ${roles.map((one) => one.name).join(', ')}; ask for one as --role <role> or --role <role>:<option>. Nothing was made.`);
+  }
+  if (role.trouble.length > 0) {
+    throw new Error(`the role ${name} cannot be used as it is written: ${role.trouble.join(' ')} Nothing was made.`);
+  }
+  const option = optionName === undefined ? role.options[0] : role.options.find((one) => one.name === optionName);
+  if (option === undefined) {
+    throw new Error(`the role ${name} has no option ${optionName}. Its options are ${optionsLine(optionsOf(role))}. Nothing was made.`);
+  }
+  return { ...role, option };
+}
+
+/**
+ * The name of a session made in `role`: `--name` as given when it already
+ * begins with the role, or with the role put in front. A name that begins with
+ * another of the bot's roles would say the wrong one, and is refused.
+ */
+function roleName(caller, bot, role, given) {
+  if (given.startsWith(`${role.name}-`)) return given;
+  const other = tempRoles(caller.home, bot).find((one) => given.startsWith(`${one.name}-`));
+  if (other !== undefined) {
+    throw new Error(`${given} begins with ${other.name}-, the name of another of ${caller.bot}'s roles, and a session made in ${role.name} is named for ${role.name}. Give --name without it, such as --name ${given.slice(other.name.length + 1)}, to make ${role.name}-${given.slice(other.name.length + 1)}. Nothing was made.`);
+  }
+  return `${role.name}-${given}`;
+}
+
+/** Refuse a make in a role whose cap of open sessions is reached, against `book` (#465). */
+function refuseCap(caller, role, book) {
+  if (role.cap === undefined) return;
+  const open = Object.keys(book.sessions).filter((name) => book.sessions[name]?.temporary?.role === role.name);
+  if (open.length >= role.cap) {
+    throw new Error(`the role ${role.name} has a cap of ${role.cap} open temporary sessions, and ${caller.bot} has ${open.length} open: ${open.join(', ')}. Retire one whose work is done first. Nothing was made.`);
+  }
+}
+
+/** A role's options as an answer gives them: each one's name, what it is for, and whether it is the default. */
+const optionsOf = (role) => role.options.map((option, at) => ({ name: option.name, ...(option.for === undefined ? {} : { for: option.for }), default: at === 0 }));
+
+/** Options as `optionsOf` gives them, on one line. */
+export const optionsLine = (options) => options
+  .map((option) => `${option.name}${option.default ? ' (the default)' : ''}${option.for === undefined ? '' : `, for ${option.for}`}`)
+  .join('; ');
+
+/** A role as an answer gives it: the option used, and every option the role has. */
+const roleAnswer = (role) => ({
+  name: role.name,
+  option: role.option.name,
+  ...(role.option.for === undefined ? {} : { for: role.option.for }),
+  options: optionsOf(role),
+});
+
+/**
+ * The roles of the caller's bot, each with its cap, its open temporary
+ * sessions, its prompt file and its options, the first the default (#465).
+ * Returns `{ bot, roles }`.
+ */
+export function listRoles(bots, { tab }) {
+  const caller = callerIn(bots, tab, 'roles', 'list the roles');
+  const book = readBook(caller.home);
+  const roles = tempRoles(caller.home, readBot(caller.home, caller.bot)).map((role) => ({
+    name: role.name,
+    ...(role.cap === undefined ? {} : { cap: role.cap }),
+    open: Object.keys(book.sessions).filter((name) => book.sessions[name]?.temporary?.role === role.name),
+    ...(role.prompt_file === undefined ? {} : { prompt_file: role.prompt_file }),
+    options: role.options.map((option, at) => ({ ...option, default: at === 0 })),
+    ...(role.trouble.length === 0 ? {} : { trouble: role.trouble }),
+  }));
+  return { bot: caller.bot, roles };
 }
 
 /**