@assuredloop/orca-bot-kit 0.25.4 → 0.26.0

package/README.md

@@ -128,8 +128,8 @@ obk up          --bots /path/to/my-bots
 that file and the rule units, `CLAUDE.md` as a symlink to it, and a `.gitignore`
 for `work/`.
 `session add` writes one session into `bot.yaml`: its harness (the bot's unless
-it says otherwise), model, effort, context window, approval level, start prompt,
-work dir and any extra arguments for the harness. A start prompt is either text
+it says otherwise), model, effort, context window, start prompt,
+work dir and any extra arguments for the harness, and the approval level. A start prompt is either text
 (`--prompt`) or, when it is long, a file in the bot home the session points at
 (`--prompt-file prompts/reviewer.md`), and it reaches the harness as written,
 apart from two things the kit does on purpose: blank space at either end is
@@ -138,7 +138,18 @@ note about it. Anything you leave out is the
 harness's own default; the kit names no model of its own. The approval level is
 `auto` — the harness's real auto mode — unless you ask for `ask` or, in those
 words, `dangerously-skip`
-([ADR 0015](docs/adr/0015-three-approval-levels-auto-by-default.md)).
+([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)).
+
+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.
 
 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
@@ -443,6 +454,11 @@ Bot Father does these for you when you ask; these are the commands it runs.
 
 ```sh
 obk bot change --bots /path/to/my-bots --bot api-bot --charter "…"
+obk bot change --bots /path/to/my-bots --bot api-bot --role-cap reviewer=2
+obk permission allow --bots /path/to/my-bots --bot api-bot --rule 'Bash(gh pr merge:*)'
+obk permission disallow --bots /path/to/my-bots --bot api-bot --rule 'Bash(gh pr merge:*)'
+obk permission approval --bots /path/to/my-bots --bot api-bot --session daily --approval ask
+obk permission approval --bots /path/to/my-bots --bot api-bot --temps --approval dangerously-skip
 obk session change --bots /path/to/my-bots --bot api-bot --session daily --model opus
 obk skills remove --bots /path/to/my-bots --bot api-bot --skill kit:obk-tdd
 obk pause --bots /path/to/my-bots --bot api-bot [--session daily]
@@ -643,13 +659,14 @@ npm run mutate                # the mutation audit, on what your branch changed
 
 The tests come in two layers, and every test file belongs to one of them.
 
-`npm test` is `test/*.test.js`: unit tests and end-to-end runs of the CLI in a
-throwaway folder, with a fake `orca` on PATH. It needs nothing but Node, so
-[GitHub Actions](.github/workflows/ci.yml) runs it on every pull request, split
-into shards that run side by side, on Node 25.8.0, the current line. A release
-runs every shard on 25.8.0 and again on 24.21.0, the floor `engines.node`
-promises users, with only the kit's own dependencies installed, before anything
-is published.
+`npm test` is `test/*.test.js` and `test/dev/*.test.js`: unit tests and
+end-to-end runs of the CLI in a throwaway folder, with a fake `orca` on PATH. It
+needs nothing but Node, so [GitHub Actions](.github/workflows/ci.yml) runs it on
+every pull request, split into shards that run side by side, on Node 25.8.0, the
+current line. A release runs every shard on 25.8.0 and again on 24.21.0, the
+floor `engines.node` promises users, with only the kit's own dependencies
+installed, before anything is published. The floor leaves out `test/dev/`, the
+tests that need a development tool.
 
 `npm run test:system` is `test/system/*.test.js`: the real `obk` against the
 real Orca and the real harnesses on your own machine. No CI runner can do that,

package/SETUP.md

@@ -128,11 +128,12 @@ tab, which is a plain shell for work across the whole fleet.
 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;
+- **the permission rules it wrote**: the kit's default set, so auto mode does
+  not stop Bot Father for the kit's own commands, reading a long message
+  beside the bots folder, and its commits. The kit writes this set for every
+  bot, with nobody asked. Say in a sentence what it allows, and that
+  `obk permission`, `obk retire`, `obk pause` and `obk init` are not in it and
+  keep their yes;
 - **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
@@ -228,8 +229,8 @@ home. The kit never makes a git worktree, so
 `2. New worktree` is never the answer.
 
 A bot's own temporary sessions are answered by their maker, through the kit, so
-that one narrow permission rule allows it rather than a rule to type into any
-tab. On Codex's hooks review, the maker runs
+that a narrow permission rule of the kit's default set allows it rather than a
+rule to type into any tab. On Codex's hooks review, the maker runs
 `obk temp trust-hooks --bots <their path> --name <session>`. On Claude Code's
 `Teach auto mode` screen, it runs `obk temp answer --bots <their path> --name <session>`.
 That command reads the screen and answers only when it holds one of the two
@@ -237,16 +238,35 @@ shapes in the table exactly as the kit knows it: Esc for the 2.1.283 form, and
 **2. Not now** for the 2.1.289 list. On the list it sends the arrows, reads the
 screen again, and sends the return only with the selection on **2. Not now**.
 It refuses any other screen, types nothing then, and prints what it saw.
-Afterwards it checks that the screen has gone. In
-auto mode the maker's bot needs this rule, with the kit's full CLI path for
-`<kit>`, as the command's own output prints it:
+Afterwards it checks that the screen has gone. The kit's default set allows
+both commands for every bot, so there is nothing to ask the user. The rules
+are these, with the kit's full CLI path for `<kit>`, as the command's own
+output prints it:
 
 ```text
-Bash(<kit> temp answer:*)
+Bash(<kit> temp answer --bots <their path>:*)
+Bash(<kit> temp trust-hooks --bots <their path>:*)
 ```
 
-Ask the user, and only after their yes run
-`obk bot change --bots <their path> --bot <bot> --allow 'Bash(<kit> temp answer:*)'`.
+A long-lived session's two screens go through the kit as well, not through the
+keys. On Codex's hooks review, run
+`obk session trust-hooks --bots <their path> --bot <bot> --session <session>`.
+On Claude Code's `Teach auto mode` screen, run
+`obk session answer --bots <their path> --bot <bot> --session <session>`.
+A long-lived session is Bot Father's, so run them from outside the fleet's tabs,
+as you do here, or from a Bot Father session. A session of any other bot is
+refused. They make the same checks as the temp commands. Before either
+trust-hooks command trusts hooks, the kit checks that the hooks on the review
+are its own: the bot's `.codex/hooks.json` holds only the kit's hooks, and the
+count on the screen is the number of the kit's hooks that Codex does not trust
+yet. When it refuses, it says what it saw: type nothing, and tell them what it
+said. Use the keys in the table for the screens the kit does not answer.
+The kit reads Codex's trust from the caller's `CODEX_HOME`, else `~/.codex`;
+a bot run under another `CODEX_HOME` is outside what the kit can see.
+The kit also records the extra arguments it launched each session with, and
+refuses when they mention hooks, or when there is no record. A Codex that
+someone started again by hand in that tab, with other flags, is outside what
+the kit records.
 
 **Anything you do not recognise: type nothing.** Tell them what is on the
 screen and which tab it is in, and wait. A keypress into a menu you have not read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.25.4",
+  "version": "0.26.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,8 +23,9 @@
     "SETUP.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js",
-    "test:shard": "node --test --test-shard=$SHARD test/*.test.js",
+    "test": "node --test test/*.test.js test/dev/*.test.js",
+    "test:shard": "node --test --test-shard=$SHARD test/*.test.js test/dev/*.test.js",
+    "test:floor": "node --test --test-shard=$SHARD test/*.test.js",
     "test:system": "node scripts/test-system.js",
     "mutate": "node scripts/mutate.js"
   },

package/rules/limits.md

@@ -17,6 +17,6 @@ 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 or rules files are the kit's to write,
-after the user's yes to the exact rules: `"${OBK_CLI:-obk}" bot change --allow <rule>` or
-`--disallow <rule>`. Never edit one in or out yourself, Bot Father included.
+Permission rules and approvals are the kit's to write: its default set at once,
+anything else after the user's yes to it, by `"${OBK_CLI:-obk}" permission allow`,
+`disallow` or `approval`. Never edit one in or out yourself, Bot Father included.

package/rules/mail.md

@@ -8,6 +8,10 @@ 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.
 
+If your harness refuses a message, do not send it again by another road. Tell
+your maker or your user, with the harness's reason. A refusal can mean a missing
+permission rule, which they can add through the kit after the user's yes.
+
 Mail is queued, not an interruption. Read it when you finish what you are on.
 
 Ask for a reply when you need one, and send one when you were asked for one.

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

@@ -194,7 +194,7 @@ The kit's command line does the writing, and the files belong to the user:
 source add` records where online skills come from and `obk skills fetch`
 clones them, `obk skills add` puts one on a bot, `obk skills build` links
 them, and `obk up` opens what is missing in Orca. `obk bot change` gives a
-bot a new charter, `obk session change` changes a session's settings, and
+bot a new charter or a role's cap, `obk session change` changes a session's settings, and
 `obk skills remove` takes a skill off a list (then `obk skills build`). `obk
 pause` stops a bot or a session for now and `obk unpause` brings it back;
 `obk retire` ends one. After `obk up`, `obk restart` or `obk unpause`, read
@@ -206,16 +206,15 @@ Run `obk --help` for the flags of the version actually installed rather than
 trusting a line you remember.
 
 A bot needs a few permission rules so that auto mode, or Codex's sandbox and
-reviewer, 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, or for Codex into its
-`.codex/rules/obk.rules`. 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 or rules file by hand.
+reviewer, does not stop it for what the kit's own rules tell it to do: the
+kit's own commands, reading a long message kept beside the bots folder, and
+its commits. The kit writes this default set itself, with nobody asked:
+`obk bot create`, `obk up` and `obk rules build` add each default rule a bot
+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.
 
 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
@@ -228,14 +227,14 @@ Spell them in Claude Code's form for a Codex bot too, `Bash(<command>:*)`: the
 kit writes Codex's own form of each, and says which ones Codex has none for,
 such as an `Edit` rule or one exact command.
 Show the user the list word for word, with a line on what each lets the bot do,
-and only after their yes run `obk bot change --allow`, once per rule they said
-yes to. On a no, run nothing. `obk bot change --charter` names the rules the
+and only after their yes run `obk permission allow --rule <rule>`, once per
+rule they said yes to. On a no, run nothing. `obk bot change --charter` names the rules the
 bot is allowed now; say which of them the new charter no longer grants, show
 each word for word, and ask whether to take it back. Only after their yes run
-`obk bot change --disallow`, once per rule, which takes it out of `bot.yaml`
+`obk permission disallow --rule <rule>`, once per rule, which takes it out of `bot.yaml`
 and the bot's settings or Codex rules; on a no, run nothing, and it stays
 allowed. A rule the user added to a settings file by hand is theirs to take
-out; the kit refuses it. Keep
+out; the kit refuses it, and it refuses a rule of its own default set too. Keep
 each rule narrow: a program and what it does. The kit refuses a rule that lets
 the bot run any command, a program with any arguments, or a shell or
 interpreter with any arguments; a user who wants one for a bot adds it to that
@@ -331,9 +330,21 @@ into any tab. The same goes for Claude Code's `Teach auto mode` screen on a
 temporary session you made: answer it with `obk temp answer --bots <bots>
 --name <session>`. It answers only a shape in the table exactly as the kit
 knows it (Esc on the 2.1.283 form, 2. Not now on the 2.1.289 list, the return
-only after a second look), refuses any other screen, and checks that it went. Its
-rule is `Bash(<kit> temp answer:*)`, `<kit>` the kit's CLI path as the
-command prints it; ask the user before `obk bot change --allow` adds it.
+only after a second look), refuses any other screen, and checks that it went. The kit's
+default set allows it, as it allows `obk temp trust-hooks`.
+
+A long-lived session's two screens go through the kit too: Codex's hooks
+review with `obk session trust-hooks --bots <bots> --bot <bot> --session
+<session>`, and Claude Code's `Teach auto mode` screen with `obk session
+answer --bots <bots> --bot <bot> --session <session>`. A long-lived session is
+Bot Father's: the caller is a Bot Father session or the user, from outside the
+fleet's tabs, and a session of any other bot is refused. They make the same
+checks as the temp commands. Before either trust-hooks command trusts hooks,
+it checks that the hooks on the review are the kit's own: the bot's
+`.codex/hooks.json` holds only the kit's, and the count on the screen is the
+number of the kit's hooks Codex does not trust yet. A refusal says what it
+saw; then type nothing and take it to the user. The keys in the table are for
+the screens the kit does not answer.
 
 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/book.js

@@ -28,6 +28,9 @@ const HEADER = `# What Orca calls this bot on this machine, and where each of it
 # \`rules\` is a stamp of the bot's AGENTS.md as the session last read it, so a
 # change to it after the session started can be told apart.
 #
+# \`launched_with\` is the extra arguments the kit typed on the session's last
+# launch line, as bot.yaml's extra_args gave them then.
+#
 # \`retired\` holds what the book knew about each session \`obk retire\` took off
 # the bot, with when, so the conversations it had are still accounted for.
 #

package/src/bot.js

@@ -11,7 +11,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSy
 import os from 'node:os';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { parse, parseDocument, stringify } from 'yaml';
+import { isSeq, parse, parseDocument, stringify } from 'yaml';
 
 import { DEFAULT_APPROVAL, HARNESSES, harnessOf, sessionTrouble } from './launch.js';
 
@@ -161,6 +161,9 @@ export function readBot(home, name = path.basename(home)) {
     allow: bot.allow,
     // 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).
+    ...(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 } : {}),
     sessions: sessions.map((session) => {
@@ -278,10 +281,10 @@ export function changeBot(bots, bot, { charter }) {
 /**
  * The bot's `allow` list as it is, after refusing what `allowRules` or
  * `disallowRules` 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.
+ * not a list of rules. Asked before anything is written, so a refused
+ * `permission allow` or `permission disallow` changes nothing.
  */
-export function allowedNow(bots, bot, rules, flag = '--allow') {
+export function allowedNow(bots, bot, rules, flag = '--rule') {
   if (rules.some((rule) => rule.trim() === '')) {
     throw new Error(`${flag} is empty. Give it the exact permission rule the user said yes to, such as Bash(git add:*).`);
   }
@@ -320,7 +323,7 @@ export function allowRules(bots, bot, rules, { write = true } = {}) {
  * false it only refuses what the edit would refuse, and writes nothing.
  */
 export function disallowRules(bots, bot, rules, { write = true } = {}) {
-  const { home, was } = allowedNow(bots, bot, rules, '--disallow');
+  const { home, was } = allowedNow(bots, bot, rules);
   const disallowed = [...new Set(rules)];
   const allow = was.filter((rule) => !disallowed.includes(rule));
   editBot(bots, bot, `take back ${disallowed.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
@@ -357,6 +360,58 @@ export function changeSession(bots, bot, name, settings) {
   return { bot, home, session };
 }
 
+/**
+ * Record the widest approval the bot's temporary sessions may be made at,
+ * `level`, as `temp_approval` (ADR 0037). 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 }));
+  return { bot, home: botDir(bots, bot), level };
+}
+
+/**
+ * Set the caps of roles in the bot's `temp_roles`: `caps` is a list of
+ * `[role, cap]`, a cap of undefined taking it off. A role written as a list of
+ * options becomes a mapping that holds that list as `options` beside its cap.
+ * A role the bot does not have is refused before anything is written. Returns
+ * { bot, home, caps }. With `write` false it only refuses what the edit would
+ * refuse, and writes nothing.
+ */
+export function setRoleCaps(bots, bot, caps, { write = true } = {}) {
+  const home = existingBot(bots, bot);
+  const roles = readBot(home, bot).temp_roles;
+  const file = path.join(home, BOT_YAML);
+  for (const [role] of caps) {
+    if (roles === null || typeof roles !== 'object' || Array.isArray(roles) || !Object.hasOwn(roles, role)) {
+      const has = roles !== null && typeof roles === 'object' && !Array.isArray(roles) ? Object.keys(roles) : [];
+      throw new Error(`${bot} has no temporary-session role called ${role} in ${file}${has.length === 0 ? ', and no temp_roles at all' : `. It has: ${has.join(', ')}`}. Nothing was changed.`);
+    }
+  }
+  const capped = (written, cap) => {
+    const { cap: was, ...rest } = Array.isArray(written) ? { options: written } : written;
+    return cap === undefined ? rest : { ...rest, cap };
+  };
+  editBot(bots, bot, `set the caps of ${caps.map(([role]) => role).join(', ')}`, (doc) => {
+    for (const [role, cap] of caps) {
+      const node = doc.getIn(['temp_roles', role], true);
+      if (isSeq(node)) {
+        doc.setIn(['temp_roles', role], doc.createNode(capped(node.toJSON(), cap)));
+      } else if (cap === undefined) {
+        doc.deleteIn(['temp_roles', role, 'cap']);
+      } else {
+        doc.setIn(['temp_roles', role, 'cap'], cap);
+      }
+    }
+  }, (was) => ({
+    ...was,
+    temp_roles: Object.fromEntries(Object.entries(was.temp_roles).map(([role, written]) => {
+      const asked = caps.findLast(([one]) => one === role);
+      return [role, asked === undefined ? written : capped(written, asked[1])];
+    })),
+  }), write);
+  return { bot, home, caps };
+}
+
 /**
  * Mark the bot `bot`, or its session `name`, paused or not. Returns whether
  * the file changed. A paused bot or session is one `obk up` leaves closed.
@@ -497,7 +552,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', 'temp_roles'];
+const BOT_FIELDS = ['name', 'harness', 'charter', 'rules', 'skills', 'allow', 'sessions', 'paused', 'temp_roles', 'temp_approval'];
 
 /**
  * The keys in a bot's file that the kit does not know, and so that nothing