z0gcode 0.2.0 → 0.3.1

package/README.md

@@ -11,6 +11,7 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/z0gcode"><img src="https://img.shields.io/npm/v/z0gcode?color=A78BFF&label=npm" alt="npm"></a>
   <img src="https://img.shields.io/badge/license-MIT-A78BFF" alt="MIT license">
   <img src="https://img.shields.io/badge/node-18%2B-6B7080" alt="Node 18+">
   <img src="https://img.shields.io/badge/brain-0G_Compute_TEE-A78BFF" alt="0G Compute">
@@ -60,7 +61,7 @@ npm install && npm link                # or run directly with: node bin/z0g.mjs
 
 ```bash
 z0g "add a /health endpoint to server.js and test it"   # one-shot task
-z0g --auto "scaffold a Fastify app and run it"           # --auto allows shell commands (on-chain is a separate --onchain opt-in)
+z0g --auto "scaffold a Fastify app and run it"           # auto mode: runs commands without asking (else it asks you first)
 z0g goal --auto "make the failing tests pass"            # iterate until a verify command passes
 z0g --continue "now add input validation"                # resume the most recent chat
 z0g --resume                                             # pick a chat to resume (arrow-key picker)
@@ -74,21 +75,22 @@ z0g transcribe memo.mp3                                  # transcribe audio on 0
 z0g serve --mcp                                          # expose z0gcode's 0G tools over MCP
 ```
 
-**In the REPL**, type `/` then **Tab** to autocomplete slash commands: `/chats`, `/new`, `/rename`, `/init`, `/goal`, `/model`, `/effort`, `/subagents`, `/onchain`, `/skills`, `/attest`, `/share`, `/pull`, `/mint`, `/plan`, `/verify`, `/clear`, `/help`, `/exit`. `/chats` opens an arrow-key session picker (type to search, `ctrl-r` rename, `ctrl-x` delete); `/new [title]` starts a chat and `/rename <title>` renames the current one. `/model` opens the model picker (saved to `~/.z0gcode/settings.json`); `/effort low|medium|high` (or `default`) tunes reasoning depth vs speed and cost; `/subagents on|off` toggles parallel subagents; `/onchain on|off` toggles gas-spending on-chain actions (off by default); `/skills` lists and toggles your skills; `/share [anchor]` exports the session (encrypted) to 0G Storage (and anchors it on 0G Chain), and `/pull <root>` fetches, verifies, and decrypts one back. A short intro animation and a "thinking on 0G" indicator play on a color TTY; set `Z0G_NO_ANIM=1` to disable. Each turn is separated by a divider carrying a running session token and cost counter.
+**In the REPL**, type `/` then **Tab** to autocomplete slash commands: `/chats`, `/new`, `/rename`, `/init`, `/goal`, `/mode`, `/model`, `/effort`, `/subagents`, `/onchain`, `/skills`, `/attest`, `/share`, `/pull`, `/mint`, `/plan`, `/verify`, `/clear`, `/help`, `/exit`. `/chats` opens an arrow-key session picker (type to search, `ctrl-r` rename, `ctrl-x` delete); `/new [title]` starts a chat and `/rename <title>` renames the current one. `/mode ask|auto|plan` switches the permission mode; `/model` opens the model picker (saved to `~/.z0gcode/settings.json`); `/effort low|medium|high` (or `default`) tunes reasoning depth vs speed and cost; `/subagents on|off` toggles parallel subagents; `/onchain on|off` toggles gas-spending on-chain actions (off by default); `/escalate on|off` toggles switching to a stronger model on repeated failures; `/skills` lists and toggles your skills; `/share [anchor]` exports the session (encrypted) to 0G Storage (and anchors it on 0G Chain), and `/pull <root>` fetches, verifies, and decrypts one back. A short intro animation and a "thinking on 0G" indicator play on a color TTY; set `Z0G_NO_ANIM=1` to disable. Each turn is separated by a divider carrying a running session token and cost counter.
 
 **Options:** `--auto`, `--onchain`, `--continue`, `--resume`, `--new`, `--model <id>`, `--effort low|medium|high`, `--no-subagents`, `--verify "<cmd>"`, `--auto-verify`, `--max-steps <n>`, `--cwd <dir>`, and `--json` (with `models`).
 
 ## Features
 
 **The agent**
-- Agentic loop with tools: `search_files` (regex + glob), `read_file`, `write_file`, `edit_file`, `list_dir`, `run_bash` (gated by `--auto`), `update_plan`, and `read_skill`.
+- Agentic loop with tools: `search_files` (regex + glob), `read_file`, `write_file`, `edit_file`, `list_dir`, `run_bash` (gated by the permission mode below), `update_plan`, and `read_skill`.
+- **Permission modes** (`/mode`, like Claude Code): **ask** (default) prompts before each shell command and on-chain action (`y` / `n` / `a` = always), and "always" choices are remembered in `~/.z0gcode/settings.json` so it never asks again for that program; **auto** (`--auto`) runs without asking; **plan** is read-only, the agent explores and proposes a plan and touches nothing until you switch to ask or auto.
 - Colored diffs for every change, an inference HUD (tokens, answering model, `0G Compute (TEE)`), and a visible planning checklist on multi-step tasks.
 - Streaming answers rendered as terminal markdown (bold, headings, lists, tables, inline code, and syntax-highlighted code blocks for JS/TS, Python, Solidity, Go, Rust, shell, JSON, and more); piped output stays raw and greppable.
 - Multiple chats per project, each isolating its own history, plan, and provenance under `.z0g/sessions/`. On open, an arrow-key picker (with search, rename, delete) resumes a chat; `--continue` resumes the most recent, `--resume` shows the picker, `/chats` switches mid-session. Plus a goal loop (`z0g goal` re-runs until a verify command passes) and auto-verify.
 - **Project context**: `AGENTS.md` (and `.z0g/context.md`) are auto-loaded into the agent's system prompt on every run, so it follows your conventions and uses your real build/test/run commands. `z0g init` (or `/init`) analyzes the repo and writes an accurate `AGENTS.md` for you.
 - **Checkpoints and undo**: every file edit is logged with its before/after content per turn, so `z0g undo` (or `/undo`) reverts the last turn's changes (restoring files, deleting ones it created); `z0g checkpoints` lists what you can step back through.
 - **Custom commands and hooks**: drop `.z0g/commands/<name>.md` to add a `/<name>` slash command (the file is a prompt template; `$ARGUMENTS` is substituted, optional `description:` frontmatter, Tab-completed and listed by `/commands`). Define lifecycle hooks in `.z0g/hooks.json` (`preRun` / `postRun` shell commands, e.g. run your formatter or tests after each turn); hooks run shell, so they only fire with `--auto`.
-- Reliability on a decentralized backend: app-level multi-model fallback, retry and backoff, tool-JSON repair, a loop breaker, and model escalation.
+- Reliability on a decentralized backend: app-level multi-model fallback, retry and backoff, tool-JSON repair, a loop breaker (stops on repeated identical calls, or the same tool result with no progress, so it hands control back instead of spinning), and model escalation (when a tool fails repeatedly it moves to a stronger fallback for the rest of the turn; on by default after 3 failures, toggle with `/escalate on|off` or `--no-escalate`).
 - **Parallel subagents**: `spawn_subagents` fans out independent, read-only subtasks (review many files, research, audit, map a codebase) as isolated agents running in parallel, capped by `ZOG_MAX_PARALLEL`. The parent synthesizes the results and each subagent's transcript is saved. With 0G's cheap inference, fanning out to many agents costs cents: massively parallel agents at 0G prices. On by default; toggle with `/subagents on|off` or `--no-subagents`.
 - **Parallel write subagents**: with `--auto` in a git repo, `spawn_write_subagents` fans out subtasks that WRITE code, each in its own isolated **git worktree**, then merges every diff back into the working tree. Disjoint file sets merge automatically; overlapping edits are reported and skipped (never half-applied), and the merged changes are checkpointed so `z0g undo` reverts them. Verified end-to-end on 0G.
 
@@ -117,7 +119,7 @@ Every on-chain action, storage upload, chain deploy, the encrypted session `shar
 
 ## Roadmap
 
-Shipped: streaming with markdown rendering, multiple chat sessions per project (resume picker with search), planning, slash commands, the goal loop and auto-verify, in-agent `deploy_0g_chain` and `upload_0g_storage` (mainnet-verified, opt-in), the private verifiable session (`z0g share`, wallet-encrypted to 0G Storage + `--anchor` on 0G Chain, and `z0g pull` to fetch, verify, and decrypt, mainnet-verified), the session INFT (`z0g mint`, mainnet-verified), parallel subagents, media on 0G (image + transcription), MCP both ways, the model catalog and arrow-key picker, and user skills.
+Shipped: streaming with markdown rendering, multiple chat sessions per project (resume picker with search), planning, slash commands, the goal loop and auto-verify, in-agent `deploy_0g_chain` and `upload_0g_storage` (mainnet-verified, opt-in), the private verifiable session (`z0g share`, wallet-encrypted to 0G Storage + `--anchor` on 0G Chain, and `z0g pull` to fetch, verify, and decrypt, mainnet-verified), the session INFT (`z0g mint`, mainnet-verified), parallel subagents, media on 0G (image + transcription), MCP both ways, the model catalog and arrow-key picker, user skills, and a published npm package (`npm i -g z0gcode`).
 
 Next:
 - **Share a session, three ways.** Today `z0g share` is a *private* backup: the bundle is encrypted to your wallet, so only you can `pull` it. The plan keeps that and adds two ways to actually hand a session to someone, without ever trusting the storage layer with a key:
@@ -128,7 +130,7 @@ Next:
   Together these are the on-ramp to full ERC-7857 authorized users.
 - Full ERC-7857 (encrypted metadata + oracle transfer) on top of the current session INFT.
 - Full TEE-quote verification of the provenance manifest (not just model + response id).
-- Publish `z0gcode` to npm; a shareable starter pack of user skills.
+- A shareable starter pack of user skills.
 
 ## Development
 

package/bin/z0g.mjs

@@ -19,7 +19,7 @@ import {
 } from "../src/sessions.mjs";
 import { loadPlan } from "../src/plan.mjs";
 import { loadMcp } from "../src/mcp.mjs";
-import { saveSetting } from "../src/settings.mjs";
+import { saveSetting, loadSettings } from "../src/settings.mjs";
 import { fetchModels, orderChatModels } from "../src/models-info.mjs";
 import { discoverSkills, setSkillEnabled } from "../src/user-skills.mjs";
 import { generateImage, transcribeAudio } from "../src/media.mjs";
@@ -54,12 +54,13 @@ function helpText() {
       ["z0g serve --mcp", "Expose z0gcode's 0G tools as an MCP server"],
     ]],
     ["Options", [
-      ["--auto", "Allow shell commands (run_bash)"],
+      ["--auto", "Start in auto mode (run commands without asking; else /mode ask prompts)"],
       ["--onchain", "Allow gas-spending on-chain actions (off by default)"],
       ["--continue", "Continue the saved session in this directory"],
       ["--model <id>", "Override the model (default " + CONFIG.model + ")"],
       ["--effort <l>", "Reasoning effort: low, medium, high (default: model's own)"],
       ["--no-subagents", "Disable parallel subagents for this run"],
+      ["--no-escalate", "Do not switch to a stronger model on repeated tool failures"],
       ['--verify "<cmd>"', "Run, then verify and self-correct with this command"],
       ["--auto-verify", "Same, auto-detecting the verify command"],
       ["--max-steps <n>", "Max agent steps (default " + CONFIG.maxSteps + ")"],
@@ -89,9 +90,11 @@ const SLASH_COMMANDS = [
   ["/rename", "Rename the current chat (/rename <title>)"],
   ["/init", "Analyze the project and write an AGENTS.md context file"],
   ["/model", "Pick the active 0G model (saved to settings)"],
+  ["/mode", "Permission mode: ask (approve each) | auto (run all) | plan (read-only)"],
   ["/effort", "Set reasoning effort (low|medium|high|default)"],
   ["/subagents", "Enable or disable parallel subagents (on|off)"],
   ["/onchain", "Enable or disable gas-spending on-chain actions (on|off)"],
+  ["/escalate", "Toggle switching to a stronger model on repeated failures (on|off)"],
   ["/skills", "List skills; /skills enable|disable <name>"],
   ["/commands", "List project custom commands (.z0g/commands/*.md)"],
   ["/attest", "Show the provenance manifest"],
@@ -248,6 +251,7 @@ function parse(argv) {
     else if (a === "--no-subagents") flags.subagents = false;
     else if (a === "--onchain") flags.onchain = true;
     else if (a === "--no-onchain") flags.onchain = false;
+    else if (a === "--no-escalate") flags.escalate = false;
     else if (a === "--force") flags.force = true;
     else if (a === "--import") flags.import = true;
     else if (a === "--verify") flags.verify = argv[++i];
@@ -713,13 +717,13 @@ async function runTask(task, flags) {
     // Auto-verify: a normal run becomes self-correcting when a verify command is present.
     const verifyCmd = flags.verify || (flags.autoVerify ? detectVerifyCmd(cwd) : null);
     if (verifyCmd) {
-      await runGoal({ client: makeClient(), objective: task, cwd, sessionId, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, verifyCmd, maxIters: 3, history: opened.history });
+      await runGoal({ client: makeClient(), objective: task, cwd, sessionId, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, preferredEscalate: flags.escalate, verifyCmd, maxIters: 3, history: opened.history });
       return;
     }
     const client = makeClient();
     const mcp = await loadMcp(cwd);
     if (mcp?.count) ui.info(`MCP: ${mcp.count} tool(s) from configured servers`);
-    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, history: opened.history, mcp });
+    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, preferredEscalate: flags.escalate, history: opened.history, mcp });
     if (res?.messages) await saveMessages(cwd, sessionId, res.messages);
     await mcp?.close();
   } finally {
@@ -742,7 +746,7 @@ async function cmdGoal(objective, flags) {
   try {
     const verifyCmd = flags.verify || detectVerifyCmd(cwd);
     if (!flags.auto) ui.info("tip: run goal with --auto so the agent can run and verify its own work.");
-    await runGoal({ client, objective, cwd, sessionId: opened.id, sessionDir: opened.dir, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, verifyCmd, maxIters: 3, history: opened.history });
+    await runGoal({ client, objective, cwd, sessionId: opened.id, sessionDir: opened.dir, allowBash: flags.auto, preferredModel: flags.model, preferredEffort: flags.effort, preferredSubagents: flags.subagents, preferredOnchain: flags.onchain, preferredEscalate: flags.escalate, verifyCmd, maxIters: 3, history: opened.history });
   } finally {
     process.removeListener("SIGINT", onSig);
     pruneEmptySync(cwd, opened.id);
@@ -761,6 +765,10 @@ async function repl(flags) {
   let effort = flags.effort;
   let subagents = flags.subagents;
   let onchain = flags.onchain;
+  let escalate = flags.escalate;
+  // Permission mode: auto (run all) | ask (approve each) | plan (read-only).
+  let mode = flags.auto ? "auto" : "ask";
+  const allowedCmds = new Set(loadSettings(cwd).allowedCommands || []);
   let sessTokens = { in: 0, out: 0 };
   let priceMap = null;
   fetchModels(client).then((all) => { priceMap = Object.fromEntries(all.map((m) => [m.id, m])); }).catch(() => {});
@@ -782,6 +790,25 @@ async function repl(flags) {
   const activeModel = () => model || CONFIG.model;
   const activeEffort = () => (effort === "" ? null : (effort || CONFIG.effort));
   const activeOnchain = () => (onchain !== undefined ? onchain : CONFIG.onchain);
+  const activeEscalate = () => (escalate !== undefined ? escalate : CONFIG.escalate);
+  // Approve a gated action in "ask" mode. Remembers "always" choices in settings
+  // so it never asks again for that program (or for on-chain actions).
+  const approve = async (kind, desc) => {
+    const key = kind === "run_bash" ? "bash:" + (String(desc).trim().split(/\s+/)[0] || "?") : "@onchain";
+    if (allowedCmds.has(key)) return true;
+    rl.pause();
+    const label = kind === "run_bash" ? ui.strong(String(desc).slice(0, 80)) : "on-chain: " + desc;
+    console.log("\n  " + ui.warn(ui.uiTTY ? "▲" : "!") + "  " + (kind === "run_bash" ? "run " : "") + label);
+    const a = (await ask("     allow?  " + ui.accent("y") + "es  " + ui.accent("n") + "o  " + ui.accent("a") + "lways  ")).trim().toLowerCase();
+    rl.resume();
+    if (a === "a" || a === "always") {
+      allowedCmds.add(key);
+      saveSetting("allowedCommands", [...allowedCmds]);
+      ui.info("saved: won't ask again for " + (kind === "run_bash" ? key.slice(5) : "on-chain actions"));
+      return true;
+    }
+    return a === "y" || a === "yes";
+  };
   const costOf = () => {
     const m = priceMap && priceMap[activeModel()];
     if (!m || m.inPerM == null) return null;
@@ -799,13 +826,14 @@ async function repl(flags) {
   // Run one agent turn: hooks, the agent, then persist history + tokens.
   const runTurn = async (task) => {
     await runHooks(cwd, "preRun", hooks, flags.auto, task);
-    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), history, mcp });
+    const res = await runAgent({ client, task, cwd, sessionDir: sessionDirPath, preferredMode: mode, approve, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), preferredEscalate: activeEscalate(), history, mcp });
     history = res.messages;
     if (res.usageTotal) { sessTokens.in += res.usageTotal.prompt || 0; sessTokens.out += res.usageTotal.completion || 0; }
     await saveMessages(cwd, sessionId, history);
     await runHooks(cwd, "postRun", hooks, flags.auto, task);
   };
   ui.info("Interactive session. Type a task, or / then Tab for commands.");
+  ui.info("mode: " + ui.strong(mode) + (mode === "ask" ? " (I ask before running commands)" : mode === "plan" ? " (read-only until you /mode auto)" : " (runs commands without asking)") + "  ·  /mode ask|auto|plan");
   if (customCmds.length) ui.info(customCmds.length + " custom command(s): " + customCmds.map((c) => "/" + c.name).join(", "));
   if (hasHooks(hooks) && !flags.auto) ui.info("hooks are configured; run with --auto to enable them");
   // Blinking block cursor at the prompt (matches the demo); restore on any exit.
@@ -903,6 +931,29 @@ async function repl(flags) {
           console.log(ui.warn("usage: /onchain on|off"));
         }
       }
+      else if (cmd === "escalate") {
+        const a = arg.toLowerCase().trim();
+        if (a === "on" || a === "off") {
+          escalate = a === "on"; saveSetting("escalate", escalate);
+          ui.info("escalate " + (escalate ? "on" : "off") + " (saved)" + (escalate ? "  ·  switches to a stronger model after " + CONFIG.escalateAfter + " tool failures" : "  ·  stays on the chosen model"));
+        } else if (!a) {
+          ui.info("escalate: " + (activeEscalate() ? "on" : "off") + "  ·  after " + CONFIG.escalateAfter + " failures  ·  usage: /escalate on|off");
+        } else {
+          console.log(ui.warn("usage: /escalate on|off"));
+        }
+      }
+      else if (cmd === "mode") {
+        const a = arg.toLowerCase().trim();
+        if (["ask", "auto", "plan"].includes(a)) {
+          mode = a;
+          const desc = a === "auto" ? "runs commands without asking" : a === "plan" ? "read-only: explores and plans, no writes or commands" : "asks before each command / on-chain action";
+          ui.info("mode: " + ui.strong(a) + "  ·  " + desc);
+        } else if (!a) {
+          ui.info("mode: " + ui.strong(mode) + "  ·  usage: /mode ask|auto|plan" + (allowedCmds.size ? "  ·  " + allowedCmds.size + " always-allowed" : ""));
+        } else {
+          console.log(ui.warn("usage: /mode ask|auto|plan"));
+        }
+      }
       else if (cmd === "skills") cmdSkills(cwd, arg);
       else if (cmd === "chats") {
         if (Array.isArray(history) && history.length) await saveMessages(cwd, sessionId, history);
@@ -967,7 +1018,7 @@ async function repl(flags) {
         else { console.log(ui.section("Custom commands", customCmds.length + " loaded")); for (const c of customCmds) console.log("  " + ui.accent("/" + c.name) + "  " + ui.muted(c.description)); }
       }
       else if (cmd === "goal") {
-        await runGoal({ client, objective: arg, cwd, sessionId, sessionDir: sessionDirPath, allowBash: flags.auto, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), verifyCmd: flags.verify || detectVerifyCmd(cwd), maxIters: 3, history });
+        await runGoal({ client, objective: arg, cwd, sessionId, sessionDir: sessionDirPath, preferredMode: mode, approve, preferredModel: model, preferredEffort: effort, preferredSubagents: subagents, preferredOnchain: activeOnchain(), preferredEscalate: activeEscalate(), verifyCmd: flags.verify || detectVerifyCmd(cwd), maxIters: 3, history });
         history = await readMessages(cwd, sessionId) || history;
       }
       else if (customMap[cmd]) {
@@ -994,7 +1045,7 @@ async function main() {
   if (flags.version) {
     let v = "";
     try { v = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version; } catch {}
-    console.log("z0gcode " + (v || "0.2.0"));
+    console.log("z0gcode " + (v || "0.3.1"));
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "z0gcode",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A terminal coding agent whose brain runs on 0G Compute: private, verifiable AI with on-chain provenance.",
   "type": "module",
   "bin": {

package/src/agent.mjs

@@ -57,22 +57,30 @@ function parseArgs(raw) {
   }
 }
 
-export async function runAgent({ client, task, cwd, sessionDir, allowBash, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, onModel, history, mcp, quiet = false, toolNames = null, isSubagent = false }) {
+export async function runAgent({ client, task, cwd, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, preferredEscalate, onModel, history, mcp, quiet = false, toolNames = null, isSubagent = false }) {
   const q = !!quiet;
   // "" means an explicit unset (use the model's own default); undefined falls back.
   const effort = preferredEffort === "" ? null : (preferredEffort || CONFIG.effort);
   const subOn = preferredSubagents !== undefined ? preferredSubagents : CONFIG.subagents;
   const onchainOn = preferredOnchain !== undefined ? preferredOnchain : CONFIG.onchain;
   const provDir = sessionDir || path.join(cwd, ".z0g");
-  const execute = makeExecutor({ cwd, allowBash, sessionDir: provDir, onchain: onchainOn });
+  // Permission mode: auto | ask | plan. Legacy: allowBash -> auto, else ask.
+  const mode = preferredMode || (allowBash ? "auto" : "ask");
+  const canBash = mode !== "plan"; // shell available in auto/ask (gated at exec)
+  const execute = makeExecutor({ cwd, allowBash, sessionDir: provDir, onchain: onchainOn, mode, approve });
   // Restrict the toolset for subagents (read-only), and drop spawn_subagents when
   // it is a subagent (no recursion) or the toggle is off. Drop on-chain tools when
   // the on-chain toggle is off so the agent never proposes a gas-spending action.
   let baseTools = toolNames ? TOOL_DEFS.filter((t) => toolNames.includes(t.function.name)) : TOOL_DEFS;
   if (isSubagent || !subOn) baseTools = baseTools.filter((t) => t.function.name !== "spawn_subagents" && t.function.name !== "spawn_write_subagents");
-  // Write subagents edit files and run shell in worktrees, so require --auto.
-  if (!allowBash) baseTools = baseTools.filter((t) => t.function.name !== "spawn_write_subagents");
+  // Write subagents edit files and run shell in worktrees, so they need shell.
+  if (!canBash) baseTools = baseTools.filter((t) => t.function.name !== "spawn_write_subagents");
   if (!onchainOn) baseTools = baseTools.filter((t) => t.function.name !== "upload_0g_storage" && t.function.name !== "deploy_0g_chain");
+  // Plan mode is read-only: drop every acting tool so the agent explores and plans.
+  if (mode === "plan") {
+    const PLAN_TOOLS = new Set(["read_file", "search_files", "list_dir", "read_skill", "update_plan", "spawn_subagents"]);
+    baseTools = baseTools.filter((t) => PLAN_TOOLS.has(t.function.name));
+  }
   const toolSet = !isSubagent && mcp?.tools?.length ? [...baseTools, ...mcp.tools] : baseTools;
   const models = modelChain(preferredModel);
   const prov = makeProvenance(provDir);
@@ -83,7 +91,10 @@ export async function runAgent({ client, task, cwd, sessionDir, allowBash, prefe
     : [{ role: "system", content: systemPrompt(cwd) }, { role: "user", content: task }];
 
   const recent = []; // circuit breaker on repeated identical tool calls
+  const results = []; // no-progress breaker: repeated identical tool RESULTS
   const failCounts = {}; // per-tool failure counter, drives model escalation
+  const escalateOn = preferredEscalate !== undefined ? preferredEscalate : CONFIG.escalate;
+  const escalateAfter = CONFIG.escalateAfter;
   let escalate = false;
   let activeModel = models[0];
   const usageTotal = { prompt: 0, completion: 0, total: 0 };
@@ -150,6 +161,7 @@ export async function runAgent({ client, task, cwd, sessionDir, allowBash, prefe
       return { ok: true, steps: step + 1, changes: prov.count(), messages, finalText, usageTotal };
     }
 
+    let stuck = false;
     for (const tc of toolCalls) {
       const name = tc.function?.name;
       const args = parseArgs(tc.function?.arguments);
@@ -278,10 +290,25 @@ export async function runAgent({ client, task, cwd, sessionDir, allowBash, prefe
         }
       } else {
         failCounts[name] = (failCounts[name] || 0) + 1;
-        if (failCounts[name] >= 2) escalate = true; // stuck on this tool: try a stronger model
+        if (escalateOn && failCounts[name] >= escalateAfter) escalate = true; // stuck on this tool: try a stronger model
       }
 
       messages.push({ role: "tool", tool_call_id: tc.id, content: String(res.content ?? (res.ok ? "OK" : "ERROR")) });
+
+      // No-progress breaker: the same tool returning the same result repeatedly
+      // means the agent is spinning (e.g. re-checking a state only a human can
+      // change). Stop cleanly and hand control back, instead of burning steps.
+      const rkey = `${name}|${res.summary || ""}|${String(res.content ?? "").slice(0, 300)}`;
+      results.push(rkey);
+      if (results.length > 8) results.shift();
+      if (results.filter((k) => k === rkey).length >= 3) stuck = true;
+    }
+
+    if (stuck) {
+      finalText = "Stopped: I kept getting the same result without new progress. If this needs a manual step (a permission or setting change), do it and ask me again, or refine the task.";
+      if (!q) { ui.error("Stopped: no progress (same tool result 3 times)."); ui.assistant(finalText); }
+      usageTotal.total = usageTotal.prompt + usageTotal.completion;
+      return { ok: false, steps: step + 1, changes: prov.count(), messages, finalText, usageTotal };
     }
   }
 

package/src/config.mjs

@@ -65,6 +65,15 @@ export const CONFIG = {
     if (e !== undefined) return e;
     return typeof settings.onchain === "boolean" ? settings.onchain : false;
   })(),
+
+  // Escalate to a stronger fallback model when a tool fails repeatedly. ON by
+  // default (env > settings > on); escalateAfter is the failure threshold.
+  escalate: (() => {
+    const e = boolOf(process.env.ZOG_ESCALATE);
+    if (e !== undefined) return e;
+    return typeof settings.escalate === "boolean" ? settings.escalate : true;
+  })(),
+  escalateAfter: Math.max(2, Number(process.env.ZOG_ESCALATE_AFTER || settings.escalateAfter || 3)),
 };
 
 export function modelChain(preferred) {

package/src/goal.mjs

@@ -14,12 +14,12 @@ function runCmd(cmd, cwd) {
   });
 }
 
-export async function runGoal({ client, objective, cwd, sessionId, sessionDir, allowBash, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, verifyCmd, maxIters = 3, history: historyParam = null }) {
+export async function runGoal({ client, objective, cwd, sessionId, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, preferredEscalate, verifyCmd, maxIters = 3, history: historyParam = null }) {
   let history = historyParam ?? null;
   let task = objective;
   for (let iter = 1; iter <= maxIters; iter++) {
     console.log(ui.section("Goal", "iteration " + iter + "/" + maxIters));
-    const res = await runAgent({ client, task, cwd, sessionDir, allowBash, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, history });
+    const res = await runAgent({ client, task, cwd, sessionDir, allowBash, preferredMode, approve, preferredModel, preferredEffort, preferredSubagents, preferredOnchain, preferredEscalate, history });
     history = res.messages;
     if (sessionId && Array.isArray(history)) {
       try { await saveMessages(cwd, sessionId, history); } catch {}

package/src/tools.mjs

@@ -247,8 +247,20 @@ function safeResolve(cwd, p) {
   return abs;
 }
 
-export function makeExecutor({ cwd, allowBash, sessionDir, onchain = false }) {
+export function makeExecutor({ cwd, allowBash, sessionDir, onchain = false, mode, approve }) {
   const planDir = sessionDir || path.join(cwd, ".z0g");
+  // Permission mode: "auto" runs everything, "ask" prompts via approve(), "plan"
+  // is read-only. Legacy callers pass allowBash -> auto/ask.
+  const effMode = mode || (allowBash ? "auto" : "ask");
+  const readOnly = effMode === "plan";
+  const planDeny = (what) => ({ ok: false, summary: "plan mode", content: `Read-only plan mode: I can explore and plan but will not ${what}. Switch with /mode auto or /mode ask to let me act.` });
+  // Approve a gated action (run_bash / on-chain). Returns true if allowed.
+  const permit = async (kind, desc) => {
+    if (readOnly) return false;
+    if (effMode === "auto") return true;
+    if (typeof approve === "function") return !!(await approve(kind, desc));
+    return false;
+  };
   return async function execute(name, args) {
     try {
       switch (name) {
@@ -263,6 +275,7 @@ export function makeExecutor({ cwd, allowBash, sessionDir, onchain = false }) {
           return { ok: true, summary: `search "${args.query}" (${res.count})`, content: res.text };
         }
         case "write_file": {
+          if (readOnly) return planDeny("write files");
           const abs = safeResolve(cwd, args.path);
           let before = "", existed = true;
           try { before = await fs.readFile(abs, "utf8"); } catch { before = ""; existed = false; }
@@ -272,6 +285,7 @@ export function makeExecutor({ cwd, allowBash, sessionDir, onchain = false }) {
           return { ok: true, summary: `wrote ${args.path} (${after.length} bytes)`, content: "OK", change: { path: args.path, before, after, created: !existed } };
         }
         case "edit_file": {
+          if (readOnly) return planDeny("edit files");
           const abs = safeResolve(cwd, args.path);
           const cur = await fs.readFile(abs, "utf8");
           if (!args.old_string || !cur.includes(args.old_string)) {
@@ -291,16 +305,23 @@ export function makeExecutor({ cwd, allowBash, sessionDir, onchain = false }) {
           return { ok: true, summary: `list ${args.path || "."} (${lines.length})`, content: lines.join("\n") || "(empty)" };
         }
         case "run_bash": {
-          if (!allowBash) {
-            return { ok: false, summary: "bash denied", content: "run_bash is disabled. Re-run z0gcode with --auto to allow shell commands." };
+          if (readOnly) return planDeny("run commands");
+          if (!(await permit("run_bash", args.command))) {
+            return { ok: false, summary: "bash not allowed", content: effMode === "ask" ? "You declined this command." : "run_bash needs approval: run z0g interactively (mode ask) and approve it, or with --auto." };
           }
           const out = await runBash(args.command, cwd);
           return { ok: out.code === 0, summary: `bash exit ${out.code}`, content: out.text };
         }
         case "upload_0g_storage": {
+          if (onchain && !(await permit("on-chain", "upload to 0G Storage"))) {
+            return { ok: false, summary: "on-chain not allowed", content: readOnly ? "Read-only plan mode." : "You declined the on-chain action." };
+          }
           return await uploadToStorage(cwd, args.path, onchain);
         }
         case "deploy_0g_chain": {
+          if (onchain && !(await permit("on-chain", "deploy to 0G Chain"))) {
+            return { ok: false, summary: "on-chain not allowed", content: readOnly ? "Read-only plan mode." : "You declined the on-chain action." };
+          }
           return await deployToChain(cwd, args, onchain);
         }
         case "update_plan": {