@nanocollective/roster 0.1.0-alpha.3 → 0.1.0-alpha.31

package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml

@@ -30,24 +30,35 @@ concurrency:
 
 jobs:
   answer:
-    # Only the human, only on a real mention. A bot quoting the phrase must never wake the loop.
+    # Only a human this org answers to, only on a real mention. A bot quoting the phrase must
+    # never wake the loop.
+    #
+    # The list is every login in `org.yaml`'s `humans:` (or the singular `human:`), so a second
+    # founder can wake a staff member without their comment being dropped in silence. One human
+    # is a one-element list: the gate has a single shape whatever the org looks like.
     #
     # The outer gate is on `sender` — the account that performed the action — and not on the author
     # of the thing it acted on. That distinction is load-bearing on the `issues` route: the pinned
-    # status issue is opened by the human and then edited by this staff member on every run, so an
+    # status issue is opened by a human and then edited by this staff member on every run, so an
     # author check would let the agent's own edit wake another run, which would edit it again.
     #
     # One spelling of the mention is enough: GitHub's `contains` is documented as not case
     # sensitive, so this already matches an uppercase mention at the start of a sentence.
     if: >-
-      github.event.sender.login == '%%HUMAN%%' &&
+      contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.sender.login) &&
       (
         (github.event_name == 'issue_comment' &&
-         github.event.comment.user.login == '%%HUMAN%%' &&
+         contains(fromJSON('%%HUMAN_LOGINS%%'), github.event.comment.user.login) &&
          contains(github.event.comment.body, '%%MENTION%%')) ||
         (github.event_name == 'issues' &&
          contains(github.event.issue.body, '%%MENTION%%'))
       )
+    # The ceiling on what session.yaml's job token may do: reading the checkout, and the one
+    # comment that says a run failed when the App that would normally say so is what broke.
+    # A called workflow cannot raise these, so they have to be granted here.
+    permissions:
+      contents: read
+      issues: write
     uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
     with:
       staff: %%STAFF%%
@@ -55,6 +66,7 @@ jobs:
       ops_repo: %%OPS_REPO%%
       model: %%MODEL%%
       timeout_minutes: %%MENTION_TIMEOUT%%
+      allowed_tools: "%%ALLOWED_TOOLS%%"
       issue_number: ${{ github.event.issue.number }}
       comment_id: ${{ github.event.comment.id }}
     secrets:

package/templates/brain/CHARTER.md

@@ -11,10 +11,10 @@ between %%MENTION%% and everyone else.
 Write it before the first unattended run. A generated charter would produce a generic agent,
 which is the failure this whole arrangement exists to avoid.
 
-Write it with your own AI:
+Write it with your own AI. This prints a brief to paste into whichever agent you use (in
+Claude Code it is also /charter, from inside this repo):
 
-    cd %%DIR%% && claude
-    /charter
+    roster brief charter %%STAFF%%
 
 Or write it by hand. The headings below are the shape that has worked; the words are yours.
 

package/templates/brain/README.md

@@ -10,6 +10,7 @@ on, and has decided.
 | `memory/INDEX.md` | One line per fact, read at every boot. |
 | `memory/notes/` | The argument behind a fact, read on demand. |
 | `log/decisions.md` | Why things were decided. Not boot context. |
+| `strategy/` | Longer role documents, and `ideas.md`: ideas parked here rather than filed as issues. |
 | `.github/workflows/` | Three callers. The body lives in `%%OPS_REPO%%`. |
 
 Scheduled runs and mentions are wired up by roster. To see what this staff member is actually

package/templates/brain/log/decisions.md

@@ -4,3 +4,6 @@ Why things were decided, newest first. Not boot context: this is read when a dec
 being revisited, not every morning.
 
 One entry per decision. What was decided, why, and what would change it back.
+
+This file holds the current month. Move anything older into `log/decisions/<YYYY-MM>.md`:
+`roster lint` warns past 24KB.

package/templates/brain/staff.yaml

@@ -13,7 +13,6 @@ schedule: "%%SCHEDULE%%"
 model: %%MODEL%%
 timeout_minutes: %%TIMEOUT%%
 mention_timeout_minutes: %%MENTION_TIMEOUT%%
-pr_mention_timeout_minutes: %%PR_MENTION_TIMEOUT%%
 
 bot: %%APP%%[bot]
 public_bot: %%PUBLIC_APP%%[bot]

package/templates/brain/strategy/ideas.md

@@ -0,0 +1,7 @@
+# Ideas
+
+Speculative ideas, one line each, parked here rather than filed as issues. An issue is for
+something that needs a ruling; an idea that does not yet is noise on the tracker.
+
+Promote one to an issue when it serves a priority in `org/priorities.md` and needs a ruling.
+Delete one when it stops being interesting.

package/templates/briefs/priorities.md

@@ -0,0 +1,46 @@
+Write `org/priorities.md` for %%ORG_NAME%%.
+
+You are helping %%HUMAN%% decide what their AI staff should work on this month. Every staff
+member reads this file at the start of every run and picks work that serves it, so a vague
+priority produces scattered work.
+
+## Where you are
+
+- `%%OPS_REPO_DIR%%/org/business.md`: what the business is. **Read it first**, and don't ask
+  anything it already answers.
+- `%%OPS_REPO_DIR%%/org/priorities.md`: the current file, which you are replacing.
+
+If you cannot read files where you are running, ask %%HUMAN%% to paste `org/business.md`.
+
+## Interview
+
+Ask one question at a time. You are after:
+
+- **The one outcome that matters most this month**, and how they will know it happened.
+- **At most two more**, in order. Push back on a fourth: past three it is a wish list.
+- **What is out of scope this month**: work that is tempting but not now. Naming it is what
+  stops the staff doing it.
+
+Prefer outcomes ("a stranger pays for it") to activities ("improve the landing page"). If an
+answer is an activity, ask what it is for.
+
+## Write it
+
+Use exactly this shape:
+
+```
+## What matters this month
+
+### Priorities, in order
+
+1. The first outcome, and how you will know it happened.
+2. The second.
+3. The third.
+
+### Out of scope this month
+
+- One thing per line.
+```
+
+Keep each priority to a sentence or two. Don't add anything %%HUMAN%% didn't say without
+listing it after the file so they can check it.

package/templates/ops/.github/workflows/session.yaml

@@ -15,7 +15,7 @@ on:
         required: true
         type: string
       kind:
-        description: "daily | mention | pr-mention"
+        description: "daily | mention"
         required: false
         default: daily
         type: string
@@ -25,17 +25,17 @@ on:
         type: string
       model:
         required: false
-        default: claude-opus-5
+        default: claude-opus-5-5
         type: string
       timeout_minutes:
         required: false
-        default: 60
+        default: 90
         type: number
       allowed_tools:
         required: false
         default: "Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch"
         type: string
-      # Trigger context. Empty on a scheduled run; set when a comment or a PR woke us.
+      # Trigger context. Empty on a scheduled run; set when a comment woke us.
       issue_number:
         required: false
         default: ""
@@ -44,10 +44,6 @@ on:
         required: false
         default: ""
         type: string
-      pr_number:
-        required: false
-        default: ""
-        type: string
     secrets:
       APP_ID:
         required: true
@@ -73,11 +69,22 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: ${{ inputs.timeout_minutes }}
 
+    # `issues: write` is for the failure notice alone, which falls back to this job's own token
+    # when the App's cannot be minted. A called workflow cannot raise what its caller granted, so
+    # the callers ask for the same.
+    permissions:
+      contents: read
+      issues: write
+
     # secrets are not usable in a step-level `if`, so the presence check is hoisted here.
     env:
       HAS_PUBLIC_APP: ${{ secrets.PUBLIC_APP_ID != '' }}
 
     steps:
+      # For the run record at the end. A job has no start time of its own to read back.
+      - name: Start the clock
+        run: echo "ROSTER_STARTED=$(date +%s)" >> "$GITHUB_ENV"
+
       - name: Mint the private-tracker token
         id: private
         uses: actions/create-github-app-token@v2
@@ -102,9 +109,7 @@ jobs:
       # missed". It sits here, before any checkout, so the eyes land in seconds rather than after
       # the clones.
       #
-      # `mention` only. A pr-mention is already acknowledged by the forwarder in the public product
-      # repo, on the comment the human actually left, and reacting again here would put two on it.
-      # A daily run has nothing to react to.
+      # `mention` only: a daily run has nothing to react to.
       #
       # An `issues` payload carries no comment, so the eyes go on the issue itself. That is the
       # route where a mention is typed straight into the body of a new issue.
@@ -167,6 +172,36 @@ jobs:
             echo "product: $repo -> $dir"
           done
 
+      # What people have open on the product repos, so the agent does not open competing work
+      # on files a human branch is rewriting. Read by "Compose the prompt" below; never
+      # fatal, because without it the prompt just has no section about it.
+      - name: Gather human work in flight
+        if: steps.plan.outputs.products != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ steps.public.outputs.token || steps.private.outputs.token }}
+        run: node roster-ops/inflight.mjs --staff "${{ inputs.staff }}" --ops roster-ops --brains . --out .roster-run/inflight.md
+
+      # staff.yaml names the variable its prompts use for the public token (`public_token_env`),
+      # and an `env:` key cannot be an expression, so the name is exported here for every later
+      # step. PUBLIC_TOKEN is always set as well; this only adds the name the manifest chose.
+      - name: Export the public token under its manifest name
+        if: steps.public.outputs.token != ''
+        env:
+          BRAIN_DIR: ${{ steps.plan.outputs.brain_dir }}
+          TOKEN: ${{ steps.public.outputs.token }}
+        run: |
+          set -euo pipefail
+          name=$(sed -n 's/^public_token_env:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1 | tr -d "\"' ")
+          case "$name" in
+            ""|PUBLIC_TOKEN|GH_TOKEN|GITHUB_TOKEN) exit 0 ;;
+          esac
+          if ! [[ "$name" =~ ^[A-Z_][A-Z0-9_]*$ ]]; then
+            echo "::warning::public_token_env '$name' is not a variable name; only PUBLIC_TOKEN is set"
+            exit 0
+          fi
+          echo "$name=$TOKEN" >> "$GITHUB_ENV"
+
       # Commits read as the bot, not as a human, so the git history stays legible.
       - name: Set git identity
         env:
@@ -191,20 +226,6 @@ jobs:
             [ -d "$dir" ] && identify "$dir" "${PUBLIC_SLUG:-$PRIVATE_SLUG}"
           done
 
-      # A PR request is answered on the PR's own branch, never on a new one.
-      - name: Check out the PR branch
-        if: inputs.pr_number != ''
-        env:
-          GH_TOKEN: ${{ steps.public.outputs.token || steps.private.outputs.token }}
-          PRODUCT_DIR: ${{ steps.plan.outputs.product_dir }}
-          PRODUCT_REPO: ${{ steps.plan.outputs.product_repo }}
-        run: |
-          set -euo pipefail
-          [ -n "$PRODUCT_DIR" ] || { echo "no product repo to check a PR out of"; exit 1; }
-          cd "$PRODUCT_DIR"
-          gh pr checkout "${{ inputs.pr_number }}" --repo "$PRODUCT_REPO"
-          echo "on $(git branch --show-current)"
-
       - uses: pnpm/action-setup@v6
         if: steps.plan.outputs.needs_node == 'true'
         with:
@@ -226,7 +247,6 @@ jobs:
           ROSTER_CONTEXT: >-
             {"issue_number":"${{ inputs.issue_number }}",
              "comment_id":"${{ inputs.comment_id }}",
-             "pr_number":"${{ inputs.pr_number }}",
              "repo":"${{ github.repository }}",
              "actor":"${{ github.actor }}"}
         run: |
@@ -257,13 +277,12 @@ jobs:
       # `uses:` cannot be an expression, so an Action-based runner has to be written out
       # literally. This is the reference one; every other agent goes through the step below.
       - name: Run the session
+        id: session_action
         if: steps.agent.outputs.kind == 'action'
         uses: anthropics/claude-code-action@v1
         env:
           GH_TOKEN: ${{ steps.private.outputs.token }}
           PUBLIC_TOKEN: ${{ steps.public.outputs.token }}
-          # Kept as an alias while charters and memory still name it. Retire once they do not.
-          PIPWEB_TOKEN: ${{ steps.public.outputs.token }}
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN || secrets.AGENT_TOKEN }}
           # These repos are private and single-user, so the usual reason to hide a run's output does
@@ -274,21 +293,25 @@ jobs:
           # No --max-turns. A run that legitimately needs more turns should get them: capping it
           # fails the action *after* the work is done and committed, which is a false red rather
           # than a saved penny. timeout-minutes is the real bound.
+          # The permission flags come from agents.mjs, which is the only thing that knows
+          # which agent is running and therefore how to say "may write" to it.
           claude_args: >-
             --model ${{ inputs.model }}
-            --allowedTools "${{ inputs.allowed_tools }}"
+            ${{ steps.agent.outputs.flags }}
           prompt: ${{ steps.compose.outputs.text }}
 
       # Any agent with a command line. The prompt is handed over as a file, never as an
       # argument: it is thousands of words containing quotes and backticks, and argv limits and
       # shell quoting fail at 07:00 rather than in review.
       - name: Run the session
+        id: session_cli
         if: steps.agent.outputs.kind == 'cli'
         env:
           GH_TOKEN: ${{ steps.private.outputs.token }}
           PUBLIC_TOKEN: ${{ steps.public.outputs.token }}
-          PIPWEB_TOKEN: ${{ steps.public.outputs.token }}
           AGENT_MODEL: ${{ steps.agent.outputs.model || inputs.model }}
+          AGENT_FLAGS: ${{ steps.agent.outputs.flags }}
+          # Kept for a custom `run` written before permissions existed.
           AGENT_TOOLS: ${{ inputs.allowed_tools }}
           AGENT_TOKEN: ${{ secrets.AGENT_TOKEN }}
           FALLBACK_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
@@ -306,6 +329,10 @@ jobs:
           # an `env:` key cannot be an expression.
           export "$TOKEN_ENV=$TOKEN"
           export AGENT_PROMPT_FILE="$PWD/.roster-prompt.txt"
+          # Where an agent that can report its own turns and cost writes them. Optional: the
+          # run record reads it if it is there and records what it cannot know as unknown.
+          mkdir -p .roster-run
+          export AGENT_RESULT_FILE="$PWD/.roster-run/agent-result.json"
 
           if [ -n "$INSTALL" ]; then
             echo "::group::install ${{ steps.agent.outputs.id }}"
@@ -314,20 +341,70 @@ jobs:
           fi
           eval "$RUN"
 
-      # A failed unattended run is otherwise a red X in a tab nobody opens. New in the roster
-      # migration, and deliberate: every failure path should end somewhere a human reads.
+      # What this run was and what it cost, in the job summary and as an artifact with a stable
+      # name, which is what the portal's Runs screen and `roster doctor` read back. Never fatal:
+      # a missing record costs a row in a table, and failing the job over it would cost the run.
+      - name: Write down the run
+        if: always()
+        continue-on-error: true
+        env:
+          STAFF: ${{ inputs.staff }}
+          KIND: ${{ inputs.kind }}
+          AGENT_ID: ${{ steps.agent.outputs.id }}
+          MODEL: ${{ steps.agent.outputs.model || inputs.model }}
+          AGENT_OUTCOME: ${{ steps.session_action.outcome != 'skipped' && steps.session_action.outcome || steps.session_cli.outcome }}
+          JOB_STATUS: ${{ job.status }}
+          RESULT_FILE: ${{ steps.session_action.outputs.execution_file || format('{0}/.roster-run/agent-result.json', github.workspace) }}
+        run: node roster-ops/run-record.mjs --out .roster-run/run.json
+
+      - name: Keep the run record
+        if: always()
+        continue-on-error: true
+        uses: actions/upload-artifact@v6
+        with:
+          name: roster-run
+          path: .roster-run/run.json
+          if-no-files-found: ignore
+
+      # A failed unattended run is otherwise a red X in a tab nobody opens, so every failure path
+      # has to end somewhere a human reads.
+      #
+      # It cannot lean on anything that might be what failed. The App token is the first thing a
+      # renamed repo, a rotated key or an uninstalled App breaks, and a canary sat red for twelve
+      # days because its alert used exactly that token. So: the App token when there is one, and
+      # this job's own token when there is not or it is refused. The plan may not have run
+      # either, so the brain repo falls back to the caller's, which is the same repo, and
+      # staff.yaml is read over the API when it was never checked out.
       - name: Say so if the run did not finish
         if: failure() || cancelled()
         env:
-          GH_TOKEN: ${{ steps.private.outputs.token }}
+          APP_TOKEN: ${{ steps.private.outputs.token }}
+          JOB_TOKEN: ${{ github.token }}
           BRAIN_DIR: ${{ steps.plan.outputs.brain_dir }}
-          BRAIN_REPO: ${{ steps.plan.outputs.brain_repo }}
+          BRAIN_REPO: ${{ steps.plan.outputs.brain_repo || github.repository }}
+          ISSUE: ${{ inputs.issue_number }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
         run: |
-          set -euo pipefail
-          issue="${{ inputs.issue_number }}"
+          set -uo pipefail
+          issue="$ISSUE"
+          if [ -z "$issue" ] && [ -n "$BRAIN_DIR" ] && [ -f "$BRAIN_DIR/staff.yaml" ]; then
+            issue=$(sed -n 's/^status_issue:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1)
+          fi
+          if [ -z "$issue" ]; then
+            issue=$(GH_TOKEN="${APP_TOKEN:-$JOB_TOKEN}" gh api "repos/$BRAIN_REPO/contents/staff.yaml" \
+              -H "Accept: application/vnd.github.raw" 2>/dev/null \
+              | sed -n 's/^status_issue:[[:space:]]*//p' | head -1)
+          fi
+          issue="${issue%%[[:space:]#]*}"
           if [ -z "$issue" ]; then
-            issue=$(sed -n 's/^status_issue:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1 || true)
+            echo "::error::no status_issue in staff.yaml and no issue in the trigger, so nobody was told"
+            exit 1
+          fi
+
+          body="This run did not finish, so there is no answer coming. [Run ${GITHUB_RUN_ID}]($RUN_URL) has the error."
+          if [ -n "$APP_TOKEN" ] && GH_TOKEN="$APP_TOKEN" gh issue comment "$issue" --repo "$BRAIN_REPO" --body "$body"; then
+            exit 0
           fi
-          [ -n "$issue" ] || { echo "no status_issue in staff.yaml; nothing to comment on"; exit 0; }
-          gh issue comment "$issue" --repo "$BRAIN_REPO" --body \
-            "This run did not finish, so there is no answer coming. [Run ${{ github.run_id }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) has the error."
+          # Posted as github-actions rather than as the staff member, which is itself the clue.
+          GH_TOKEN="$JOB_TOKEN" gh issue comment "$issue" --repo "$BRAIN_REPO" --body \
+            "$body The staff member's own App could not post it, so check the App is installed on this repo and its APP_ID and APP_PRIVATE_KEY secrets are current."

package/templates/ops/agents.mjs

@@ -24,22 +24,43 @@ import { parseYaml } from "./compose.mjs";
  * `uses:` cannot be an expression. Only the reference Claude runner is one of these.
  * `cli` is everything else: install a package, run a command. That path is open-ended.
  */
+/* Claude says what an agent may do as a list of its own tool names. The three levels are the
+   same list narrowed: everything, everything but the network, and nothing that writes. */
+const CLAUDE_TOOLS = {
+  full: '--allowedTools "Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch"',
+  workspace: '--allowedTools "Bash,Read,Write,Edit,Glob,Grep"',
+  "read-only": '--allowedTools "Read,Glob,Grep,WebFetch,WebSearch"',
+};
+
+/** Single quotes, because every one of these ends up inside `eval` in the session. */
+function shellArg(v) {
+  return `'${String(v).replace(/'/g, "'\\''")}'`;
+}
+
 export const PRESETS = {
   // The reference runner, and the default. Uses Anthropic's own action, which handles tool
   // permissions and output for us.
   "claude-code-action": {
     kind: "action",
     token_env: "CLAUDE_CODE_OAUTH_TOKEN",
-    model: "claude-opus-5",
+    model: "claude-opus-5-5",
+    permissions: CLAUDE_TOOLS,
+    option: (k, v) => `--${k} ${shellArg(v)}`,
   },
 
   // The same agent through its plain CLI, for anyone who would rather not depend on the action.
   claude: {
     kind: "cli",
     install: "npm install -g @anthropic-ai/claude-code",
-    run: 'claude -p --model "$AGENT_MODEL" --allowedTools "$AGENT_TOOLS" < "$AGENT_PROMPT_FILE"',
+    // JSON rather than text so the run record can read turns and cost off it. The log still
+    // carries the answer, inside the `result` field.
+    run:
+      'claude -p --model "$AGENT_MODEL" $AGENT_FLAGS --output-format json < "$AGENT_PROMPT_FILE"' +
+      ' | tee "$AGENT_RESULT_FILE"',
     token_env: "CLAUDE_CODE_OAUTH_TOKEN",
-    model: "claude-opus-5",
+    model: "claude-opus-5-5",
+    permissions: CLAUDE_TOOLS,
+    option: (k, v) => `--${k} ${shellArg(v)}`,
   },
 
   codex: {
@@ -47,20 +68,66 @@ export const PRESETS = {
     install: "npm install -g @openai/codex",
     // `exec -` reads the prompt from stdin. The sandbox has to be opened up because the whole
     // point of a session is that it edits the checkout and pushes.
-    run: 'codex exec - --model "$AGENT_MODEL" --sandbox danger-full-access < "$AGENT_PROMPT_FILE"',
+    run: 'codex exec - --model "$AGENT_MODEL" $AGENT_FLAGS < "$AGENT_PROMPT_FILE"',
     token_env: "CODEX_API_KEY",
     model: "gpt-5-codex",
+    /* Codex spells freedom as a sandbox plus an approval policy, and both have to be said:
+       a sandbox that allows writes still stops to ask by default, and a run that stops to ask
+       at 07:00 is a run that times out having done nothing. */
+    permissions: {
+      full: '--sandbox danger-full-access -c approval_policy="never"',
+      workspace: '--sandbox workspace-write -c approval_policy="never"',
+      "read-only": '--sandbox read-only -c approval_policy="never"',
+    },
+    // `-c key=value` is its highest-precedence override, so anything else goes through it.
+    option: (k, v) => `-c ${k}=${shellArg(JSON.stringify(v))}`,
   },
 
   nanocoder: {
     kind: "cli",
     install: "npm install -g @nanocollective/nanocoder",
-    // `run` is its non-interactive mode; --trust-directory skips the first-run prompt that
-    // would otherwise hang a runner, and --plain avoids the TUI. The prompt is an argument
-    // here rather than stdin, so it is read out of the file.
-    run: 'nanocoder --model "$AGENT_MODEL" --mode yolo --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"',
+    /* `run` is its non-interactive mode; --trust-directory skips the first-run prompt that
+       would otherwise hang a runner, and --plain avoids the TUI. The prompt is an argument
+       here rather than stdin, so it is read out of the file.
+
+       NANOCODER_PROVIDERS_FILE is the part that makes it work unattended. Nanocoder is a
+       client, not a model: it reads its providers from `agents.config.json` found in the
+       working directory. In a session that directory is the workspace root — the place the
+       repos are checked out *into* — which belongs to no repo, so a committed config would
+       never be found. Pointing at the ops repo's copy gives every staff member the same
+       providers from a file that is version controlled. A missing file is ignored, so this is
+       safe when somebody has configured it another way. */
+    run:
+      'NANOCODER_PROVIDERS_FILE="${NANOCODER_PROVIDERS_FILE:-roster-ops/agents.config.json}" ' +
+      'nanocoder --model "$AGENT_MODEL" $AGENT_FLAGS --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"',
     token_env: "NANOCODER_API_KEY",
     model: "",
+    /* Its development modes. `plan` is genuinely read-only: it reasons and proposes and edits
+       nothing, which is the right answer for a staff member you are not ready to trust yet. */
+    permissions: {
+      full: "--mode yolo",
+      workspace: "--mode auto-accept",
+      "read-only": "--mode plan",
+    },
+    option: (k, v) => `--${k} ${shellArg(v)}`,
+    /* A client rather than a model, so it cannot run until it has been told whose model to
+       call. Written on init and reported by doctor when it is missing, because the failure
+       without it is a run that installs, starts, finds no provider and exits. */
+    config: {
+      path: "agents.config.json",
+      contents: {
+        nanocoder: {
+          providers: [
+            {
+              name: "openrouter",
+              baseUrl: "https://openrouter.ai/api/v1",
+              apiKey: "${NANOCODER_API_KEY}",
+              models: ["FILL IN: a model this provider serves, and set it as `model` in org.yaml"],
+            },
+          ],
+        },
+      },
+    },
   },
 };
 
@@ -96,9 +163,60 @@ export function resolveAgent(org, staff = {}) {
     token_env: merged.token_env,
     // The staff member's own model wins; then the agent's default. Empty means "the agent's".
     model: staff.model ?? merged.model ?? "",
+    flags: flagsFor(merged, spec, org, staff),
+    config: merged.config ?? null,
   };
 }
 
+/** The three levels, in the order a person would climb them. */
+export const LEVELS = ["read-only", "workspace", "full"];
+
+/**
+ * What the agent is allowed to do, in its own words.
+ *
+ * org.yaml says `permissions: full` and every agent hears something different: Claude a list
+ * of tool names, Codex a sandbox and an approval policy, nanocoder a development mode. The
+ * translation lives here because it is the only place that knows which agent is running, and
+ * because the alternative is a config file written in one tool's vocabulary that quietly means
+ * nothing to the other two.
+ *
+ * `options` is the escape hatch, in that agent's own vocabulary, spelled onto its command line
+ * by the preset. Anything roster does not model is still reachable without waiting for us.
+ */
+function flagsFor(merged, spec, org, staff) {
+  const out = [];
+  const asked = staff.permissions ?? spec.permissions ?? org.permissions ?? "full";
+  if (!LEVELS.includes(asked)) {
+    throw new Error(`unknown permissions "${asked}". One of: ${LEVELS.join(", ")}`);
+  }
+
+  /* `allowed_tools` predates the levels and is Claude's own vocabulary, so it still wins for
+     an agent that takes a tool list. Nothing translates it for the others: a list written for
+     one tool is not a permission level for another, and guessing would be worse than saying so. */
+  const tools = staff.allowed_tools ?? org.defaults?.allowed_tools;
+  const table = merged.permissions;
+  if (tools && table === CLAUDE_TOOLS) {
+    const list = Array.isArray(tools) ? tools.join(",") : String(tools);
+    out.push(`--allowedTools "${list.replace(/\s+/g, "")}"`);
+  } else if (table) {
+    out.push(table[asked]);
+  }
+
+  const options = { ...(spec.options ?? {}), ...(staff.options ?? {}) };
+  const speller = merged.option;
+  for (const [k, v] of Object.entries(options)) {
+    if (v === undefined || v === null || v === "") continue;
+    if (!speller) {
+      throw new Error(
+        `agent "${merged.id ?? "custom"}" has options but no way to spell them.\n` +
+          "  A custom agent takes its options in its own `run` command.",
+      );
+    }
+    out.push(speller(k, v));
+  }
+  return out.filter(Boolean).join(" ");
+}
+
 function strip(o) {
   const out = {};
   for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== "") out[k] = v;
@@ -138,6 +256,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     `model=${agent.model}`,
     `install<<AGENT_EOF_9c1f\n${agent.install}\nAGENT_EOF_9c1f`,
     `run<<AGENT_EOF_9c1f\n${agent.run}\nAGENT_EOF_9c1f`,
+    `flags<<AGENT_EOF_9c1f\n${agent.flags}\nAGENT_EOF_9c1f`,
   ].join("\n");
   process.stdout.write(out + "\n");
 }