z0gcode 0.2.0 → 0.3.0

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,14 +75,15 @@ 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); `/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.
@@ -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,7 +54,7 @@ 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 + ")"],
@@ -89,6 +89,7 @@ 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)"],
@@ -761,6 +762,9 @@ async function repl(flags) {
   let effort = flags.effort;
   let subagents = flags.subagents;
   let onchain = flags.onchain;
+  // 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 +786,24 @@ async function repl(flags) {
   const activeModel = () => model || CONFIG.model;
   const activeEffort = () => (effort === "" ? null : (effort || CONFIG.effort));
   const activeOnchain = () => (onchain !== undefined ? onchain : CONFIG.onchain);
+  // 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 +821,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(), 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 +926,18 @@ async function repl(flags) {
           console.log(ui.warn("usage: /onchain 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 +1002,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(), verifyCmd: flags.verify || detectVerifyCmd(cwd), maxIters: 3, history });
         history = await readMessages(cwd, sessionId) || history;
       }
       else if (customMap[cmd]) {
@@ -994,7 +1029,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.0"));
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "z0gcode",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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, 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);

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, 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, 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": {