@runtypelabs/cli 2.0.1 → 2.1.0

package/README.md

@@ -220,15 +220,44 @@ EOF
 - `planWritten` — advances when the agent writes its plan artifact
 - `never` — only the agent's `TASK_COMPLETE` signal can advance (if `canAcceptCompletion: true`)
 
+**Playbook policies**:
+
+The optional `policy` block lets you restrict what the agent can do at runtime. Policies are additive restrictions — they can only narrow behavior, never override global safety denies (e.g. `.env` files and private keys are always blocked).
+
+```yaml
+name: blog-writer
+policy:
+  allowedReadGlobs: ['content/**', 'templates/**']
+  allowedWriteGlobs: ['content/**']
+  blockedTools: ['search_repo']
+  blockDiscoveryTools: true
+  requirePlanBeforeWrite: true
+  requireVerification: true
+  outputRoot: 'content/'
+milestones:
+  - ...
+```
+
+| Field                    | Type       | Description                                                                                                                   |
+| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `allowedReadGlobs`       | `string[]` | Glob patterns for allowed read paths. If set, reads outside these are blocked.                                                |
+| `allowedWriteGlobs`      | `string[]` | Glob patterns for allowed write paths. If set, writes outside these are blocked. The plan file is always writable regardless. |
+| `blockedTools`           | `string[]` | Tool names to block entirely (e.g. `["write_file", "search_repo"]`).                                                          |
+| `blockDiscoveryTools`    | `boolean`  | Block `search_repo`, `glob_files`, `tree_directory`, and `list_directory`.                                                    |
+| `requirePlanBeforeWrite` | `boolean`  | Require the agent to write its plan before any other file writes.                                                             |
+| `requireVerification`    | `boolean`  | Require verification before `TASK_COMPLETE`.                                                                                  |
+| `outputRoot`             | `string`   | For creation tasks: confine writes to this directory (e.g. `"public/"`).                                                      |
+
 #### Marathon Anatomy
 
 ```
 ┌─ marathon ──────────────────────────────────────────────────────┐
 │                                                                 │
-│  ┌─ playbook (optional) ─────────────────────────────┐          │
-│  │  Defines milestones, models, verification, rules  │          │
-│  │  .runtype/marathons/playbooks/tdd.yaml            │          │
-│  └───────────────────────────────────────────────────┘          │
+│  ┌─ playbook (optional) ──────────────────────────────────┐     │
+│  │  Defines milestones, models, verification, rules,     │     │
+│  │  and policy constraints                               │     │
+│  │  .runtype/marathons/playbooks/tdd.yaml                │     │
+│  └────────────────────────────────────────────────────────┘     │
 │           │                                                     │
 │           ▼                                                     │
 │  ┌─ milestone 1 ──┐  ┌─ milestone 2 ──┐  ┌─ milestone 3 ─────┐  |
@@ -261,8 +290,55 @@ What's optional:
   ✓ Rules       Without them, agent follows only playbook/milestone instructions
   ✓ Models      Without overrides, uses CLI --model flag or default
   ✓ Verification Without it, no verification gate between milestones
+  ✓ Policy      Without one, only global safety denies apply
+```
+
+#### Reasoning / Thinking
+
+Marathon enables model reasoning by default for models that support it (Gemini 3, o-series, GPT-5, etc.). When active, the model's thinking process streams to the TUI in real time. To disable:
+
+```bash
+runtype marathon "Code Builder" --goal "Fix the bug" --no-reasoning
+```
+
+#### Fallback Models
+
+When an upstream model provider returns a transient error (e.g. overload, rate limit), marathon can automatically retry and then fall back to a different model instead of dying mid-run.
+
+**CLI flag** — applies to all phases:
+
+```bash
+# If claude-opus-4-6 fails, retry once then fall back to claude-sonnet-4-5
+runtype marathon "Code Builder" --goal "Refactor auth" \
+  --model claude-opus-4-6 \
+  --fallback-model claude-sonnet-4-5
+```
+
+**Playbook** — per-milestone fallback chains:
+
+```yaml
+milestones:
+  - name: research
+    model: claude-sonnet-4-5
+    fallbackModels:
+      - gpt-4o # string shorthand
+      - gemini-3-flash
+    instructions: |
+      Research the codebase...
+
+  - name: execution
+    model: claude-opus-4-6
+    fallbackModels:
+      - model: claude-sonnet-4-5 # object form with overrides
+        temperature: 0.5
+      - model: gpt-4o
+        maxTokens: 8192
+    instructions: |
+      Implement the changes...
 ```
 
+Playbook per-milestone fallbacks take priority over the CLI `--fallback-model` flag. The fallback chain always starts with a retry (5s delay) before trying alternative models.
+
 #### Tool Context Modes
 
 When a marathon runs multiple sessions, tool call/result pairs from previous sessions are preserved in the conversation history. The `--tool-context` flag controls how older tool results are stored to balance cost and re-readability: