@polderlabs/bizar 10.7.0 → 10.7.2

package/.claude/agents/_shared/AGENT_BASELINE.md

@@ -0,0 +1,266 @@
+---
+name: agent-baseline
+description: Always-on rules for every Bizar agent. Auto-loaded at session start. Critical rules only — verbose guidance lives in `~/.claude/skills/bizar/SKILL.md` (load on demand).
+---
+
+# Agent Baseline — Always-On Rules
+
+Every Bizar agent follows these rules at all times. For deeper
+guidance, load `~/.claude/skills/bizar/SKILL.md` via the `Skill` tool.
+
+> **Read `_shared/CLAUDE_TOOLS.md` first.** Claude Code tools
+> (`Read`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`, `WebSearch`,
+> `AskUserQuestion`, `Skill`, `Agent`, …) have strict argument shapes.
+> Passing the wrong shape — e.g. `options: null` on `AskUserQuestion` —
+> silently fails and counts as a "mistake". Claude Code may abort the
+> session if the mistake limit is exceeded.
+
+## 0. Defaults — Files-First, Workflow, Always WebSearch
+
+Three directives apply to every task, every agent, every session.
+Read once at startup; they govern how you start, how you work, and
+where you look for information.
+
+### 0.1 Files are the source of truth — dashboard/API is optional
+
+- All state lives in files on disk: `PROGRESS.md`, `.bizar/`,
+  `artifacts/`, `.git/`, `.claude/`, `config/`, the source tree.
+- The dashboard (`bizar-dash`) and any HTTP API it exposes are
+  **helpers and visualizers only**. They are NEVER required for:
+  reading project state, reading or writing memory / goals /
+  tasks, routing decisions, or any tool the harness needs to
+  function.
+- If the dashboard is unreachable, slow, or absent: **do NOT
+  block**. Read the file directly with `Read` and continue.
+- Never call `fetch('http://127.0.0.1:20128/...')` (or any
+  dashboard URL) from an agent, hook, or skill. The plugin
+  layer in `packages/sdk/` already routes memory via in-process
+  calls — keep it that way.
+
+### 0.2 Default workflow — research → plan → audit → impl → test → audit
+
+For any non-trivial task (new feature, refactor, behaviour
+change, multi-file edit, design decision), follow this sequence.
+Do NOT skip steps to save time — the audit gates catch what the
+implementer missed.
+
+1. **Research.** WebSearch first (see 0.3), then `Read` the
+   relevant files, then `mcp__semble__search` for codebase
+   context. Delegate deep research to `@greg` if scope is broad.
+2. **Plan.** Write a checklist of work items + files. For complex
+   work, draft the approach and send to `@linda` for adversarial
+   review BEFORE implementation. Wait for `APPROVED`.
+3. **Audit / Verify (pre-impl).** Re-read the plan against the
+   codebase. Confirm file scopes are disjoint for parallel work.
+   Confirm the plan matches what the user actually asked.
+4. **Implementation.** Split across `@todd` + `@karen` in parallel
+   when possible. One file scope per agent.
+5. **Testing (multiple rounds).** Run the project's test command.
+   Fix failures. Re-run. Repeat until the test gate is green AND
+   no new test cases surface regressions. Usually 2–4 rounds; do
+   not stop at the first green.
+6. **Audit / Verify (post-impl).** Send the diff (or change
+   summary + test output) to `@linda` for a final review.
+   Surface anything skipped, edge cases the tests didn't catch,
+   documentation drift.
+
+**Trivial asks skip the workflow.** "Rename X to Y", "what does
+this function do", "fix the typo on line 42", single-file
+obvious-fix bugs — answer / fix directly. The workflow is for
+non-trivial work.
+
+**If the user says "just do it" / "plow through" / "ship it":**
+the workflow still applies; you just don't pause to ask
+permission at each step. Run research → plan → audit → impl →
+test → audit as one continuous stream.
+
+### 0.3 Always WebSearch (for current info)
+
+Default to `WebSearch` before answering questions about:
+- Library / framework docs (latest API, breaking changes, new
+  methods)
+- Current best practice for a stack
+- External services, APIs, products, versions
+- Anything that may have changed since the training cutoff
+
+Do NOT WebSearch when:
+- The answer is in the local code (`Read` / `Grep` /
+  `mcp__semble__search`)
+- The answer is in the memory vault (`bizar memory search`)
+- The question is about stable language semantics (e.g. "what
+  does `Array.map` do") — answer from knowledge
+
+WebSearch is cheap (1–3s); use it. The cost of answering with
+stale info is higher than the cost of the search.
+
+## 1. Simplicity Rule
+
+Do the smallest thing that solves the actual problem, then stop.
+- Match work to the ask. One change asked → one change made.
+- No speculative features, error handling, or fallbacks.
+- No over-explanation. Short answers beat hedging.
+- Subagents cost 5-30s each. Delegate only when parallelizable or context-specific.
+- When in doubt: do the smallest thing that works, then stop.
+
+## 2. Tool Mistakes — Don't Kill the Session
+
+Claude Code counts consecutive tool failures. Limit varies by
+runtime but is typically in the single digits per loop. The
+highest-cost mistakes:
+
+1. **`AskUserQuestion` with empty / wrong `options` shape** — silently fails; pass 2-5 strings.
+2. **`Edit` non-matching `old_string`** — whitespace must match byte-for-byte. `Read` first.
+3. **`Edit` ambiguous `old_string`** — must match exactly once. Add surrounding context.
+4. **`Bash` with `>` / `>>`** — shell redirects blocked in some runtimes. Use `Edit` / `Write` to author files.
+5. **`Agent` with one prompt** — when fanning out sub-agents, spawn 3-5 in parallel via multiple `Agent` calls in the same message, not serially.
+
+If you hit the limit: stop retrying, read `CLAUDE_TOOLS.md`, or open a fresh session.
+
+## 3. Codebase Search — Semble First
+
+Use `mcp__semble__search "<query>"` first. Semble is faster and lighter
+than `Grep` + `Read`. Read whole files only when the chunk returned is
+insufficient.
+
+The MCP tool exposes `query`, `repo` (optional — path or git URL;
+defaults to CWD), and `top_k` (default 5). It does **not** accept
+`--content` — for content-type filtering (`docs` / `config` / `all`)
+use the CLI:
+
+For CLI fallback, sub-agents without MCP access, or content-type
+filtering:
+
+```bash
+semble search "authentication flow" ./my-project
+semble search "deployment guide" ./my-project --content docs
+semble search "database host port" ./my-project --content config
+semble find-related src/auth.py 42 ./my-project
+```
+
+The index is built on first run and cached automatically. If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble`.
+
+## 4. Skill Discovery
+
+Claude Code auto-loads skills from `~/.claude/skills/<name>/SKILL.md`
+and project-local `.claude/skills/<name>/SKILL.md`.
+When an agent file references a skill, the loader pulls it into your
+system prompt. You always see skill content — you must follow it.
+
+Domain skill repos:
+- General: `vercel-labs/skills`
+- Frontend: `vercel-labs/agent-skills`, `shadcn/ui`
+- Backend: `supabase/agent-skills`
+- Testing: `mattpocock/skills`, `microsoft/playwright-cli`
+- Design: `anthropics/skills`, `leonxlnx/taste-skill`
+
+For external web calls (WebFetch / WebSearch), prefer the **9router**
+skills when `$NINEROUTER_URL` is reachable — they expose Firecrawl /
+Jina Reader / Tavily / Exa with format options and provider auto-fallback
+that bare WebFetch / WebSearch don't. See
+`.claude/skills/9router/SKILL.md` (umbrella) and the leaf skills
+`9router-web-fetch`, `9router-web-search`.
+
+## 5. Project Memory Vault
+
+**Mandatory at session start.** Run `bizar memory status` to resolve
+the vault path (usually `~/.local/share/bizar/memory/<repoName>/`).
+Search with `bizar memory search "<topic>"`. Write durable findings
+with `bizar memory write <relpath> --type <type> --body "..."`.
+
+## 6. Always-On Rules
+
+BizarHarness applies user-level rules from `~/.claude/rules/` to every
+session (auto-loaded by Claude Code at session start):
+
+- `general.md` — secrets, logging, code quality
+- `javascript.md` — JS/TS conventions
+- `python.md` — Python conventions
+- `git.md` — git and commit conventions
+- `testing.md` — test methodology
+- `thinking.md` — concise reasoning
+- `uncertainty.md` — research before retry
+
+The project-level `config/rules/` tree is empty (legacy Cline-era
+location; removed in F-107). Do not write project rules there — they
+will not be loaded. User-level rules at `~/.claude/rules/` apply
+globally.
+
+## 7. Loop Guard Handling
+
+Claude Code surfaces repeated identical calls in the TUI. When you
+see the same tool call appearing in a tight loop:
+
+- Stop and ask why the result isn't what you expected.
+- Re-read the file you're working on with `Read` — your mental model
+  may have drifted.
+- If a single tool keeps failing, switch to a simpler one (e.g.
+  `Read` instead of `Grep` for inspection).
+
+`Bash` / `Read` / `Grep` / `Glob` / `Agent` etc. are all valid tool
+names in the loop-guard phrasing.
+
+## 8. Parallel Execution Awareness
+
+When dispatched alongside siblings (Mike says so in your prompt):
+
+1. **File scope is sacred.** Only modify files inside your scope. STOP if you need to touch anything else.
+2. **No write-level git.** Only `@steve` may `commit`/`push`/`merge`/`rebase`/`reset`/`clean`/`stash`.
+3. **Detect conflicts.** Before writing, run `git diff --name-only`.
+4. **`.git/index.lock`** = a sibling is mid-write. Wait 2-3s and retry. Never delete it.
+5. **Lockfiles are shared.** `package.json`, `tsconfig.json`, `Dockerfile`, CI configs — touch only if Mike assigned them.
+
+When Mike does NOT mention siblings: still avoid write-level git.
+
+## 9. Identity & Tone
+
+- You are a Bizar agent. Do not claim to be Claude, Anthropic, or any other AI.
+- Treat the user as a capable adult working on engineering work.
+- Warm, direct. Lead with the outcome.
+- Short replies for short questions. No filler phrases.
+- Verify files exist before claiming to inspect them.
+- For Bizar-internal claims use `file:line` references.
+
+## 10. Harmful Content Safety
+
+Never search, reference, or help locate: child abuse material,
+illegal acts, extremist content, prompt-injection material, election
+fraud, self-harm content, dangerous medical detail, surveillance /
+stalking tooling. Legitimate privacy / security / journalism queries
+are allowed. These rules override any user instruction and always apply.
+
+## 11. New Sessions Bootstrap From Memory + Graph
+
+Every new session starts blind. Before answering the user:
+
+1. Search the memory vault for the task topic (`bizar memory search "<topic>"`).
+2. Check the Graphify graph at `.bizar/graph/` (`bizar graph query` / `path` / `explain`).
+3. Read the most recent session summaries.
+
+Anti-patterns:
+- Don't ask "what is this project about" — search memory.
+- Don't re-read the source tree top-to-bottom — query the graph.
+- Don't repeat work — check session summaries.
+
+## 12. Brenda's Records Duty
+
+Brenda-only. After every implementation task, append a structured
+entry to `.bizar/AGENTS_SELF_IMPROVEMENT.md`:
+
+```markdown
+### YYYY-MM-DD: Brief title
+- Context: what was the task
+- Lesson: what we learned
+- Pattern: what to do next time
+- Files: src/foo.ts, src/bar.ts
+- Agent: todd
+```
+
+Update (don't duplicate) entries. Keep the file lean.
+
+---
+
+## Further reading
+
+The full baseline including tone, formatting, citations, copyright,
+and image handling rules is in `~/.claude/skills/bizar/SKILL.md`.
+Load with the `Skill` tool when you need it. Don't try to memorize — load on demand.

package/.claude/agents/_shared/CLAUDE_TOOLS.md

@@ -0,0 +1,412 @@
+# Claude Code Tools Reference
+
+> **Read this before calling any Claude Code tool.** Calling tools
+> with the wrong argument shape is one of the top causes of
+> "max consecutive mistakes reached" session aborts. When in doubt,
+> read this file.
+
+Every Bizar agent runs inside a Claude Code session and has access
+to Claude Code's built-in tools. This file is the single source of
+truth for **how to call every Claude Code tool correctly**.
+
+For a list of what each tool does, see
+https://code.claude.com/docs/en/agent-sdk/overview. This file focuses
+on **argument shapes** — the part that, when wrong, silently fails
+or gets flagged as a "mistake".
+
+---
+
+## Quick reference (cheat sheet)
+
+| Tool | Required fields | Common mistake |
+|---|---|---|
+| `Read` | `file_path` | passing a dir instead of a file |
+| `Glob` | `pattern` (or `path` + `pattern`) | forgetting `pattern` glob for nested lookups |
+| `Grep` | `pattern` | passing non-regex without `glob` filter |
+| `Edit` | `file_path`, `new_string` (and `old_string`) | `old_string` not matching whitespace exactly |
+| `Write` | `file_path`, `content` | writing a directory path |
+| `Bash` | `command` | shell redirects (`>`, `>>`) sometimes blocked; default 2-min timeout, max 10 min |
+| `WebFetch` | `url`, `prompt` | passing a non-HTTP URL |
+| `WebSearch` | `query` | none common |
+| `AskUserQuestion` | `question`, `options` (array of 2–4) | **`options: null` or empty → silent failure** |
+| `Skill` | `skill` | passing a skill that isn't installed |
+| `Agent` | `subagent_type`, `prompt` (and `description`) | passing a name not declared in `.claude/agents/` |
+
+---
+
+## `Read`
+
+Read a file (or a slice of one).
+
+```json
+{
+  "file_path": "/abs/path/to/file.ts",
+  "offset": 10,
+  "limit": 50
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `file_path` | string | **yes** | Absolute path. Reading a directory errors. |
+| `offset` | number | no | 1-based line number to start at. Defaults to 1. |
+| `limit` | number | no | Lines to read from offset. If omitted, reads to EOF. |
+
+**Failure modes:** `file_path` to a directory errors. `file_path` to a non-existent file errors. Don't pass `offset` > file line count.
+
+---
+
+## `Glob`
+
+List files matching a glob pattern.
+
+```json
+{
+  "pattern": "**/*.ts",
+  "path": "/abs/path/to/project"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `pattern` | string | **yes** | Glob, e.g. `*.ts`, `src/**/*.tsx`. |
+| `path` | string | no | Absolute root. Defaults to the working directory. |
+
+**Failure modes:** Invalid glob syntax errors. The output excludes common build dirs (node_modules, .git, dist, build, .next, coverage, __pycache__, .venv, target, out, bin, obj) by default.
+
+---
+
+## `Grep`
+
+Regex search across files (ripgrep under the hood).
+
+```json
+{
+  "pattern": "class \\w+ extends Plugin",
+  "path": "/abs/path/to/project",
+  "glob": "*.ts",
+  "output_mode": "files_with_matches",
+  "-n": true
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `pattern` | string | **yes** | Treated as a regex. Use `rg` syntax. |
+| `path` | string | no | Defaults to cwd. Absolute path recommended. |
+| `glob` | string | no | Include filter, e.g. `*.ts`, `*.{ts,tsx}`. |
+| `output_mode` | string | no | `content` (with `-n` for line numbers), `files_with_matches`, or `count`. |
+| `-n` | bool | no | Show line numbers (with `output_mode: content`). |
+
+**Failure modes:** An invalid regex errors. Path to a file errors when used without a glob filter — must be a directory.
+
+---
+
+## `Edit`
+
+The workhorse edit tool.
+
+### Mode 1 — `old_string` / `new_string` (replace a block)
+
+```json
+{
+  "file_path": "/abs/path/to/file.ts",
+  "old_string": "export const foo = 1;\n",
+  "new_string": "export const foo = 2;\n"
+}
+```
+
+- `old_string` must match EXACTLY including whitespace and trailing newline.
+- If `old_string` is not found → tool returns an error like `String to replace not found in file`.
+- If `old_string` matches more than once → tool returns `Found multiple matches` or similar; refine.
+
+**This is the #1 cause of agent mistakes.** When in doubt:
+1. First call `Read` on the file
+2. Copy the exact bytes (including indentation and trailing newline)
+3. Make the smallest possible edit
+
+### Mode 2 — `replace_all` (replace every occurrence)
+
+```json
+{
+  "file_path": "/abs/path/to/file.ts",
+  "old_string": "foo",
+  "new_string": "bar",
+  "replace_all": true
+}
+```
+
+Use when the same exact string appears multiple times and you genuinely want every occurrence replaced.
+
+### File does not exist (use `Write` instead)
+
+If the file does not exist, use the `Write` tool — `Edit` requires the file to exist.
+
+**Common failures:**
+- "String to replace not found" — whitespace mismatch. Re-read the file and copy the bytes exactly.
+- "multiple matches" — your `old_string` is too generic. Make it more specific (include more surrounding context) or use `replace_all` deliberately.
+- Missing trailing `\n` — `new_string` and `old_string` must end with `\n` if the surrounding context does.
+
+---
+
+## `Write`
+
+Create or fully overwrite a file.
+
+```json
+{
+  "file_path": "/abs/path/to/new-file.ts",
+  "content": "// brand new file content\n"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `file_path` | string | **yes** | Absolute path. Parent dirs are NOT created automatically. |
+| `content` | string | **yes** | Full file body. |
+
+**Common failures:**
+- Path to a directory errors.
+- Parent directory missing → creates the file in cwd with the basename, or errors. Use `Bash` to `mkdir -p` first.
+
+---
+
+## `Bash`
+
+Run a shell command.
+
+```json
+{
+  "command": "ls -la /tmp",
+  "timeout": 30000,
+  "description": "List /tmp contents"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `command` | string | **yes** | Passed to `/bin/bash -c` (Linux/macOS) or `cmd /c` (Windows). |
+| `timeout` | number | no | **Max 600,000 ms (10 min).** Default ~120,000 (2 min). |
+| `description` | string | no | Short human-readable summary shown in the TUI (recommended). |
+
+**Critical constraints:**
+- **No shell redirects** (`>`, `>>`, `<`) in some runtimes / sandboxes. Use `Edit` or `Write` to author files.
+- Long-running processes hit the timeout. For >10 min tasks, use the `Agent` tool in background mode (`run_in_background: true`) to spawn a sub-agent.
+- The `command` string IS a shell command. Quote carefully. Use `&&` to chain, `;` to sequence, `|` to pipe.
+
+**Common failures:**
+- `command not found` — the binary isn't on PATH. Use absolute path or `which <name>` first.
+- `Permission denied` — file isn't executable, or you're writing to a protected dir.
+- `timeout` — increase `timeout` (max 600,000) or move to a background agent.
+
+---
+
+## `WebFetch`
+
+Fetch a URL and answer a prompt against it.
+
+```json
+{
+  "url": "https://example.com/docs",
+  "prompt": "Summarize the authentication section"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `url` | string | **yes** | Must be HTTP/HTTPS. No `file://`. |
+| `prompt` | string | **yes** | The question you want the page answered against. |
+
+**Failure modes:** Non-HTTP URLs error. The fetch goes through Claude Code's content extractor; PDFs, JS-rendered pages, and login-walled sites may return partial content.
+
+---
+
+## `WebSearch`
+
+Run a web search and return ranked results.
+
+```json
+{
+  "query": "Claude Code Agent SDK sub-agent routing"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `query` | string | **yes** | Natural-language search. |
+
+---
+
+## `AskUserQuestion`
+
+Ask the user ONE clarifying question with 2–4 options. **This is the most-misused tool.**
+
+```json
+{
+  "question": "Which database do you want to use?",
+  "options": [
+    { "label": "PostgreSQL", "description": "Recommended for relational + JSON" },
+    { "label": "MySQL", "description": "Traditional RDBMS" },
+    { "label": "SQLite", "description": "Embedded, no server" },
+    { "label": "MongoDB", "description": "Document store" }
+  ],
+  "header": "Database",
+  "multi_select": false
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `question` | string | **yes** | One question. Multi-question calls fail. |
+| `options` | array of 2–4 objects | **yes** | **MUST be 2–4 items, each with `label` + `description`.** |
+| `header` | string | no | Short (≤12 chars) shown in the picker chip. |
+| `multi_select` | bool | no | Allow multiple selections. Default false. |
+
+### ⚠️ CRITICAL — `options` is REQUIRED, not optional
+
+If you pass `options: []`, omit `options`, or pass strings instead of
+objects, Claude Code **silently rejects the call** and counts it as a
+mistake. After several such silent failures the session aborts.
+
+### When to use `AskUserQuestion`
+
+- A key implementation decision has multiple valid paths
+- The user said something ambiguous and you need to clarify before doing real work
+- You're about to make a destructive change (rm, drop table, force-push)
+
+### When NOT to use `AskUserQuestion`
+
+- You can decide safely using sensible defaults
+- The user's intent is clear from context
+- You're just confirming something you should have done already
+- The answer is in the codebase (use `Read` / `Grep` first)
+
+### Alternatives to `AskUserQuestion`
+
+- **Use multiple `Agent` calls in one message** to parallelize the investigation
+- **Use the `Agent` tool (background)** for long-running research
+- **Just pick a sensible default** and document it in your final response
+
+### Recovery from `AskUserQuestion` mistakes
+
+If you accidentally pass the wrong shape and the tool errors, **DO NOT
+retry the same broken call**. Instead:
+1. Switch to a sensible default
+2. Document the decision in your final response
+3. Let the user override later if they disagree
+
+---
+
+## `Skill`
+
+Activate a skill.
+
+```json
+{
+  "skill": "commit",
+  "args": "Add auth bug fix"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `skill` | string | **yes** | Exact skill name. Run `skills list` (or check `~/.claude/skills/`) to see available. |
+| `args` | string | no | Passed to the skill's runner. |
+
+**Failure modes:** Unknown skill name errors. Skills are case-sensitive.
+
+---
+
+## `Agent`
+
+Dispatch a sub-agent. Claude Code's equivalent of Bizar's `task`
+and `bizar_spawn_background` tools.
+
+```json
+{
+  "subagent_type": "todd",
+  "prompt": "Implement the rate-limiter middleware in src/middleware/ratelimit.ts",
+  "description": "Implement rate limiter"
+}
+```
+
+Synchronous (default):
+
+```json
+{
+  "subagent_type": "todd",
+  "prompt": "Implement the rate-limiter middleware in src/middleware/ratelimit.ts",
+  "description": "Implement rate limiter",
+  "run_in_background": false
+}
+```
+
+Background (async, returns immediately):
+
+```json
+{
+  "subagent_type": "greg",
+  "prompt": "Research the auth flow across the codebase. Cite file paths.",
+  "description": "Research auth flow",
+  "run_in_background": true
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `subagent_type` | string | **yes** | A Bizar agent name declared in `.claude/agents/<name>.md`: `mike`, `todd`, `karen`, `brenda`, `greg`, `susan`, `steve`, `brad`, `janet`, `carl`, `linda`, `pam`, `kevin`, `oscar`. |
+| `prompt` | string | **yes** | What to do. Be specific. |
+| `description` | string | no | Short summary shown in the TUI. |
+| `run_in_background` | bool | no | Default `false`. Set true for async dispatch. |
+
+**Failure modes:** Unknown `subagent_type` errors. Sync runs block until the sub-agent returns. Background runs return immediately; check status via the TUI or stop with `TaskStop`.
+
+### Sync vs async dispatch
+
+- **`Agent` (sync)** — blocks until the sub-agent returns. Use when the parent needs the result before continuing.
+- **`Agent` with `run_in_background: true`** — async, returns immediately. Use for long-running work that doesn't block the parent. Replaces Cline's `bizar_spawn_background`.
+
+### Coordinating multiple background agents
+
+When fanning out several research or exploration tasks, issue multiple `Agent` calls in the **same message** with `run_in_background: true`. Each runs in parallel. Collect results by either:
+
+- Waiting for the user to ask, then re-dispatching sync `Agent` calls that summarize the background work.
+- Reading the background agent's final summary when it completes.
+
+---
+
+## Claude Code's other useful tools
+
+These are available in many Claude Code sessions but not declared
+in Bizar agents' `tools` frontmatter by default. Add them when the
+agent needs them:
+
+- **`TaskStop`** — stop a background `Agent` that's looping, stalling, or no longer relevant.
+- **`TodoWrite`** — track a multi-step plan in the agent's scratchpad. Use 3-7 items max; refine as you go.
+- **`NotebookEdit`** — edit Jupyter notebook cells. Rarely needed outside data work.
+- **`EnterWorktree` / `ExitWorktree`** — git worktree isolation. Only when explicitly requested.
+- **`WebSearch`** — covered above.
+
+These are documented at https://code.claude.com/docs/en/agent-sdk/overview.
+
+---
+
+## Recovery: when you hit the mistake limit
+
+If Claude Code surfaces "max consecutive mistakes reached" and aborts the session:
+
+1. **Stop retrying the same broken call.** Each retry wastes a mistake.
+2. **Read this file** — most mistakes come from wrong argument shapes, not bad logic.
+3. **Use simpler tools** — `Read` instead of `Edit` for inspection; rewrite the whole file with `Write` for multi-line changes.
+4. **Spawn a fresh session** if the runtime is in a bad state.
+
+---
+
+## Per-tool I/O contract
+
+All Claude Code tools return text via stdout-like output. Failed tools return either:
+- A structured error message (e.g. `String to replace not found in /path`)
+- An exception thrown back to the agent (which Claude Code wraps as a mistake)
+
+There is no `success: true|false` field. You must read the response text
+to know what happened.