@assuredloop/orca-bot-kit 0.26.0 → 0.26.1

package/README.md

@@ -141,15 +141,19 @@ words, `dangerously-skip`
 ([ADR 0015](docs/adr/0015-three-approval-levels-auto-by-default.md)). Only
 `obk permission approval` changes it, after your yes: `session add` and
 `session change` take no approval, and refuse an extra argument that sets one
-([ADR 0037](docs/adr/0037-permission-changes-and-risky-operations-have-commands-of-their-own.md)).
+([ADR 0041](docs/adr/0041-permission-changes-and-risky-operations-have-commands-of-their-own.md)).
 
 Every bot gets the kit's default permission rules, written by the kit with
 nobody asked: its own commands for this bots folder, reading a long message,
 `git add` and `git commit`, and Orca's `orca orchestration check --run`
 ([ADR 0036](docs/adr/0036-the-kit-writes-every-bots-default-permission-rules.md)).
-`obk permission`, `obk retire`, `obk pause` and `obk init` are not in the set,
-and keep your yes. A rule beyond the set is written by `obk permission allow`,
-after your yes to the exact rule.
+`obk permission`, `obk retire`, `obk pause`, `obk restart`, `obk bot create`
+and `obk init` are not in the set, and keep your yes
+([ADR 0041](docs/adr/0041-permission-changes-and-risky-operations-have-commands-of-their-own.md)).
+A rule beyond the set is written by `obk permission allow`, after your yes to
+the exact rule. A bot that still holds the `obk restart` or `obk bot create`
+rule, which kit 0.26.0 gave every bot, keeps it: `obk rules build` and `obk up`
+name it, with the `obk permission disallow` command that takes it back.
 
 Neither command touches Orca. `obk up` is what makes it all real there: an Orca
 project per bot, a tab per session, each started at the bot home with its own
@@ -676,6 +680,8 @@ except the mailbox Runs Orca gives no way to delete, which the run names; it
 never closes a tab it did not open. The trust its harnesses write into your
 `~/.codex/config.toml` and `~/.claude.json` for the run's own throwaway folders
 is taken out again after the run, and named; nothing else in them is changed.
+An Orca project the run leaves in one of its own throwaway folders is named,
+with its setup id, and fails the run; the command removes none itself.
 
 They run on the machine the command is typed on, so the command will not start
 them by itself. On its own it says what it is about to drive — whose machine,

package/package.json

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

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

@@ -213,8 +213,11 @@ its commits. The kit writes this default set itself, with nobody asked:
 does not have yet to its `bot.yaml` and its settings, or for Codex its
 `.codex/rules/obk.rules`, and say which rules they wrote. The set leaves out
 the commands that keep the user's yes: `obk permission`, `obk retire`, `obk
-pause` and `obk init`. Never write a permission rule into a settings or rules
-file by hand.
+pause`, `obk restart`, `obk bot create` and `obk init`. A bot that still holds
+the `obk restart` or `obk bot create` rule from kit 0.26.0 keeps it, and `obk
+rules build` and `obk up` name it with the `obk permission disallow` command
+that takes it back; run that command only after the user's yes. Never write a
+permission rule into a settings or rules file by hand.
 
 The charter decides what else the bot needs. What it lets the bot do without
 asking, such as merging pull requests, auto mode or Codex's sandbox can still

package/src/bot.js

@@ -162,7 +162,7 @@ export function readBot(home, name = path.basename(home)) {
     // The roles its temporary sessions can be made in, judged by tempRoles.
     ...(bot.temp_roles === undefined ? {} : { temp_roles: bot.temp_roles }),
     // The widest approval its temporary sessions may be made at, the user's yes
-    // kept by `permission approval --temps` (ADR 0037).
+    // kept by `permission approval --temps` (ADR 0041).
     ...(bot.temp_approval === undefined ? {} : { temp_approval: bot.temp_approval }),
     // A paused bot is one `obk up` leaves closed; its sessions keep their book.
     ...(bot.paused === true ? { paused: true } : {}),
@@ -362,7 +362,7 @@ export function changeSession(bots, bot, name, settings) {
 
 /**
  * Record the widest approval the bot's temporary sessions may be made at,
- * `level`, as `temp_approval` (ADR 0037). Returns { bot, home, level }.
+ * `level`, as `temp_approval` (ADR 0041). Returns { bot, home, level }.
  */
 export function setTempApproval(bots, bot, level) {
   editBot(bots, bot, `let ${bot}'s temporary sessions be made at ${level}`, (doc) => doc.set('temp_approval', level), (was) => ({ ...was, temp_approval: level }));

package/src/cli.js

@@ -909,7 +909,7 @@ const commands = {
       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.`);
     }
     // Permission changes have commands of their own, which keep the user's yes
-    // (ADR 0037): the old spelling refuses, and changes nothing.
+    // (ADR 0041): the old spelling refuses, and changes nothing.
     const moved = [['allow', 'permission allow'], ['disallow', 'permission disallow']].filter(([flag]) => values[flag] !== undefined);
     if (moved.length > 0) {
       throw new Error(`bot change no longer takes ${moved.map(([flag]) => `--${flag}`).join(' or ')}: permission rules change through ${moved.map(([, now]) => `${shellWord(ownCli())} ${now} --bots ${shellWord(bots)} --bot ${values.bot} --rule <rule>`).join(' and ')}, after the user's yes. Nothing was changed.`);
@@ -1116,7 +1116,7 @@ const commands = {
       ...(values.effort === undefined ? {} : { effort: values.effort }),
       ...(values['extra-arg'] === undefined ? {} : { extra_args: values['extra-arg'] }),
     };
-    // A run's launch may not widen its approval (ADR 0037).
+    // A run's launch may not widen its approval (ADR 0041).
     if (values['run-on'] === 'codex') refuseApprovalArgs('codex', values['extra-arg']);
     const groom = grooming(bots, { at: values.at, ask, run });
     return { answer: { bots, groom }, lines: groomLines(groom, bots) };
@@ -1407,7 +1407,7 @@ function workDirFound(values, bot, home, session) {
 
 /**
  * Refuse what would change a session's approval through `session add` or
- * `session change` (ADR 0037): `--approval`, and an extra argument that sets
+ * `session change` (ADR 0041): `--approval`, and an extra argument that sets
  * it on the session's harness. Only `permission approval` changes it.
  */
 function refuseApproval(bots, values, command) {
@@ -1787,17 +1787,22 @@ function charterRulesLines(bots, bot, rules) {
 
 /**
  * What became of each bot's permission rules: each of the kit's default rules
- * the run added to the bot, word for word (ADR 0036), and the file the allowed
- * ones were written into. Nothing for a bot with nothing added or written.
+ * the run added to the bot, word for word (ADR 0036), each rule of a command no
+ * longer in the set that the bot still holds, with the command that takes it
+ * back (ADR 0041), and the file the allowed ones were written into. Nothing for
+ * a bot with nothing added, held or written.
  */
 function permissionsLines(permissions, bots) {
   // A bot on both harnesses has an entry for each file, with the same
-  // defaults: they are listed once, with the first.
+  // defaults and held rules: they are listed once, with the first.
   const listed = new Set();
+  const disallow = (bot, rule) => `${shellWord(ownCli())} permission disallow --bots ${shellWord(bots)} --bot ${shellWord(bot)} --rule ${shellWord(rule)}`;
   return permissions.flatMap((entry) => [
     ...(entry.trouble === undefined ? [] : [`${'refused'.padEnd(9)}  ${entry.trouble}`]),
-    ...((entry.defaults ?? []).length === 0 || listed.has(entry.bot) || !listed.add(entry.bot) ? []
-      : entry.defaults.map((rule) => `${'allowed'.padEnd(9)}  ${entry.bot}  ${rule}`)),
+    ...(listed.has(entry.bot) || !listed.add(entry.bot) ? [] : [
+      ...(entry.defaults ?? []).map((rule) => `${'allowed'.padEnd(9)}  ${entry.bot}  ${rule}`),
+      ...(entry.held ?? []).map((rule) => `${'holds'.padEnd(9)}  ${entry.bot}  ${rule}, which is no longer one of the kit's defaults. To take it back:  ${disallow(entry.bot, rule)}`),
+    ]),
     ...(entry.written.length === 0
       ? []
       : [`${'wrote'.padEnd(9)}  ${path.relative(bots, entry.file)}  ${entry.written.length} permission rule${entry.written.length === 1 ? '' : 's'} from its allow list`]),

package/src/commands.js

@@ -1,7 +1,7 @@
 // The kit's commands, each with the flags it cannot do without, which `obk`
 // reads to parse a command line; and the two lists every command is on one of:
 // those every bot is allowed by default (#527, ADR 0036), and those kept back
-// for the user's yes (ADR 0037). A new command is on neither until someone
+// for the user's yes (ADR 0041). A new command is on neither until someone
 // puts it on one, and a test holds every command to that choice.
 
 /** The commands, and the flags each one cannot do without. */
@@ -56,8 +56,8 @@ export const COMMANDS = {
  * runs whatever its arguments say never is.
  */
 export const DEFAULT_COMMANDS = [
-  'up', 'restart', 'unpause', 'health', 'groom', 'roster', 'usage',
-  'bot create', 'bot change', 'rules build',
+  'up', 'unpause', 'health', 'groom', 'roster', 'usage',
+  'bot change', 'rules build',
   'skills add', 'skills remove', 'skills build', 'skills fetch', 'skills update', 'source add',
   'session add', 'session change', 'session clear', 'session compact',
   'message to', 'message send', 'message check',
@@ -68,7 +68,17 @@ export const DEFAULT_COMMANDS = [
 
 /**
  * The commands kept out of the default permission set, which keep the user's
- * yes (ADR 0037): the ones that change permissions, close a long-lived
- * session, or make the bots folder.
+ * yes (ADR 0041): the ones that change permissions, close a long-lived
+ * session, make the bots folder, or make a bot, which the owner leaves to Bot
+ * Father (#548).
  */
-export const KEPT_BACK = ['init', 'retire', 'pause', 'permission allow', 'permission disallow', 'permission approval'];
+export const KEPT_BACK = [
+  'init', 'retire', 'pause', 'restart', 'bot create',
+  'permission allow', 'permission disallow', 'permission approval',
+];
+
+/**
+ * The commands kit 0.26.0 gave every bot by default and that are kept back now
+ * (#548). A bot may still hold their rules, which the kit names and leaves.
+ */
+export const NO_LONGER_DEFAULT = ['restart', 'bot create'];

package/src/health.js

@@ -213,7 +213,7 @@ 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');
-  // The widest approval they may be made at, the user's yes (ADR 0037).
+  // The widest approval they may be made at, the user's yes (ADR 0041).
   const level = bot.temp_approval;
   const approval = level === undefined || APPROVALS.includes(level) ? [] : [{
     where,

package/src/launch.js

@@ -45,7 +45,7 @@ export const approvalRank = (level) => ['ask', 'auto', 'dangerously-skip'].index
 
 /**
  * The harness flags that set approval or permissions, which only
- * `obk permission approval` may change, not an extra argument (ADR 0037).
+ * `obk permission approval` may change, not an extra argument (ADR 0041).
  * Codex's `-a` and `-s` take their value glued on too.
  */
 const APPROVAL_FLAGS = {

package/src/permissions.js

@@ -24,7 +24,7 @@ import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync
 import path from 'node:path';
 
 import { allowRules, leadsOutside } from './bot.js';
-import { DEFAULT_COMMANDS } from './commands.js';
+import { DEFAULT_COMMANDS, NO_LONGER_DEFAULT } from './commands.js';
 import { readSettings } from './hooks.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 
@@ -37,7 +37,7 @@ const CODEX_FILE = `${CODEX_RULES}/obk.rules`;
 
 /**
  * The rules every bot is given (ADR 0036): each of the kit's default commands,
- * and none kept back for the user's yes (ADR 0037), narrowed to this bots folder and
+ * and none kept back for the user's yes (ADR 0041), narrowed to this bots folder and
  * spelled as the kit prints them, which is what a bot runs; reading a long
  * message; committing; and the check Orca's mail notice tells a session to
  * run. `//` is Claude's form for an absolute path.
@@ -54,6 +54,18 @@ export function defaultRules(bots, cli = ownCli()) {
   ];
 }
 
+/**
+ * The rules of the commands that were defaults once and are kept back now
+ * (#548), spelled as `defaultRules` spelled them, that the bot's `allow`
+ * holds. The kit cannot tell its own old entry from a user's yes to the same
+ * rule, so it names them and leaves them (ADR 0041).
+ */
+export function heldRules(bots, home, bot, cli = ownCli()) {
+  const allowed = allowOf(home, bot);
+  return NO_LONGER_DEFAULT.map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+    .filter((rule) => allowed.includes(rule));
+}
+
 /** Command wrappers: programs that run the command their arguments name. */
 const WRAPPERS = new Set(['env', 'xargs', 'sudo', 'eval', 'exec', 'nohup', 'timeout', 'nice', 'command', 'time', 'watch']);
 
@@ -261,26 +273,30 @@ export function refuseNoCodexForm(bot, rules) {
  * Add the default rules the bot is not allowed yet to its `allow` (ADR 0036),
  * then write what it is allowed into the files of the harnesses it runs on:
  * one entry per file, Claude's first, each with `defaults`, the rules this run
- * added. The harness files are written first and bot.yaml last, as
+ * added, and `held`, the rules of commands no longer in the set that the bot
+ * still holds (#548). The harness files are written first and bot.yaml last, as
  * `permission allow` writes them (#383). With `keepGoing`, a file the kit may
  * not write is an entry with its `trouble` rather than a throw.
  */
 export function writePermissions(bots, home, bot, { keepGoing = false } = {}) {
   const writers = [[runsOnClaude, FILE], [runsOnCodex, CODEX_FILE]].filter(([runs]) => runs(bot));
   let defaults = [];
+  // Read before anything is written, so a file's trouble still names them.
+  let held = [];
   try {
+    held = heldRules(bots, home, bot);
     defaults = writers.length === 0 ? [] : missingDefaults(bots, home, bot);
     if (defaults.length > 0) {
       const { allow } = allowRules(bots, bot.name, defaults, { write: false });
       const entries = allowIn(bots, home, { ...bot, allow })();
       allowRules(bots, bot.name, defaults);
-      return entries.map((entry) => ({ ...entry, defaults }));
+      return entries.map((entry) => ({ ...entry, defaults, held }));
     }
     return writers.map(([runs]) => (runs === runsOnClaude ? planClaude : planCodex)(bots, home, bot).write())
-      .map((entry) => ({ ...entry, defaults }));
+      .map((entry) => ({ ...entry, defaults, held }));
   } catch (error) {
     if (!keepGoing) throw error;
-    return writers.map(([, file]) => ({ bot: bot.name, file: path.join(home, file), written: [], defaults: [], trouble: error.message }));
+    return writers.map(([, file]) => ({ bot: bot.name, file: path.join(home, file), written: [], defaults: [], held, trouble: error.message }));
   }
 }
 

package/src/temp.js

@@ -178,7 +178,7 @@ function settingsFor(bot, maker, option, given) {
 /**
  * Refuse an approval wider than the widest of the maker's own and the bot's
  * `temp_approval`, which only the user's yes through `permission approval
- * --temps` widens (ADR 0037).
+ * --temps` widens (ADR 0041).
  */
 function refuseWiderApproval(bots, caller, bot, maker, asked) {
   if (asked === undefined) return;