@assuredloop/orca-bot-kit 0.25.6 → 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]

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,17 +238,16 @@ 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>`.

package/package.json

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

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

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