@assuredloop/orca-bot-kit 0.8.0 → 0.10.0

package/README.md

@@ -529,7 +529,8 @@ name. Everything else goes through Orca's mailbox, which the kit does carry.
 
 That includes a Claude session still running under a name from before the
 token, `<bot>.<session>`: `message to` answers the mailbox road for it, never
-that name, until the session next starts a new conversation.
+that name, until the kit's launch line next starts it (`obk restart`, or
+`obk up` after its tab is gone), which gives it a token name of its own.
 
 A session's mailbox is made the first time the kit starts it, and written in
 the book beside its tab. It is an Orca Run rather than the session's tab,
@@ -598,7 +599,9 @@ cannot be read as one that passed. `-- --yes` is how you say you meant it. When
 Orca is not answering, the command says which Orca it asked and skips, rather
 than report a kit that is not broken. Name files after it to run only those;
 each must be one of the `*.test.js` files under `test/system/`, links followed,
-and a name that is not is refused before anything runs.
+and a name that is not is refused before anything runs. This command is the
+only way in: a system test loaded any other way, with `node --test` or an
+editor's runner, skips and says how to run it.
 
 `npm run mutate` runs [StrykerJS](https://stryker-mutator.io) over the
 JavaScript this branch changed against `main` — committed, still in the working

package/SETUP.md

@@ -37,7 +37,7 @@ node --version                                          # 24.21.0 or newer
 git --version
 /Applications/Orca.app/Contents/Resources/bin/orca status --json
 claude --version                                        # at least one of these
-codex --version
+codex --version                                         # 0.156.1 or newer
 ```
 
 The Orca line must come back with `ok: true` and `result.runtime.reachable:
@@ -55,6 +55,10 @@ first release measured here that loads it without an experimental warning.
 If neither harness is installed, say so and stop. If only one is, that is fine,
 and it is the one Bot Father will run on.
 
+If Codex is older than 0.156.1, say so and ask them to update it before a bot
+runs on Codex. The kit starts Codex with `--no-daemon`, and older Codex refuses
+that flag.
+
 ## 2. Make `obk` runnable
 
 **First ask whether it already is:**
@@ -121,9 +125,14 @@ This makes the folder a git repository, seeds it, writes Bot Father, and opens
 its two tabs in Orca: the management tab where they will talk to it, and an ops
 tab, which is a plain shell for work across the whole fleet.
 
-Read everything it prints. Two parts of it matter to them:
+Read everything it prints. Three parts of it matter to them:
 
 - **what it created** — say it in a sentence, not as a file listing;
+- **the permission rules it says wait for their yes**, when Bot Father runs on
+  Claude Code: its mail through the kit, reading a long message beside the
+  bots folder, and its commits, so auto mode does not stop it for those. Show
+  them the rules word for word and ask. Only on a yes, run the one command
+  `init` printed for them; on a no, run nothing, and nothing is written;
 - **anything it says about Orca's own default launch arguments.** Orca adds
   these to every agent it launches, relaunches and resumes. When they carry a
   permission bypass, every session runs in that mode whatever approval level the
@@ -206,8 +215,9 @@ empty book and nothing says why.
 Codex's trust question applies to the **repository root**, which for a bot means
 the whole bots folder rather than the one bot. That is what they are agreeing to.
 
-Codex's `/new` question (0.156.1 on) is always answered with the current
-checkout, which is the bot home. The kit never makes a git worktree, so
+Codex's `/new` question (seen on 0.156.1; 0.157.1 did not show it in the runs
+seen so far) is always answered with the current checkout, which is the bot
+home. The kit never makes a git worktree, so
 `2. New worktree` is never the answer.
 
 **Anything you do not recognise: type nothing.** Tell them what is on the

package/package.json

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

package/rules/limits.md

@@ -16,3 +16,7 @@ publishing, releasing, spending money, anything another person receives.
 
 When something you were told to use is missing (a model, a tool, a file), say
 so and ask. Quietly using a different one hides the change.
+
+Permission rules in a harness's settings file are the kit's to write, after
+the user's yes to the exact rules: `obk bot change --allow <rule>` records and
+writes them. Never edit them into a settings file yourself, Bot Father included.

package/rules/mail.md

@@ -6,8 +6,7 @@ applies: all
 
 To reach another session, ask the kit for the road rather than guessing an
 address: `"${OBK_CLI:-obk}" message to --bots <bots> --to <bot>/<session>`. It
-answers with the address and the command that carries it. Your bots folder is
-two levels above the folder you start in.
+answers with the address and the command that carries it.
 
 Mail is queued, not an interruption. Read it when you finish what you are on.
 

package/skills/obk-bot-building/SKILL.md

@@ -201,6 +201,17 @@ say that you edited it by hand.
 Run `obk --help` for the flags of the version actually installed rather than
 trusting a line you remember.
 
+A bot on Claude Code needs a few permission rules so that auto mode does not
+stop it for what the kit's own rules tell it to do: its mail through the kit,
+reading a long message kept beside the bots folder, and its commits. `obk bot
+create`, `obk up` and `obk rules build` list the rules still waiting for a bot
+and give one command that allows them. Show the user those rules word for word
+and say in a line what each lets the bot do. Run the command only after their
+yes: it records the yes in the bot's `bot.yaml` and writes the rules into its
+settings. On a no, run nothing, and nothing is written. When the kit lists new
+rules for a bot later, ask again. Never write a permission rule into a settings
+file by hand.
+
 A bot that should learn across its sessions can use its harness's own memory,
 turned on for that bot alone, whatever the user's own setting is for everything
 else. The harness writes it, loads it and keeps it tidy itself. On Claude Code
@@ -260,9 +271,10 @@ table: a harness that has added an option has moved them. Codex's hooks
 question matters most. The kit's hook is how the book learns which
 conversation the session is running, and until it is answered the
 conversation has not started. Codex's trust applies to the repository root,
-which is the whole bots folder. Codex's `/new` asks where the new
-conversation runs; the answer is always the current checkout, the bot home,
-and never `2. New worktree`: the kit never makes a git worktree.
+which is the whole bots folder. Codex's `/new` may ask where the new
+conversation runs (0.156.1 did; 0.157.1 has not so far); the answer is
+always the current checkout, the bot home, and never `2. New worktree`:
+the kit never makes a git worktree.
 
 Where the kit says no session came up, the shell swallowed the launch line,
 usually while it was asking its own question. Answer the shell, then close

package/src/bot.js

@@ -136,6 +136,9 @@ export function readBot(home, name = path.basename(home)) {
     // and a list the build cannot follow is that build's to report (PRD 6.6).
     charter: bot.charter,
     rules: bot.rules,
+    // 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,
     // A paused bot is one `obk up` leaves closed; its sessions keep their book.
     ...(bot.paused === true ? { paused: true } : {}),
     sessions: sessions.map((session) => {
@@ -250,6 +253,42 @@ export function changeBot(bots, bot, { charter }) {
   return { bot, home: botDir(bots, bot), charter: text };
 }
 
+/**
+ * The bot's `allow` list as it is, after refusing what `allowRules` would refuse:
+ * an empty rule, or a list already there that is not a list of rules. Asked
+ * before anything is written, so a refused `bot change` changes nothing, its
+ * charter included.
+ */
+export function allowedNow(bots, bot, rules) {
+  if (rules.some((rule) => rule.trim() === '')) {
+    throw new Error('--allow is empty. Give it the exact permission rule the user said yes to, such as Bash(git add:*).');
+  }
+  const home = existingBot(bots, bot);
+  const was = readBot(home, bot).allow ?? [];
+  if (!Array.isArray(was) || was.some((rule) => typeof rule !== 'string' || rule.trim() === '')) {
+    throw new Error(`the allow entry in ${path.join(home, BOT_YAML)} is not a list of permission rules, so nothing was written. Fix it, then run the command again.`);
+  }
+  return { home, was };
+}
+
+/**
+ * Add the permission rules the user said yes to, `rules`, to the bot's `allow`,
+ * after the ones already there and never twice. Returns { bot, home, allow,
+ * added }: the whole list now, and what this call put in it.
+ *
+ * Only the list: the rules are written into the harness's settings by the
+ * caller, as the rules build is run by the caller of `changeBot`.
+ */
+export function allowRules(bots, bot, rules) {
+  const { home, was } = allowedNow(bots, bot, rules);
+  const added = [...new Set(rules)].filter((rule) => !was.includes(rule));
+  const allow = [...was, ...added];
+  if (added.length > 0) {
+    editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }));
+  }
+  return { bot, home, allow, added };
+}
+
 /**
  * Change the settings of the session `name` of the bot `bot`. Returns
  * { bot, home, session } — the session as it now reads.
@@ -414,7 +453,7 @@ export const SESSION_FIELDS = [
 ];
 
 /** Everything the top of a bot's own file can hold. */
-const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'sessions', 'paused'];
+const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'allow', 'sessions', 'paused'];
 
 /**
  * The keys in a bot's file that the kit does not know, and so that nothing

package/src/cli.js

@@ -12,13 +12,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
-import { addSession, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
+import { addSession, allowedNow, allowRules, botDir, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
 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 } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
+import { allowCommand, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -54,9 +55,13 @@ Usage:
                             given glued to its flag, so its dashes are not read
                             as ours: --prompt='- a bullet', and
                             --extra-arg=--search, once per extra argument.
-  obk bot change --bots <path> --bot <bot> --charter <text>
+  obk bot change --bots <path> --bot <bot> [--charter <text>]
+                 [--allow <rule> ...]
                             Give a bot a new charter and rebuild its AGENTS.md.
                             A running session reads it when it next starts.
+                            --allow records a permission rule the user said
+                            yes to, once per rule, and writes it into the bot's
+                            Claude settings.
   obk session change --bots <path> --bot <bot> --session <session>
                   [--model <m>] [--effort <e>] [--context <c>]
                   [--approval ${APPROVALS.join('|')}]
@@ -300,6 +305,7 @@ async function run(argv) {
       thread: { type: 'string' },
       peek: { type: 'boolean' },
       charter: { type: 'string' },
+      allow: { type: 'string', multiple: true },
       ...Object.fromEntries(SETTINGS.map(([flag]) => [flag, { type: 'string' }])),
       'extra-arg': { type: 'string', multiple: true },
       json: { type: 'boolean' },
@@ -441,19 +447,19 @@ const commands = {
     const seeded = initBots(bots, values.harness);
     // The typed path was for making the folder and naming it in a refusal; from
     // here on it is the fleet, and the fleet is its real path (#164).
-    const { tabs, rules, skills, paused, projects } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
+    const { tabs, rules, skills, permissions, paused, projects } = await bringUp(sameFleet(seeded.bots), { bot: BOT_FATHER });
     // Setup is the other place the PRD asks for Orca's own launch arguments to
     // be looked at (6.5), and the one where the user is still standing in front
     // of the fleet they are making. Only that one check: a folder init has just
     // made has nothing else to say about itself.
-    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, tabs, paused, projects, found: orcaSettingFindings() };
+    const answer = { bots: seeded.bots, created: seeded.created, completed: seeded.completed, rules, skills, permissions, tabs, paused, projects, found: orcaSettingFindings() };
     return { answer, lines: tabLines(answer, `Bot Father is up in Orca. Your bots folder: ${seeded.bots}`) };
   },
 
   async up(bots, values) {
     refuseWhenOrcaIsDown();
-    const { tabs, rules, skills, paused, projects } = await bringUp(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects };
+    const { tabs, rules, skills, permissions, paused, projects } = await bringUp(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, permissions, tabs, paused, projects };
     const up = [...new Set(tabs.map((tab) => tab.bot))];
     const summary = up.length === 0
       ? `Nothing was brought up in Orca. Your bots folder: ${bots}`
@@ -481,8 +487,8 @@ const commands = {
 
   async restart(bots, values) {
     refuseWhenOrcaIsDown();
-    const { closed, tabs, rules, skills, paused, projects } = await restartSessions(bots, { bot: values.bot, session: values.session });
-    const answer = { bots, created: [], completed: [], rules, skills, tabs, paused, projects, closed };
+    const { closed, tabs, rules, skills, permissions, paused, projects } = await restartSessions(bots, { bot: values.bot, session: values.session });
+    const answer = { bots, created: [], completed: [], rules, skills, permissions, tabs, paused, projects, closed };
     const what = values.session === undefined ? values.bot : `${values.bot} ${values.session}`;
     return {
       answer,
@@ -551,9 +557,12 @@ const commands = {
       answer: { bots, ...retired },
       lines: [
         ...closedLines(retired.closed),
-        // After every removal, whatever the window was told: Orca's window can
-        // keep a removed project's row even after it re-reads (stablyai/orca#20102).
-        ...(retired.project === undefined ? [] : [`removed    Orca project ${retired.project}`, RELOAD_LINE]),
+        // Orca's window keeps a removed project's row until it is rebuilt
+        // (#343): the user reloads it by hand only when the kit could not.
+        ...(retired.project === undefined ? [] : [
+          `removed    Orca project ${retired.project}`,
+          retired.windowReloaded ? "reloaded   Orca's window, so its sidebar no longer shows the project" : RELOAD_LINE,
+        ]),
         `retired    ${retired.bot}: moved to ${path.relative(bots, retired.moved)}, with its book, charter and memory`,
       ],
     };
@@ -567,7 +576,10 @@ const commands = {
     // A new bot is given what the lists already name, so it is whole before
     // anybody opens a tab on it.
     const skills = [linkSkills(bots, made.home, readBot(made.home))];
-    const answer = { bots, bot: made.bot, home: made.home, created: made.created, rules, skills };
+    // Nothing is allowed yet, so this writes nothing: it says which of the
+    // kit's rules wait for the user's yes (#344).
+    const permissions = [writePermissions(bots, made.home, readBot(made.home))].filter((entry) => entry !== undefined);
+    const answer = { bots, bot: made.bot, home: made.home, created: made.created, rules, skills, permissions };
     // A bot whose rules would not build is made but not finished: it has no
     // instructions, so `up` will not start it, and saying "give it a session"
     // would send the caller past the thing that needs settling first.
@@ -578,6 +590,7 @@ const commands = {
         ...made.created.map((entry) => `created    ${entry}`),
         ...rulesLines(rules, bots),
         ...skillsLines(skills),
+        ...permissionsLines(permissions, bots),
         trouble
           ? `${made.bot} is written, and its rules are not. Settle what the line above says, then:  ${shellWord(ownCli())} rules build --bots ${shellWord(bots)} --bot ${made.bot}`
           : `${made.bot} is written. Give it a session:  ${shellWord(ownCli())} session add --bots ${shellWord(bots)} --bot ${made.bot} --name <name>`,
@@ -590,22 +603,45 @@ const commands = {
     if (values.harness !== undefined) {
       throw new Error(`bot change does not change a bot's harness: its sessions' conversations belong to the harness they ran on. To move to ${values.harness}, give it a session on ${values.harness} with obk session add, or retire the bot with obk retire and create a new one.`);
     }
-    const changed = changeBot(bots, values.bot, { charter: values.charter });
-    // Rebuilt at once, as bot create builds it, so the charter a session reads
-    // is the one the bot now has.
-    const rules = [buildAgents(bots, changed.home, readBot(changed.home))];
-    const trouble = rules[0].trouble !== undefined;
-    return {
-      answer: { bots, bot: changed.bot, home: changed.home, charter: changed.charter, rules },
-      lines: [
+    if (values.charter === undefined && values.allow === undefined) {
+      throw new Error('bot change needs --charter <text> or --allow <rule>: what to change.');
+    }
+    // Refused before anything is written, so a bad rule, or a bad list already
+    // there, leaves the charter as it was too.
+    if (values.allow !== undefined) allowedNow(bots, values.bot, values.allow);
+
+    const answer = { bots, bot: values.bot, home: botDir(bots, values.bot) };
+    const lines = [];
+    let trouble = false;
+    if (values.charter !== undefined) {
+      const changed = changeBot(bots, values.bot, { charter: values.charter });
+      // Rebuilt at once, as bot create builds it, so the charter a session reads
+      // is the one the bot now has.
+      const rules = [buildAgents(bots, changed.home, readBot(changed.home))];
+      trouble = rules[0].trouble !== undefined;
+      Object.assign(answer, { charter: changed.charter, rules });
+      lines.push(
         `changed    the charter in ${path.join('bots', changed.bot, 'bot.yaml')}`,
         ...rulesLines(rules, bots),
         trouble
           ? `${changed.bot}'s charter is written, and its rules are not. Settle what the line above says, then:  ${shellWord(ownCli())} rules build --bots ${shellWord(bots)} --bot ${changed.bot}`
           : `${changed.bot}'s charter is changed. A session that is running read the old one when it started; it reads this one when it next starts.`,
-      ],
-      code: trouble ? 1 : 0,
-    };
+      );
+    }
+    if (values.allow !== undefined) {
+      const allowed = allowRules(bots, values.bot, values.allow);
+      // Written at once, as the charter's rules are built at once (#344).
+      const permissions = [writePermissions(bots, allowed.home, readBot(allowed.home))].filter((entry) => entry !== undefined);
+      Object.assign(answer, { allow: allowed.allow, permissions });
+      lines.push(
+        ...allowed.added.map((rule) => `${'allowed'.padEnd(9)}  ${rule}`),
+        ...permissionsLines(permissions, bots),
+        allowed.added.length === 0
+          ? `${allowed.bot} was allowed every one of these already.`
+          : `${allowed.bot}'s allow list in ${path.join('bots', allowed.bot, 'bot.yaml')} holds the user's yes.`,
+      );
+    }
+    return { answer, lines, code: trouble ? 1 : 0 };
   },
 
   'skills build'(bots, values) {
@@ -698,17 +734,19 @@ const commands = {
 
   'rules build'(bots, values) {
     const rules = buildRules(bots, { bot: values.bot });
-    const trouble = rules.filter((entry) => entry.trouble !== undefined);
+    const permissions = rules.flatMap((entry) => permissionsOf(bots, entry.bot));
+    const trouble = [...rules, ...permissions].filter((entry) => entry.trouble !== undefined);
     return {
-      answer: { bots, rules },
+      answer: { bots, rules, permissions },
       lines: [
         ...rulesLines(rules, bots),
+        ...permissionsLines(permissions, bots),
         trouble.length === 0
           ? `Rules are built. Your bots folder: ${bots}`
           // Not "not built": the file itself may be fine and the trouble be
           // the CLAUDE.md beside it, which is a bot whose rules still do not
           // reach both harnesses.
-          : `${trouble.map((entry) => entry.bot).join(', ')}: the rules are not in place. Settle what the lines above say, then build again.`,
+          : `${[...new Set(trouble.map((entry) => entry.bot))].join(', ')}: the rules are not in place. Settle what the lines above say, then build again.`,
       ],
       // The build is the whole of this command, so a build it could not make is
       // what the command ends in. `up` answers for its tabs and is not held to
@@ -1169,6 +1207,47 @@ function sessionLines(session) {
   ];
 }
 
+/**
+ * The permission rules of one bot, written as `rules build` writes them: its
+ * entry, one with the trouble that stopped it, or none for a bot that does not
+ * run on Claude. A bot.yaml that cannot be read is the rules build's to report.
+ */
+function permissionsOf(bots, name) {
+  const home = botDir(bots, name);
+  let bot;
+  try {
+    bot = readBot(home, name);
+  } catch {
+    return [];
+  }
+  try {
+    const entry = writePermissions(bots, home, bot);
+    return entry === undefined ? [] : [entry];
+  } catch (error) {
+    return [{ bot: name, file: path.join(home, '.claude', 'settings.json'), written: [], waiting: [], trouble: error.message }];
+  }
+}
+
+/**
+ * What became of each bot's permission rules: the file the allowed ones were
+ * written into, and the kit's rules that still wait for the user's yes, each
+ * word for word, with the one command that allows them once the user has said
+ * it (#344). Nothing for a bot with nothing written and nothing waiting.
+ */
+function permissionsLines(permissions, bots) {
+  return permissions.flatMap((entry) => [
+    ...(entry.trouble === undefined ? [] : [`${'refused'.padEnd(9)}  ${entry.trouble}`]),
+    ...(entry.written.length === 0
+      ? []
+      : [`${'wrote'.padEnd(9)}  ${path.relative(bots, entry.file)}  ${entry.written.length} permission rule${entry.written.length === 1 ? '' : 's'} the user allowed`]),
+    ...(entry.waiting.length === 0 ? [] : [
+      `${'waiting'.padEnd(9)}  ${entry.bot}: these permission rules wait for the user's yes, and none of them is written until then:`,
+      ...entry.waiting.map((rule) => `             ${rule}`),
+      `             Show them to the user. Once they say yes:  ${allowCommand(bots, entry.bot, entry.waiting)}`,
+    ]),
+  ]);
+}
+
 /**
  * What became of each bot's `AGENTS.md`, in the same column as the rest of the
  * report: what the build did, the file it did it to, and what it carries. A
@@ -1252,12 +1331,13 @@ function settingsLine({ bot, session, running, settings, rules }) {
   return `${word.padEnd(9)}  ${who}  ${each.join('  ')}  rules ${rules.state}`;
 }
 
-function tabLines({ bots, created, completed, rules, skills, tabs, paused = [], projects = [], found = [] }, summary) {
+function tabLines({ bots, created, completed, rules, skills, permissions = [], tabs, paused = [], projects = [], found = [] }, summary) {
   const lines = [
     ...created.map((entry) => `created    ${entry}`),
     ...completed.map((entry) => `completed  ${entry}`),
     ...rulesLines(rules, bots),
     ...skillsLines(skills),
+    ...permissionsLines(permissions, bots),
   ];
 
   for (const tab of tabs) {

package/src/health.js

@@ -27,6 +27,7 @@ import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
 import { bypassFlags, harnessOf, HARNESSES, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
 import { frontOfTab, orcaDefaultArgs, projects, tabs, wordsOfProcess } from './orca.js';
+import { permissionsTrouble } from './permissions.js';
 import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
 import { settingsInUse } from './settings.js';
@@ -191,6 +192,7 @@ function aboutBot(bots, name, setups, sessions) {
     ...sessionSettings(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')),
     ...skillsTrouble(bots, home, bot).map(said('skill')),
     ...inOrca(bots, home, bot, setups, sessions),
   ];

package/src/hooks.js

@@ -238,12 +238,12 @@ const unquoted = (word) => (word.startsWith("'") ? word.slice(1, -1).replaceAll(
  * cannot read as JSON is the user's, and guessing at it would lose what they
  * wrote, so the command says so and writes nothing.
  */
-function readSettings(file) {
+export function readSettings(file, what = "the kit's session hook") {
   if (!existsSync(file)) return {};
 
   const parsed = parse(readFileSync(file, 'utf8'));
   if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error(`${file} is not readable as JSON, and the kit's session hook goes in it. Fix it or move it aside, then run the command again.`);
+    throw new Error(`${file} is not readable as JSON, and ${what} goes in it. Fix it or move it aside, then run the command again.`);
   }
   return parsed;
 }

package/src/launch.js

@@ -99,6 +99,48 @@ export const setsNetworkAccess = (session) =>
 export const reachesMail = (session, harness) =>
   harness !== 'codex' || !turnedOff(session);
 
+/** Codex's flag for running without its shared background server (0.156.1 on). */
+const NO_DAEMON = '--no-daemon';
+
+// A string is shell text, so it is read as the shell will split it: `'--no-daemon'`
+// is the flag, and `'/tmp/a --no-daemon b'` is one path that merely says it.
+const setsNoDaemon = (session) => {
+  const extra = session.extra_args;
+  const words = Array.isArray(extra) ? extra.map(String) : set(extra) ? shellWords(String(extra)) : [];
+  return words.includes(NO_DAEMON);
+};
+
+/**
+ * The words a shell makes of `text`: split on blanks outside quotes, quotes
+ * removed, a backslash keeping the next character. Nothing is expanded.
+ */
+function shellWords(text) {
+  const words = [];
+  let word;
+  let quote;
+  for (let at = 0; at < text.length; at += 1) {
+    const char = text[at];
+    if (quote === "'") {
+      if (char === "'") quote = undefined;
+      else word += char;
+    } else if (quote === '"') {
+      if (char === '"') quote = undefined;
+      else if (char === '\\' && '"\\$`'.includes(text[at + 1] ?? ' ')) word += text[(at += 1)];
+      else word += char;
+    } else if (/\s/.test(char)) {
+      if (word !== undefined) words.push(word);
+      word = undefined;
+    } else {
+      word ??= '';
+      if (char === "'" || char === '"') quote = char;
+      else if (char === '\\') word += text[(at += 1)] ?? '';
+      else word += char;
+    }
+  }
+  if (word !== undefined) words.push(word);
+  return words;
+}
+
 const turnedOff = (session) =>
   extraWords(session.extra_args).some((word) => word.includes(`${NETWORK_ACCESS}=false`));
 
@@ -174,6 +216,11 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
   // take every other flag exactly as a fresh session does.
   if (resume !== undefined && harness === 'codex') words.push('resume');
   words.push(...APPROVAL[harness][set(session.approval) ? session.approval : DEFAULT_APPROVAL]);
+  // Codex 0.157 shares one background server between sessions by default, and
+  // a resume through it was seen to fail; without it Codex runs as 0.156 did
+  // (tech notes, section 3, #330). Codex refuses the flag twice, so the user's
+  // own wins.
+  if (harness === 'codex' && !setsNoDaemon(session)) words.push(NO_DAEMON);
 
   if (harness === 'claude') {
     // The name is the address other Claude sessions write to, so it goes on

package/src/orca-reload.applescript

@@ -0,0 +1,45 @@
+-- Run by the kit as `osascript orca-reload.applescript <Orca.app path>`, after
+-- a project was removed (#343, ADR 0025).
+--
+-- 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
+-- version check), and its menu item Force Reload rebuilds it. This has System Events
+-- click that item in the Orca at <Orca.app path>, and in no other app. The
+-- item's name is localized, so it is also known by the shortcut the menu draws
+-- after a tab, Orca's own ⌘⇧R. Only when that Orca is the front app: macOS
+-- takes a click on a background Orca's menu and Orca does nothing, and the
+-- kit never brings Orca to the front, where the user's typing would land. It
+-- prints `reloaded` only when it clicked; no such Orca, Orca not in front or
+-- no such item prints something else, and anything macOS refuses is an
+-- error. The kit reads all of those the same way.
+
+on run argv
+	set appPath to item 1 of argv
+	tell application "System Events"
+		repeat with candidate in (every application process whose name is "Orca")
+			if POSIX path of application file of candidate is appPath then
+				tell candidate
+					-- Menu 1 is Apple's own.
+					repeat with b from 2 to count of menu bar items of menu bar 1
+						set m to menu 1 of menu bar item b of menu bar 1
+						set labels to name of menu items of m
+						repeat with i from 1 to count of labels
+							set label to item i of labels
+							if label is not missing value then
+								if label is "Force Reload" or label starts with ("Force Reload" & tab) or label ends with (tab & "⌘⇧R") then
+									-- Asked last, right before the click, so Orca has had no time to
+									-- lose the front since.
+									if frontmost of candidate is false then return "Orca is not the front app"
+									click menu item i of m
+									return "reloaded"
+								end if
+							end if
+						end repeat
+					end repeat
+				end tell
+				return "no Force Reload in Orca's menus"
+			end if
+		end repeat
+	end tell
+	return "no Orca running from " & appPath
+end run

package/src/orca-runtime.cjs

@@ -0,0 +1,28 @@
+// Run by Orca's own binary as plain Node, the way Orca's `bin/orca` runs its
+// 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 0025): `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
+// the call; anything else is a non-zero exit, and the kit reads every non-zero
+// exit the same way.
+
+'use strict';
+
+const [client, method, params, wait] = process.argv.slice(2);
+
+process.exitCode = 1;
+const { RuntimeClient } = require(client);
+new RuntimeClient(undefined, Number(wait))
+  .call(method, JSON.parse(params))
+  // A write to a pipe is not done when it returns on macOS, so the exit waits
+  // for it: an answer cut short would read as no answer.
+  .then((answer) => answer?.ok === true && new Promise((done) => {
+    process.stdout.write(JSON.stringify(answer), () => {
+      process.exitCode = 0;
+      done();
+    });
+  }), () => {})
+  .finally(() => process.exit());

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0023). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0025). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -177,7 +177,7 @@ export function asFolderProject(setupId, title) {
  */
 export const deleteProject = (setupId) => orca(['project', 'setup-delete', '--setup', setupId]);
 
-/** Said after a run that made, renamed or removed a project, whatever `tellWindow` answered. */
+/** Said after a run that made or renamed a project, whatever `tellWindow` answered, and after a removal `reloadWindow` could not follow. */
 export const RELOAD_LINE = "If Orca's sidebar does not show it, reload the window with Cmd+Shift+R.";
 
 /** How long Orca's client waits for its runtime, and how long the kit waits for the client. */
@@ -190,13 +190,22 @@ 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, so this 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 0023). None of that is Orca's published
- * interface, so anything that goes wrong is a quiet false: it never throws and
- * is never tried twice, and the caller prints `RELOAD_LINE` either way.
+ * changes does, and Orca's CLI does not offer it (ADR 0025). The caller prints
+ * `RELOAD_LINE` either way. It does not take a removed project out of the
+ * sidebar: `reloadWindow` does.
  */
-export function tellWindow(projectId) {
+export const tellWindow = (projectId) => askRuntime('project.update', { projectId, updates: {} }) !== undefined;
+
+/**
+ * One call to Orca's runtime for a method its CLI does not offer, and the
+ * 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 0025). 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.
+ */
+function askRuntime(method, params) {
   try {
     // The CLI sits at <Orca.app>/Contents/Resources/bin/orca, often reached
     // through a link.
@@ -209,16 +218,55 @@ export function tellWindow(projectId) {
 
     const asked = spawnSync(
       path.join(contents, 'MacOS', 'Orca'),
-      [WINDOW_SCRIPT, client, projectId, String(CLIENT_WAIT_MS)],
-      { env, stdio: 'ignore', timeout: CLIENT_KILL_MS },
+      [RUNTIME_SCRIPT, client, method, JSON.stringify(params), String(CLIENT_WAIT_MS)],
+      { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: CLIENT_KILL_MS },
     );
-    return asked.error === undefined && asked.status === 0;
+    if (asked.error !== undefined || asked.status !== 0) return undefined;
+    return parse(asked.stdout) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const RUNTIME_SCRIPT = fileURLToPath(new URL('./orca-runtime.cjs', import.meta.url));
+
+/** The `osascript` this run asks. OBK_OSASCRIPT overrides it, as OBK_PS does `ps`. */
+const osascriptCli = () => process.env.OBK_OSASCRIPT || '/usr/bin/osascript';
+
+/** How long macOS is given to click the menu item. */
+const RELOAD_KILL_MS = 5000;
+
+/**
+ * Have Orca's window force-reload itself, after a project was removed: true
+ * only when it did (#343, ADR 0025).
+ *
+ * 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
+ * release fixes it, this can go behind a version check). Orca's own menu item
+ * Force Reload rebuilds it and keeps every terminal. So on macOS the kit has
+ * System Events click that item, in the Orca app its CLI belongs to and no
+ * other, and only while that Orca is the front app: a click on a background
+ * Orca is taken and does nothing, and the kit does not take the user's screen. None of that is Orca's published interface, and macOS may refuse it,
+ * so anything that goes wrong is a quiet false, as with `tellWindow`: it never
+ * throws and is never tried twice, and the caller prints `RELOAD_LINE`.
+ */
+export function reloadWindow() {
+  if (process.platform !== 'darwin') return false;
+  try {
+    // <Orca.app>/Contents/Resources/bin/orca, often reached through a link.
+    const app = path.resolve(realpathSync(orcaCli()), '..', '..', '..', '..');
+    const asked = spawnSync(osascriptCli(), [RELOAD_SCRIPT, app], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: RELOAD_KILL_MS,
+    });
+    return asked.error === undefined && asked.status === 0 && asked.stdout.trim() === 'reloaded';
   } catch {
     return false;
   }
 }
 
-const WINDOW_SCRIPT = fileURLToPath(new URL('./orca-window.cjs', import.meta.url));
+const RELOAD_SCRIPT = fileURLToPath(new URL('./orca-reload.applescript', import.meta.url));
 
 /**
  * The live tabs of the Orca project at `home`, each under its own tab id.
@@ -282,11 +330,14 @@ export function harnessInTab(handle, timeoutMs) {
     answered: answer.ok === true,
     blockedReason: answer.result?.wait?.blockedReason,
     agent,
-    ...frontOf(shown?.ptyId),
+    ...frontOf(handle, shown?.ptyId),
     ...screenOf(handle),
   };
 }
 
+/** Orca's reason for a folder-trust screen, which it can go on giving once that is answered (#342). */
+const TRUST_REASON = 'agent-trust-workspace';
+
 /** The kit's word for a tab whose screen shows a question of its harness's own (#329). */
 export const QUESTION_ON_SCREEN = 'question-on-screen';
 
@@ -320,7 +371,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 0023). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0025). 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.
@@ -359,6 +410,14 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   // A line typed into a screen waiting for an answer is that answer: once, it
   // confirmed Claude Code's folder-trust default, `No, exit` (tech notes,
   // section 1).
+  // Except where Orca still reports Codex's trust screen after it was
+  // answered, over an idle screen (#342). Nothing is typed then either, but
+  // there is nothing to answer, so the kit says what it saw. Claude Code's
+  // trust list is not numbered and the screen read cannot see it, so this is
+  // for Codex alone.
+  if (seen.blockedReason === TRUST_REASON && seen.agent === 'codex' && seen.question === false) {
+    return { unsure: `Orca still reports ${TRUST_REASON} in it, and its screen shows no question: Orca can go on reporting the trust screen after it is answered, and refuse a typed line while it does, so nothing was typed` };
+  }
   if (seen.blockedReason !== undefined) return { blocked: seen.blockedReason };
   // The shell in front is a tab with no harness, whatever a stale
   // `agentIdentity` says.
@@ -397,25 +456,63 @@ export function frontOfTab(handle) {
   } catch (error) {
     return { unreadable: `Orca would not show the tab: ${error.message}` };
   }
-  return frontOf(shown?.ptyId);
+  return frontOf(handle, shown?.ptyId);
 }
 
 /** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
 const psCli = () => process.env.OBK_PS || '/bin/ps';
 
 /**
- * Who holds the terminal of the pane `ptyId`: `{ front: 'shell' }`,
- * `{ front: 'program', command, pid }` with the name and pid of the process
- * leading the group in front, or `{ unreadable: <why> }`.
+ * Who holds the terminal of the tab `handle`, whose pane is `ptyId`:
+ * `{ front: 'shell' }`, `{ front: 'program', command, pid }` with the name and,
+ * where `ps` gave it, the pid of the process leading the group in front, or
+ * `{ unreadable: <why> }`.
+ *
+ * `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 0025).
+ */
+function frontOf(handle, ptyId) {
+  const read = frontByPs(ptyId);
+  if (read.unreadable === undefined) return read;
+  const asked = frontByOrca(handle);
+  return asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` };
+}
+
+/**
+ * Who holds the tab's terminal as Orca's runtime says it, through
+ * `terminal.inspectProcess`: Orca's own daemon reads the process table from
+ * outside any sandbox of the kit's, and names what leads the terminal's
+ * foreground group. Only a `live` answer counts. A process named there is the
+ * program in front; none named and no child in front is the shell. Anything
+ * else is "cannot tell": for a moment after a harness quits, Orca can name
+ * nothing and still see a child in front (read in the Orca 1.4.212 bundle).
+ */
+function frontByOrca(handle) {
+  const seen = askRuntime('terminal.inspectProcess', { terminal: handle })?.result?.process;
+  const evidence = seen?.foregroundProcessEvidence;
+  if (evidence?.verdict !== 'live') {
+    const why = typeof evidence?.reason === 'string' ? `: ${evidence.reason}` : '';
+    return { unreadable: `Orca's runtime could not say who is in front of it${why}` };
+  }
+  const name = (word) => typeof word === 'string' && word !== '';
+  if (name(evidence.processName)) return { front: 'program', command: evidence.processName };
+  if (evidence.processName === null && name(seen.foregroundProcess)) return { front: 'program', command: seen.foregroundProcess };
+  if (evidence.processName === null && seen.foregroundProcess === null && seen.hasChildProcesses === false) return { front: 'shell' };
+  return { unreadable: "Orca's runtime gave no answer the kit can read about who is in front of it" };
+}
+
+/**
+ * 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 0023).
+ * gives that pid's terminal's foreground process group (ADR 0025).
  * 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
  * here ends in "cannot tell" rather than in an error or a guess.
  */
-function frontOf(ptyId) {
+function frontByPs(ptyId) {
   let pane;
   try {
     pane = orca(['diagnostics', 'memory']).worktrees

package/src/permissions.js

@@ -0,0 +1,164 @@
+// The permission rules a bot may run with, written into its own Claude
+// settings, and only the ones its user said yes to (#344).
+//
+// A bot in auto mode is stopped by the harness's check for things the kit's own
+// rules tell every bot to do: read and send its mail, read a long message's
+// body beside the bots folder, commit. A matching allow rule is settled before
+// that check (Claude Code's permissions docs), so the kit offers every Claude
+// bot a small default set, spelled with its real CLI and bots folder. The user
+// sees the exact rules and says yes; `bot change --allow` keeps that yes in
+// bot.yaml's `allow`, and the kit's code writes what `allow` holds into
+// `.claude/settings.json` in the bot folder, beside its hook (ADR 0022). A model
+// editing the file by hand may get the format wrong; code does not.
+//
+// The kit owns only the entries `allow` holds. Any other entry in the file is
+// left where it is, and health names it.
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { leadsOutside } from './bot.js';
+import { readSettings } from './hooks.js';
+import { harnessOf, ownCli, shellWord } from './launch.js';
+
+/** Where Claude Code reads a project's settings, inside the bot home. */
+const FILE = '.claude/settings.json';
+
+/**
+ * The rules every Claude bot is offered, in this order. The mail commands are
+ * narrowed to this bots folder and spelled as the kit prints them in its
+ * nudge and in `message to`'s answer, which is what a bot runs. `//` is Claude's
+ * form for an absolute path.
+ */
+export function defaultRules(bots, cli = ownCli()) {
+  const kit = shellWord(cli);
+  const folder = shellWord(bots);
+  return [
+    `Bash(${kit} message check --bots ${folder}:*)`,
+    `Bash(${kit} message send --bots ${folder}:*)`,
+    `Bash(${kit} message to --bots ${folder}:*)`,
+    `Read(/${bots}.messages/**)`,
+    'Bash(git add:*)',
+    'Bash(git commit:*)',
+  ];
+}
+
+/** Whether any of a bot's sessions, or the bot itself, runs on Claude Code. */
+export const runsOnClaude = (bot) => bot.harness === 'claude'
+  || bot.sessions.some((session) => harnessOf(session, bot.harness) === 'claude');
+
+/** The rules the user allowed this bot, read from its bot.yaml, or a refusal naming the file. */
+export function allowOf(home, bot) {
+  const value = bot.allow;
+  if (value === undefined || value === null) return [];
+  const file = path.join(home, 'bot.yaml');
+  if (!Array.isArray(value) || value.some((rule) => typeof rule !== 'string' || rule.trim() === '')) {
+    throw new Error(`the allow entry in ${file} is not a list of permission rules, such as Bash(git add:*), so none of it is written. Fix it, then run the command again.`);
+  }
+  return value;
+}
+
+/** The default rules this bot has not been allowed yet, in the default order. */
+export function waitingFor(bots, home, bot) {
+  if (!runsOnClaude(bot)) return [];
+  const allowed = allowOf(home, bot);
+  return defaultRules(bots).filter((rule) => !allowed.includes(rule));
+}
+
+/** The one command that allows `rules` for `bot`, as the user can run it. */
+export const allowCommand = (bots, bot, rules) => [
+  shellWord(ownCli()), 'bot', 'change', '--bots', shellWord(bots), '--bot', shellWord(bot),
+  ...rules.flatMap((rule) => ['--allow', shellWord(rule)]),
+].join(' ');
+
+/**
+ * Write what the bot is allowed into its Claude settings, and say what waits:
+ * `{ bot, file, written, waiting }`, with `written` the rules this run added.
+ * Nothing for a bot that does not run on Claude.
+ *
+ * Only rules `allow` holds are written. Everything else in the file stays as it
+ * is, the user's own entries and their order included; a rule missing from the
+ * file goes after them, and a run with nothing to add writes nothing.
+ */
+export function writePermissions(bots, home, bot) {
+  if (!runsOnClaude(bot)) return undefined;
+  const file = path.join(home, FILE);
+  const allowed = allowOf(home, bot);
+  const waiting = waitingFor(bots, home, bot);
+  const answer = { bot: bot.name, file, written: [], waiting };
+  if (allowed.length === 0) return answer;
+
+  refuseOutside(home, file);
+  const settings = readSettings(file, 'the permission rules the user allowed');
+  const present = presentIn(settings, file);
+  const missing = [...new Set(allowed)].filter((rule) => !present.includes(rule));
+  if (missing.length === 0) return answer;
+
+  const wanted = { ...settings, permissions: { ...settings.permissions, allow: [...present, ...missing] } };
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(wanted, null, 2)}\n`);
+  return { ...answer, written: missing };
+}
+
+/**
+ * What health has to say about a bot's permission rules: `{ where, says }` for
+ * each entry in the file that `allow` does not hold, and each rule `allow`
+ * holds that the file lacks. Read only: an entry the kit did not write is named,
+ * never taken out.
+ */
+export function permissionsTrouble(home, bot) {
+  if (!runsOnClaude(bot)) return [];
+  const file = path.join(home, FILE);
+
+  let allowed;
+  try {
+    allowed = allowOf(home, bot);
+  } catch (error) {
+    return [{ where: path.join(home, 'bot.yaml'), says: error.message }];
+  }
+  if (!existsSync(file) && allowed.length === 0) return [];
+
+  // A link out of the bot folder is named by the hook's check already; here it
+  // matters only when there are rules the kit would write through it.
+  if (allowed.length === 0 && leadsOutside(home, file) !== undefined) return [];
+
+  let present;
+  try {
+    refuseOutside(home, file);
+    present = presentIn(readSettings(file, 'the permission rules the user allowed'), file);
+  } catch (error) {
+    return [{ where: file, says: error.message }];
+  }
+
+  return [
+    ...present.filter((rule) => !allowed.includes(rule)).map((rule) => ({
+      where: file,
+      says: `${file} allows ${rule}, and ${bot.name}'s bot.yaml does not: the kit did not write it. It stays where it is. If the user wants it, record their yes with obk bot change --allow; if not, take it out of the file.`,
+    })),
+    ...allowed.filter((rule) => !present.includes(rule)).map((rule) => ({
+      where: file,
+      says: `${file} does not hold ${rule}, which ${bot.name}'s bot.yaml allows, so ${bot.name}'s Claude sessions are asked about it. obk up writes it.`,
+    })),
+  ];
+}
+
+/** The file's `permissions.allow`, or a refusal when it is there and is not a list. */
+function presentIn(settings, file) {
+  const permissions = settings.permissions;
+  if (permissions === undefined) return [];
+  if (permissions === null || typeof permissions !== 'object' || Array.isArray(permissions)) {
+    throw new Error(`${file} has a permissions entry that is not a mapping, and the permission rules the user allowed go in it. Fix it or move it aside, then run the command again.`);
+  }
+  if (permissions.allow === undefined) return [];
+  if (!Array.isArray(permissions.allow)) {
+    throw new Error(`${file} has a permissions.allow entry that is not a list, and the permission rules the user allowed go in it. Fix it or move it aside, then run the command again.`);
+  }
+  return permissions.allow;
+}
+
+/** The kit writes a bot's settings in the bot folder and nowhere else (ADR 0022). */
+function refuseOutside(home, file) {
+  const real = leadsOutside(home, file);
+  if (real === undefined) return;
+  throw new Error(`${file} leads outside the bot folder, to ${real}, through a link, and the kit writes permission rules only inside the bot folder. Replace the link with a file of the bot's own, then run the command again.`);
+}

package/src/retire.js

@@ -16,16 +16,16 @@
 // restart or a pause it does not wait for the book to know which one it was.
 // The mailbox Runs stay: Orca has no way to remove one (ADR 0018).
 
-import { existsSync, mkdirSync, realpathSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import path from 'node:path';
 
 import { readBook, tabIdsIn, updateBook } from './book.js';
 import { botDir, dropSession, readBot } from './bot.js';
-import { deleteProject, findProject, projects, tabs, tellWindow } from './orca.js';
+import { deleteProject, findProject, projects, reloadWindow, tabs } from './orca.js';
 import { fleetMember } from './pause.js';
 import { closeTabs, tabsToClose } from './restart.js';
 import { unlinkSkills } from './skills.js';
-import { BOT_FATHER, promptPath, sessionsOf } from './up.js';
+import { promptPath, sessionsOf } from './up.js';
 
 /** Where retired bots go: beside `bots/`, where nothing the kit runs looks. */
 export const retiredDir = (bots) => path.join(bots, 'retired');
@@ -53,8 +53,9 @@ export async function retireSession(bots, { bot, session }) {
 }
 
 /**
- * Retire the bot `bot`. Returns `{ bot, closed, project, moved }`: the tabs it
- * closed, the Orca project it took away (if it had one) and where the bot is now.
+ * Retire the bot `bot`. Returns `{ bot, closed, project, windowReloaded, moved }`:
+ * the tabs it closed, the Orca project it took away (if it had one), whether
+ * Orca's window was reloaded after that, and where the bot is now.
  * When Orca does not confirm the project gone, it returns `{ bot, closed,
  * project, trouble }` instead, and the bot is left where it was.
  */
@@ -81,13 +82,13 @@ export async function retireBot(bots, { bot }) {
   // they are gone.
   const booked = Object.keys(readBook(home).sessions).map((name) => ({ name }));
   const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot);
+  let windowReloaded;
   if (project !== undefined) {
     deleteProject(project.id);
     // Orca's answer to the delete is not the same as the project being gone
     // (#282): its list afterwards is. Until that list is read and no longer
     // has the project, the bot stays where it is, so that retiring it again
-    // takes the project away and then finishes. The list is read once, for
-    // this and for the window both.
+    // takes the project away and then finishes.
     let setups;
     try {
       setups = projects();
@@ -97,7 +98,9 @@ export async function retireBot(bots, { bot }) {
     if (setups.some((setup) => setup.id === project.id || setup.path === home)) {
       return { bot, closed, project: project.id, trouble: `Orca answered the delete of Orca project ${project.id}, and still lists it. ${bot} was not moved. Retire ${bot} again with obk retire; if Orca still lists the project after that, remove it in Orca yourself, then retire ${bot} again.` };
     }
-    tellWindowOfRemoval(bots, setups);
+    // Only now: Orca's window keeps a removed project in its sidebar until
+    // it is rebuilt (#343).
+    windowReloaded = reloadWindow();
   }
 
   for (const name of new Set([...known.sessions, ...booked].map((session) => session.name))) {
@@ -107,21 +110,5 @@ export async function retireBot(bots, { bot }) {
   mkdirSync(retiredDir(bots), { recursive: true });
   renameSync(botDir(bots, bot), moved);
 
-  return { bot, closed, ...(project === undefined ? {} : { project: project.id }), moved };
-}
-
-/**
- * Tell Orca's window a project went (#224). The call names a project that is
- * still there, and Bot Father's is the one that always is; when Orca has none
- * for it in `setups`, Orca's list after the delete, there is nothing to call
- * on. Finding it is part of the workaround, so it fails as quietly as the call.
- */
-function tellWindowOfRemoval(bots, setups) {
-  try {
-    const home = botDir(bots, BOT_FATHER);
-    const father = existsSync(home) ? setups.find((setup) => setup.path === realpathSync(home)) : undefined;
-    if (father !== undefined) tellWindow(father.projectId);
-  } catch {
-    // Nothing: see above.
-  }
+  return { bot, closed, ...(project === undefined ? {} : { project: project.id, windowReloaded }), moved };
 }

package/src/rules.js

@@ -21,10 +21,23 @@ import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 
 import { botDir, botNames, displayName, readBot } from './bot.js';
+import { ownCli, shellWord } from './launch.js';
 
 /** The kit's own units, inside the installed package. */
 const KIT_RULES = fileURLToPath(new URL('../rules', import.meta.url));
 
+/**
+ * How a rule unit names the kit, and what the build writes in its place: the
+ * CLI that builds the file, by its own path. A bot runs the command as the file
+ * gives it, and Claude Code matches an allow rule against the command as
+ * written, not after the shell expands a variable, so a bot told to run
+ * `"${OBK_CLI:-obk}"` would never match the kit's own mail rule (#344).
+ */
+const KIT_WORD = '"${OBK_CLI:-obk}"';
+
+/** How a rule unit names the bots folder, which the build writes out for the same reason. */
+const BOTS_WORD = '<bots>';
+
 /** What a name in a list carries to mean one of the kit's rather than one of the user's. */
 const KIT = 'kit:';
 
@@ -116,7 +129,9 @@ export function blockFor(bots, bot) {
 
   const charter = typeof bot.charter === 'string' ? bot.charter.trim() : '';
   if (charter !== '') parts.push('## Charter', charter);
-  for (const unit of units) parts.push(`## ${unit.title}`, unit.body);
+  for (const unit of units) {
+    parts.push(`## ${unit.title}`, unit.body.replaceAll(KIT_WORD, shellWord(ownCli())).replaceAll(BOTS_WORD, shellWord(bots)));
+  }
 
   return { body: parts.join('\n\n'), units: units.map((unit) => unit.name) };
 }

package/src/up.js

@@ -12,6 +12,7 @@ import { forgetClaimed, forgetSession, readBook, sessionIdsIn, tabIdsIn, updateB
 import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
+import { writePermissions } from './permissions.js';
 import { addressOf, harnessOf, isAddressOf, isShortPrompt, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
 import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, tabs, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
 import { TAB_ENV } from './record.js';
@@ -58,7 +59,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
     return false;
   });
 
-  const { running, rules, skills } = prepareBots(bots, names, onlySession);
+  const { running, rules, skills, permissions } = prepareBots(bots, names, onlySession);
 
   const report = [];
   const projects = [];
@@ -83,6 +84,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
       trouble: `${entry.trouble} Its sessions were not started: a bot comes up with its rules or not at all.`,
     })),
     skills,
+    permissions,
     paused,
     projects,
   };
@@ -90,7 +92,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
 
 /**
  * Everything the bots need in place before a session starts, and which of them
- * can be started at all: `{ running, rules, skills }`.
+ * can be started at all: `{ running, rules, skills, permissions }`.
  *
  * Separate from the tabs because the order matters twice over. A session reads
  * its rules, its skills and its hooks as it comes up, so all three have to be
@@ -150,7 +152,12 @@ export function prepareBots(bots, names, onlySession) {
     }
   }
 
-  return { running, rules, skills };
+  // And the permission rules the user allowed, beside the hook and for the same
+  // reason: a session that comes up before its rules are there is asked about
+  // what the user already said yes to (#344).
+  const permissions = running.map(({ bot, home }) => writePermissions(bots, home, bot)).filter((entry) => entry !== undefined);
+
+  return { running, rules, skills, permissions };
 }
 
 /**
@@ -377,13 +384,13 @@ function launchFor(bots, bot, session, harness, home, workDir, resume, held) {
   // through the tab's shell a character at a time.
   const promptFile = prompt === undefined || isShortPrompt(prompt) ? undefined : promptPath(bots, bot.name, session.name);
   // A new conversation is given a new name. A resume goes on under the one the
-  // kit gave it, and under no `-n` at all when the book `held` none of the
-  // kit's own: a resume keeps whatever name the conversation has, which is
-  // proven, and whether `-n` renames it is not (#286). Such a session is
-  // written to through its mailbox until it next starts fresh.
+  // kit gave it, and gets a new one when the book `held` none of the kit's own:
+  // `--resume <id> -n <name>` renames the conversation, proven live (#319), so
+  // a session still under the shared `<bot>.<session>` moves to an address of
+  // its own here.
   const address = harness !== 'claude' ? undefined
-    : resume === undefined ? addressOf(bot.name, session.name)
-    : isAddressOf(bot.name, session.name, held) ? held : undefined;
+    : resume !== undefined && isAddressOf(bot.name, session.name, held) ? held
+    : addressOf(bot.name, session.name);
   const line = launchCommand(session, {
     harness,
     home,

package/src/orca-window.cjs

@@ -1,21 +0,0 @@
-// Run by Orca's own binary as plain Node, the way Orca's `bin/orca` runs its
-// CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-window.cjs <client> <projectId> <wait>`.
-//
-// It asks Orca's runtime, through Orca's own client, for `project.update` with
-// no changes on one project. That is the call that makes Orca's window read its
-// projects again, and Orca's CLI does not offer it (#224, ADR 0023). It exits 0
-// only when the runtime took the call; anything else is a non-zero exit, and
-// the kit reads every non-zero exit the same way.
-
-'use strict';
-
-const [client, projectId, wait] = process.argv.slice(2);
-
-process.exitCode = 1;
-const { RuntimeClient } = require(client);
-new RuntimeClient(undefined, Number(wait))
-  .call('project.update', { projectId, updates: {} })
-  .then((answer) => {
-    if (answer?.ok === true) process.exitCode = 0;
-  }, () => {})
-  .finally(() => process.exit());