@zhn2605/topo 0.2.0 → 0.3.0

package/README.md

@@ -68,11 +68,31 @@ topo hook                    # print a Claude Code hook so your agent's edits sh
 
 ## Ask Topo and agents
 
-If the `claude` CLI is on your PATH, questions in the ⌘K box go to Topo's own Claude Code process. It can only use Topo's map tools, so it answers questions, changes the view and makes territories, but never edits code. Ask "how does X work" and it shows a short walkthrough: just the blocks that matter, numbered in the order they run. Without `claude`, the box falls back to plain search.
+If the `claude` CLI is on your PATH, questions in the ⌘K box go to Topo's own Claude Code process. It can only use Topo's map tools, so it answers questions, changes the view and makes territories, but never edits code. Ask "how does X work" and it shows a walkthrough: the blocks that matter, numbered in the order they run, as a guided tour. Its length follows the question: a handful of steps for the gist, every step when you ask for all of it. The map glides to each block in turn, a marker travels the call that leads there, and a card under the block says what happens in it (← / → or Play to move on, Esc to leave; "Tour this walkthrough" in ⌘K starts it again). The card switches the map between *Just these blocks* and *With neighbours*, the same blocks with what they call and what calls them. Without `claude`, the box falls back to plain search.
 
-**Territories** are regions of the map you hand an agent: a label, the task, and the blocks it covers (saved in `.topo/territories.json`). *Launch* starts a headless `claude -p` on that task with Topo's tools, and its edits show up on the map as it makes them. Edits outside its territory aren't blocked, just flagged. Agents working in git worktrees (Claude Code subagents, Codex, `git worktree add`) show up too.
+The Ask Topo panel opens on a short welcome until you close it: *Walk me through these changes* (or *how this runs* on a map), *How does … work?* and *Plan a change to …*. Asked on the review map, "walk me through this" tours the changes on that map, with a few sentences per block on what it does and what changed. A plan comes back as steps on the map and territories with their tasks written out; no agent starts until you say go.
 
-`--dangerously-skip-permissions` lets launched agents run without asking, like Claude Code's flag of the same name. The UI shows a red pill while it's on.
+When a request could go more than one way ("split this repo up for a few agents": how many, split by what?), Topo asks first, the way Claude Code does: a question or two with choices as buttons under its reply, plus a box for your own answer. Pick and it carries on.
+
+When reviewing, **Tour the changes** (the button on the *To review* tab, or ⌘K) plays the same tour on the review map itself, over the changes it shows, callers before what they call; *Tour all N* on the card takes in every change. Each card shows what changed: the risk and its reasons, the signature old → new, calls gained and lost, the agent's reason if it gave one, and Viewed / Ask for changes. Esc brings you back to the review. Asking Topo "walk me through the change" does the same with a sentence per step.
+
+**Viewed** marks a changed block as seen, so a long review keeps your place: *To review* dims it and counts how many you've viewed, and the mark clears itself if the block changes again (after an agent's next pass you re-read only what's new). Marks are yours alone, saved in `.topo/reviews.json`, which Topo gitignores. **Ask for changes** sends a note on that block straight to the agent that made it; on a block no agent made, it reads *Hand to an agent* and starts a worker with your note as the task.
+
+**Territories** are regions of the map you hand an agent: a label, the task, and the blocks it covers (saved in `.topo/territories.json`). *Launch* starts an agent CLI headless on that task with Topo's tools, and its edits show up on the map as it makes them. Edits outside its territory aren't blocked, just flagged. Agents working in git worktrees (Claude Code subagents, Codex, `git worktree add`) show up too.
+
+**Which agents.** Launch works with any of these that are on your PATH; each territory picks one under *Runs with*:
+
+| Agent | Asks you mid-run | Continue a run | Edits on the map from |
+|---|---|---|---|
+| Claude Code (`claude`) | yes, as cards under the bell | yes | its PostToolUse hook |
+| Gemini CLI (`gemini`) | no: runs in its own sandbox (`auto_edit`; *Never ask* = `yolo`) | no | its JSON stream |
+| Codex (`codex`) | no: runs in its own sandbox (`workspace-write`; *Never ask* = bypass) | yes | its JSON stream |
+
+Ask Topo (the ⌘K box's agent) needs Claude Code; without it the box is plain search. Model overrides: `TOPO_WORKER_MODEL` (Claude, default `sonnet`), `TOPO_GEMINI_MODEL`, `TOPO_CODEX_MODEL`.
+
+**Keys are yours.** Topo never asks for, stores or sees an API key. Each CLI signs in the way it normally does: `claude` with your Claude login or `ANTHROPIC_API_KEY`, `gemini` with `GEMINI_API_KEY` or a Google login, `codex` with `codex login`. Set that up once in the CLI and Topo's launches use it.
+
+**Permissions.** The top of the Territories tab (or ⌘K, *Agent permissions*) sets what launched agents may do without asking: *Allow safe commands* (the default: reading, searching, editing, and read-only commands like `ls`, `cat`, `grep` and `git log`), *Ask for every command*, or *Never ask*. For Claude Code, anything else comes to you as a card under the bell. *Always allow* on a card saves the same rule Claude Code's own "don't ask again" saves, in the repo's `.claude/settings.local.json`, so it holds when you run `claude` yourself too. Gemini and Codex can't ask mid-run, so the setting picks their sandbox mode instead. The choice is saved in `.topo/settings.json` and applies to the next launch. Starting Topo with `--dangerously-skip-permissions` means *Never ask* for that session; the UI shows a red pill whenever nothing asks.
 
 ### Connect your own agent (MCP)
 
@@ -144,6 +164,7 @@ The base version is extracted from git into a cache keyed by commit, so your wor
 
 ## Changes
 
+- **0.3.0:** Ask Topo hands code changes to a worker agent itself; Launch runs Gemini CLI and Codex as well as Claude Code; agent permissions (safe commands by default, *Always allow* on a request card); a badge on every block an agent is editing; guided tours of walkthroughs, and *Tour the changes* in a review; repeat "outside its territory" warnings fold into one card; *Viewed* and *Ask for changes* replace Approve and Request changes (saved across restarts, cleared when a block changes again, notes go straight to the agent).
 - **0.2.0:** a new interface: one ⌘K box for search, actions and questions; right-click menus on blocks; views as one list; a single side panel you can fold or resize; agent requests under a bell with Approve/Deny on each card; quieter colors. Runs on Node 24+ (was 26+).
 - **0.1.0:** first preview.