svamp-cli 0.2.68 → 0.2.70

package/dist/{agentCommands-QnPGJFY-.mjs → agentCommands-BaQIO1T2.mjs}

@@ -148,7 +148,7 @@ async function sessionBroadcast(action, args) {
   console.log(`Broadcast sent: ${action}`);
 }
 async function connectToMachineService() {
-  const { connectAndGetMachine } = await import('./commands-D5kCHCfX.mjs');
+  const { connectAndGetMachine } = await import('./commands-BMOelGYC.mjs');
   return connectAndGetMachine();
 }
 async function inboxSend(targetSessionId, opts) {
@@ -165,7 +165,7 @@ async function inboxSend(targetSessionId, opts) {
   }
   const { server, machine } = await connectToMachineService();
   try {
-    const { resolveSessionId } = await import('./commands-D5kCHCfX.mjs');
+    const { resolveSessionId } = await import('./commands-BMOelGYC.mjs');
     const sessions = await machine.listSessions();
     const match = resolveSessionId(sessions, targetSessionId);
     const fullTargetId = match.sessionId;

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { s as startDaemon, b as stopDaemon, d as daemonStatus } from './run-HuBXfVSz.mjs';
+import { s as startDaemon, b as stopDaemon, d as daemonStatus } from './run-BqAe7GgA.mjs';
 import 'os';
 import 'fs/promises';
 import 'fs';
@@ -44,7 +44,7 @@ async function main() {
         console.error(`svamp daemon restart: ${err.message || err}`);
         process.exit(1);
       }
-      const { restartDaemon } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.u; });
+      const { restartDaemon } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.u; });
       await restartDaemon();
       process.exit(0);
     }
@@ -280,7 +280,7 @@ async function main() {
       console.error("svamp service: Service commands are not available in sandboxed sessions.");
       process.exit(1);
     }
-    const { handleServiceCommand } = await import('./commands-Cxb6tsha.mjs');
+    const { handleServiceCommand } = await import('./commands-CdGLuwtQ.mjs');
     await handleServiceCommand();
   } else if (subcommand === "serve") {
     const { isSandboxed: isSandboxedServe } = await import('./sandboxDetect-DNTcbgWD.mjs');
@@ -288,7 +288,7 @@ async function main() {
       console.error("svamp serve: Serve commands are not available in sandboxed sessions.");
       process.exit(1);
     }
-    const { handleServeCommand } = await import('./serveCommands-DDlHXpPe.mjs');
+    const { handleServeCommand } = await import('./serveCommands-DpKi_PuD.mjs');
     await handleServeCommand();
     process.exit(0);
   } else if (subcommand === "process" || subcommand === "proc") {
@@ -297,7 +297,7 @@ async function main() {
       console.error("svamp process: Process commands are not available in sandboxed sessions.");
       process.exit(1);
     }
-    const { processCommand } = await import('./commands-tUjBdy54.mjs');
+    const { processCommand } = await import('./commands-CB03m9-Z.mjs');
     let machineId;
     const processArgs = args.slice(1);
     const mIdx = processArgs.findIndex((a) => a === "--machine" || a === "-m");
@@ -315,7 +315,7 @@ async function main() {
   } else if (!subcommand || subcommand === "start") {
     await handleInteractiveCommand();
   } else if (subcommand === "--version" || subcommand === "-v") {
-    const pkg = await import('./package-DhOTD1Ln.mjs').catch(() => ({ default: { version: "unknown" } }));
+    const pkg = await import('./package-Cw40xKCx.mjs').catch(() => ({ default: { version: "unknown" } }));
     console.log(`svamp version: ${pkg.default.version}`);
   } else {
     console.error(`Unknown command: ${subcommand}`);
@@ -324,7 +324,7 @@ async function main() {
   }
 }
 async function handleInteractiveCommand() {
-  const { runInteractive } = await import('./run-BvcwFt_g.mjs');
+  const { runInteractive } = await import('./run-Di-48dsY.mjs');
   const interactiveArgs = subcommand === "start" ? args.slice(1) : args;
   let directory = process.cwd();
   let resumeSessionId;
@@ -369,7 +369,7 @@ async function handleAgentCommand() {
     return;
   }
   if (agentArgs[0] === "list") {
-    const { KNOWN_ACP_AGENTS, KNOWN_MCP_AGENTS: KNOWN_MCP_AGENTS2 } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.p; });
+    const { KNOWN_ACP_AGENTS, KNOWN_MCP_AGENTS: KNOWN_MCP_AGENTS2 } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.p; });
     console.log("Known agents:");
     for (const [name, config2] of Object.entries(KNOWN_ACP_AGENTS)) {
       console.log(`  ${name.padEnd(12)} ${config2.command} ${config2.args.join(" ")}  (ACP)`);
@@ -381,7 +381,7 @@ async function handleAgentCommand() {
     console.log('Use "svamp agent -- <command> [args]" for a custom ACP agent.');
     return;
   }
-  const { resolveAcpAgentConfig, KNOWN_MCP_AGENTS } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.p; });
+  const { resolveAcpAgentConfig, KNOWN_MCP_AGENTS } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.p; });
   let cwd = process.cwd();
   const filteredArgs = [];
   for (let i = 0; i < agentArgs.length; i++) {
@@ -405,12 +405,12 @@ async function handleAgentCommand() {
   console.log(`Starting ${config.agentName} agent in ${cwd}...`);
   let backend;
   if (KNOWN_MCP_AGENTS[config.agentName]) {
-    const { CodexMcpBackend } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.q; });
+    const { CodexMcpBackend } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.q; });
     backend = new CodexMcpBackend({ cwd, log: logFn });
   } else {
-    const { AcpBackend } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.o; });
-    const { GeminiTransport } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.G; });
-    const { DefaultTransport } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.D; });
+    const { AcpBackend } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.o; });
+    const { GeminiTransport } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.G; });
+    const { DefaultTransport } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.D; });
     const transportHandler = config.agentName === "gemini" ? new GeminiTransport() : new DefaultTransport(config.agentName);
     backend = new AcpBackend({
       agentName: config.agentName,
@@ -537,7 +537,7 @@ async function handleSessionCommand() {
       process.exit(1);
     }
   }
-  const { sessionList, sessionSpawn, sessionStop, sessionInfo, sessionMessages, sessionAttach, sessionMachines, sessionSend, sessionWait, sessionShare, sessionRalphStart, sessionRalphCancel, sessionRalphStatus, sessionInboxSend, sessionInboxList, sessionInboxRead, sessionInboxReply, sessionInboxClear } = await import('./commands-D5kCHCfX.mjs');
+  const { sessionList, sessionSpawn, sessionArchive, sessionResume, sessionDelete, sessionInfo, sessionMessages, sessionAttach, sessionMachines, sessionSend, sessionWait, sessionShare, sessionRalphStart, sessionRalphCancel, sessionRalphStatus, sessionInboxSend, sessionInboxList, sessionInboxRead, sessionInboxReply, sessionInboxClear } = await import('./commands-BMOelGYC.mjs');
   const parseFlagStr = (flag, shortFlag) => {
     for (let i = 1; i < sessionArgs.length; i++) {
       if ((sessionArgs[i] === flag || shortFlag) && i + 1 < sessionArgs.length) {
@@ -573,7 +573,13 @@ async function handleSessionCommand() {
     const wait = hasFlag("--wait");
     const worktree = hasFlag("--worktree");
     const isolate = hasFlag("--isolate");
-    const permissionMode = parseFlagStr("--permission-mode") || parseFlagStr("-p");
+    let permissionMode = parseFlagStr("--permission-mode") || parseFlagStr("-p");
+    if (!permissionMode && hasFlag("--require-approval")) {
+      permissionMode = "default";
+    }
+    if (!permissionMode) {
+      permissionMode = "bypassPermissions";
+    }
     const securityContextPath = parseFlagStr("--security-context");
     const denyNetwork = hasFlag("--deny-network");
     const parentSessionId = parseFlagStr("--parent");
@@ -597,7 +603,7 @@ async function handleSessionCommand() {
         allowDomain.push(sessionArgs[++i]);
       }
     }
-    const { parseShareArg } = await import('./commands-D5kCHCfX.mjs');
+    const { parseShareArg } = await import('./commands-BMOelGYC.mjs');
     const shareEntries = share.map((s) => parseShareArg(s));
     await sessionSpawn(agent, dir, targetMachineId, {
       message,
@@ -614,12 +620,24 @@ async function handleSessionCommand() {
       tags: tags.length > 0 ? tags : void 0,
       parentSessionId
     });
-  } else if (sessionSubcommand === "stop") {
+  } else if (sessionSubcommand === "archive") {
+    if (!sessionArgs[1]) {
+      console.error("Usage: svamp session archive <session-id>");
+      process.exit(1);
+    }
+    await sessionArchive(sessionArgs[1], targetMachineId);
+  } else if (sessionSubcommand === "resume") {
+    if (!sessionArgs[1]) {
+      console.error("Usage: svamp session resume <session-id>");
+      process.exit(1);
+    }
+    await sessionResume(sessionArgs[1], targetMachineId);
+  } else if (sessionSubcommand === "delete" || sessionSubcommand === "rm") {
     if (!sessionArgs[1]) {
-      console.error("Usage: svamp session stop <session-id>");
+      console.error("Usage: svamp session delete <session-id>");
       process.exit(1);
     }
-    await sessionStop(sessionArgs[1], targetMachineId);
+    await sessionDelete(sessionArgs[1], targetMachineId);
   } else if (sessionSubcommand === "info") {
     if (!sessionArgs[1]) {
       console.error("Usage: svamp session info <session-id>");
@@ -648,16 +666,35 @@ async function handleSessionCommand() {
     await sessionAttach(sessionArgs[1], targetMachineId);
   } else if (sessionSubcommand === "send") {
     if (!sessionArgs[1] || !sessionArgs[2]) {
-      console.error('Usage: svamp session send <session-id> <message> [--subject "..."] [--urgency urgent|normal] [--wait] [--timeout N] [--json]');
+      console.error('Usage: svamp session send <session-id> <message> [--subject "..."] [--urgency urgent|normal] [--wait] [--response] [--btw] [--require-approval] [--timeout N] [--json]');
       process.exit(1);
     }
     await sessionSend(sessionArgs[1], sessionArgs[2], targetMachineId, {
       wait: hasFlag("--wait"),
+      response: hasFlag("--response"),
+      btw: hasFlag("--btw"),
+      requireApproval: hasFlag("--require-approval"),
       timeout: parseFlagInt("--timeout"),
       json: hasFlag("--json"),
       subject: parseFlagStr("--subject"),
       urgency: parseFlagStr("--urgency")
     });
+  } else if (sessionSubcommand === "query") {
+    const dir = sessionArgs[1];
+    const prompt = sessionArgs[2];
+    if (!dir || !prompt) {
+      console.error("Usage: svamp session query <directory> <prompt> [--timeout N] [--keep] [--json] [--permission-mode MODE] [--tag NAME]");
+      console.error("  Spawns a stateless Claude session in <directory>, sends <prompt>, prints the answer, then deletes the session.");
+      process.exit(1);
+    }
+    const { sessionQuery } = await import('./commands-BMOelGYC.mjs');
+    await sessionQuery(dir, prompt, targetMachineId, {
+      timeout: parseFlagInt("--timeout"),
+      json: hasFlag("--json"),
+      keep: hasFlag("--keep"),
+      permissionMode: parseFlagStr("--permission-mode"),
+      tag: parseFlagStr("--tag")
+    });
   } else if (sessionSubcommand === "wait") {
     if (!sessionArgs[1]) {
       console.error("Usage: svamp session wait <session-id> [--timeout N] [--json]");
@@ -683,7 +720,7 @@ async function handleSessionCommand() {
       console.error("Usage: svamp session approve <session-id> [request-id] [--json]");
       process.exit(1);
     }
-    const { sessionApprove } = await import('./commands-D5kCHCfX.mjs');
+    const { sessionApprove } = await import('./commands-BMOelGYC.mjs');
     const approveReqId = sessionArgs[2] && !sessionArgs[2].startsWith("--") ? sessionArgs[2] : void 0;
     await sessionApprove(sessionArgs[1], approveReqId, targetMachineId, {
       json: hasFlag("--json")
@@ -693,7 +730,7 @@ async function handleSessionCommand() {
       console.error("Usage: svamp session deny <session-id> [request-id] [--json]");
       process.exit(1);
     }
-    const { sessionDeny } = await import('./commands-D5kCHCfX.mjs');
+    const { sessionDeny } = await import('./commands-BMOelGYC.mjs');
     const denyReqId = sessionArgs[2] && !sessionArgs[2].startsWith("--") ? sessionArgs[2] : void 0;
     await sessionDeny(sessionArgs[1], denyReqId, targetMachineId, {
       json: hasFlag("--json")
@@ -729,7 +766,7 @@ async function handleSessionCommand() {
       console.error("Usage: svamp session set-title <title>");
       process.exit(1);
     }
-    const { sessionSetTitle } = await import('./agentCommands-QnPGJFY-.mjs');
+    const { sessionSetTitle } = await import('./agentCommands-BaQIO1T2.mjs');
     await sessionSetTitle(title);
   } else if (sessionSubcommand === "set-link") {
     const url = sessionArgs[1];
@@ -738,7 +775,7 @@ async function handleSessionCommand() {
       process.exit(1);
     }
     const label = sessionArgs[2] && !sessionArgs[2].startsWith("--") ? sessionArgs[2] : void 0;
-    const { sessionSetLink } = await import('./agentCommands-QnPGJFY-.mjs');
+    const { sessionSetLink } = await import('./agentCommands-BaQIO1T2.mjs');
     await sessionSetLink(url, label);
   } else if (sessionSubcommand === "notify") {
     const message = sessionArgs[1];
@@ -747,7 +784,7 @@ async function handleSessionCommand() {
       process.exit(1);
     }
     const level = parseFlagStr("--level") || "info";
-    const { sessionNotify } = await import('./agentCommands-QnPGJFY-.mjs');
+    const { sessionNotify } = await import('./agentCommands-BaQIO1T2.mjs');
     await sessionNotify(message, level);
   } else if (sessionSubcommand === "broadcast") {
     const action = sessionArgs[1];
@@ -755,7 +792,7 @@ async function handleSessionCommand() {
       console.error("Usage: svamp session broadcast <action> [args...]\nActions: open-canvas <url> [label], close-canvas, toast <message>");
       process.exit(1);
     }
-    const { sessionBroadcast } = await import('./agentCommands-QnPGJFY-.mjs');
+    const { sessionBroadcast } = await import('./agentCommands-BaQIO1T2.mjs');
     await sessionBroadcast(action, sessionArgs.slice(2).filter((a) => !a.startsWith("--")));
   } else if (sessionSubcommand === "inbox") {
     const inboxSubcmd = sessionArgs[1];
@@ -766,7 +803,7 @@ async function handleSessionCommand() {
         process.exit(1);
       }
       if (agentSessionId) {
-        const { inboxSend } = await import('./agentCommands-QnPGJFY-.mjs');
+        const { inboxSend } = await import('./agentCommands-BaQIO1T2.mjs');
         await inboxSend(sessionArgs[2], {
           body: sessionArgs[3],
           subject: parseFlagStr("--subject"),
@@ -781,7 +818,7 @@ async function handleSessionCommand() {
       }
     } else if (inboxSubcmd === "list" || inboxSubcmd === "ls") {
       if (agentSessionId && !sessionArgs[2]) {
-        const { inboxList } = await import('./agentCommands-QnPGJFY-.mjs');
+        const { inboxList } = await import('./agentCommands-BaQIO1T2.mjs');
         await inboxList({
           unread: hasFlag("--unread"),
           limit: parseFlagInt("--limit"),
@@ -803,7 +840,7 @@ async function handleSessionCommand() {
         process.exit(1);
       }
       if (agentSessionId && !sessionArgs[3]) {
-        const { inboxList } = await import('./agentCommands-QnPGJFY-.mjs');
+        const { inboxList } = await import('./agentCommands-BaQIO1T2.mjs');
         await sessionInboxRead(agentSessionId, sessionArgs[2], targetMachineId);
       } else if (sessionArgs[3]) {
         await sessionInboxRead(sessionArgs[2], sessionArgs[3], targetMachineId);
@@ -813,7 +850,7 @@ async function handleSessionCommand() {
       }
     } else if (inboxSubcmd === "reply") {
       if (agentSessionId && sessionArgs[2] && sessionArgs[3] && !sessionArgs[4]) {
-        const { inboxReply } = await import('./agentCommands-QnPGJFY-.mjs');
+        const { inboxReply } = await import('./agentCommands-BaQIO1T2.mjs');
         await inboxReply(sessionArgs[2], sessionArgs[3]);
       } else if (sessionArgs[2] && sessionArgs[3] && sessionArgs[4]) {
         await sessionInboxReply(sessionArgs[2], sessionArgs[3], sessionArgs[4], targetMachineId);
@@ -849,7 +886,7 @@ async function handleMachineCommand() {
     return;
   }
   if (machineSubcommand === "share") {
-    const { machineShare } = await import('./commands-D5kCHCfX.mjs');
+    const { machineShare } = await import('./commands-BMOelGYC.mjs');
     let machineId;
     const shareArgs = [];
     for (let i = 1; i < machineArgs.length; i++) {
@@ -879,7 +916,7 @@ async function handleMachineCommand() {
     }
     await machineShare(machineId, { add, remove, list, configPath, showConfig });
   } else if (machineSubcommand === "exec") {
-    const { machineExec } = await import('./commands-D5kCHCfX.mjs');
+    const { machineExec } = await import('./commands-BMOelGYC.mjs');
     let machineId;
     let cwd;
     const cmdParts = [];
@@ -899,7 +936,7 @@ async function handleMachineCommand() {
     }
     await machineExec(machineId, command, cwd);
   } else if (machineSubcommand === "info") {
-    const { machineInfo } = await import('./commands-D5kCHCfX.mjs');
+    const { machineInfo } = await import('./commands-BMOelGYC.mjs');
     let machineId;
     for (let i = 1; i < machineArgs.length; i++) {
       if ((machineArgs[i] === "--machine" || machineArgs[i] === "-m") && i + 1 < machineArgs.length) {
@@ -919,10 +956,10 @@ async function handleMachineCommand() {
         level = machineArgs[++i];
       }
     }
-    const { machineNotify } = await import('./agentCommands-QnPGJFY-.mjs');
+    const { machineNotify } = await import('./agentCommands-BaQIO1T2.mjs');
     await machineNotify(message, level);
   } else if (machineSubcommand === "ls") {
-    const { machineLs } = await import('./commands-D5kCHCfX.mjs');
+    const { machineLs } = await import('./commands-BMOelGYC.mjs');
     let machineId;
     let showHidden = false;
     let path;
@@ -1295,12 +1332,12 @@ function printHelp() {
   console.log(`
 svamp \u2014 AI workspace on Hypha Cloud
 
-Quick start \u2014 spawn an agent to do a task (use -p bypassPermissions to run autonomously):
-  svamp session spawn claude -d ./project -p bypassPermissions --message "fix tests" --wait
+Quick start \u2014 spawn an agent to do a task (autonomous by default):
+  svamp session spawn claude -d ./project --message "fix tests" --wait
 
-  Note: without -p bypassPermissions the agent PAUSES waiting for human approval of each
-  tool use. This will cause it to hang in automated/agent contexts. Use bypassPermissions
-  for autonomous work, or "default" only when a human is actively watching.
+  Note: as of 0.2.69 spawn defaults to permission mode "bypassPermissions" so the
+  child agent doesn't get stuck on tool-approval prompts. Pass --require-approval
+  (or -p default / -p acceptEdits) when you want a human to gate tool use.
 
 Commands:
   svamp                              Start interactive Claude session (synced to cloud)
@@ -1312,12 +1349,15 @@ Commands:
 
   Session management (requires daemon running):
   svamp session spawn <agent> [opts] Spawn a new agent session (agents: claude, gemini, codex)
-  svamp session send <id> <message>  Send message to a session (--wait to block until done)
+  svamp session send <id> <message>  Send message to a session (--wait, --response, --btw)
+  svamp session query <dir> <prompt> Stateless one-shot: spawn \u2192 ask \u2192 answer \u2192 delete
   svamp session wait <id>            Wait for agent to become idle
   svamp session messages <id>        Show message history (--last N, --json, --raw)
   svamp session info <id>            Show session status & pending permissions
   svamp session list                 List sessions
-  svamp session stop <id>            Stop a session
+  svamp session archive <id>         Archive a session (preserves history, resumable later)
+  svamp session resume <id>          Resume an archived session
+  svamp session delete <id>          Permanently delete a session (cannot be undone)
   svamp session attach <id>          Attach interactive terminal (stdin/stdout)
   svamp session approve/deny <id>    Approve or deny pending permission requests
   svamp session --help               Show ALL session commands and detailed options
@@ -1389,7 +1429,7 @@ async function applyClaudeAuthFlags(argv) {
       "--use-hypha-proxy, --use-claude-login, and --anthropic-base-url/--anthropic-api-key are mutually exclusive"
     );
   }
-  const mod = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.t; });
+  const mod = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.t; });
   if (hasHypha) {
     mod.setClaudeAuthHyphaProxy();
     console.log("Claude auth configured: hypha-proxy (uses HYPHA_TOKEN live at each spawn).");
@@ -1427,7 +1467,7 @@ async function applyDaemonShareFlag(argv) {
     }
   }
   if (collected.length === 0) return;
-  const { updateEnvFile } = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.t; });
+  const { updateEnvFile } = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.t; });
   const seen = /* @__PURE__ */ new Set();
   const deduped = collected.filter((e) => {
     const k = e.toLowerCase();
@@ -1440,7 +1480,7 @@ async function applyDaemonShareFlag(argv) {
 }
 async function handleDaemonAuthCommand(argv) {
   const sub = (argv[0] || "status").toLowerCase();
-  const mod = await import('./run-HuBXfVSz.mjs').then(function (n) { return n.t; });
+  const mod = await import('./run-BqAe7GgA.mjs').then(function (n) { return n.t; });
   if (sub === "--help" || sub === "-h" || sub === "help") {
     console.log(`
 svamp daemon auth \u2014 Configure how Claude subprocesses authenticate
@@ -1506,14 +1546,14 @@ svamp session \u2014 Spawn and manage AI agent sessions
 
 QUICK START \u2014 Spawn a session, give it a task, get results:
 
-  # One-liner: spawn agent, send task, wait for completion
-  svamp session spawn claude -d ./my-project -p bypassPermissions \\
-    --message "fix the failing tests" --wait
+  # One-liner: spawn agent, send task, wait for completion (autonomous by default)
+  svamp session spawn claude -d ./my-project --message "fix the failing tests" --wait
 
   # The command prints the session ID (e.g., "abc12345-..."). Use it to:
   svamp session messages abc1 --last 10         # read output (prefix match on ID)
   svamp session send abc1 "now run lint" --wait  # send follow-up, wait for done
-  svamp session stop abc1                        # stop when finished
+  svamp session archive abc1                     # archive when finished (resumable)
+  svamp session resume abc1                      # bring an archived session back
 
   # Spawn on a remote/cloud machine:
   svamp session spawn claude -d /workspace -m cloud-box --message "deploy" --wait
@@ -1530,14 +1570,32 @@ COMMANDS:
 
   Lifecycle:
     spawn <agent> [-d <path>] [options]   Spawn a new agent session
-    stop <id>                             Stop a running session
+    archive <id>                          Archive a session (resumable; preserves --resume token)
+    resume <id>                           Resume an archived session (spawns agent with --resume)
+    delete <id>                           Permanently delete a session (cannot be undone)
     list [--active] [--json]              List sessions (alias: ls)
     machines                              List discoverable machines
     info <id> [--json]                    Show status & pending permissions
 
   Communicate:
-    send <id> <message> [--wait] [--timeout N] [--json]
-                                          Send a message to a running session
+    send <id> <message> [--wait] [--response] [--btw] [--require-approval] [--timeout N] [--json]
+                                          Send a message to a running session.
+                                            --wait              block until the agent goes idle
+                                            --response          block AND print the agent's
+                                                                text answer (implies --wait)
+                                            --btw               side-channel one-shot query via
+                                                                /btw \u2014 does NOT touch the
+                                                                running session's context window
+                                            --require-approval  do NOT pre-flight the target to
+                                                                bypassPermissions. Without this,
+                                                                send with --wait/--response auto-
+                                                                ensures bypass so the agent does
+                                                                not stall on tool prompts.
+    query <directory> <prompt> [--timeout N] [--keep] [--json] [--permission-mode MODE] [--tag NAME]
+                                          Stateless one-shot: spawn fresh Claude in
+                                          <directory>, send <prompt>, print answer,
+                                          delete the session. No existing session is
+                                          affected. Use for reproducible Q&A.
     messages <id> [--last N] [--json]     Read message history (alias: msgs)
     wait <id> [--timeout N] [--json]      Wait for agent to become idle
     attach <id>                           Attach interactive terminal (stdin/stdout)
@@ -1566,7 +1624,9 @@ COMMANDS:
 
 SPAWN OPTIONS:
   -d, --directory <path>          Working directory (REQUIRED for meaningful work)
-  -p, --permission-mode <mode>    Permission mode (see below). Default: "default"
+  -p, --permission-mode <mode>    Permission mode (see below). Default: "bypassPermissions"
+  --require-approval              Opt into human-in-the-loop approval (alias for -p default).
+                                  Without this flag, the agent runs autonomously.
   --message <msg>                 Send this message to the agent immediately after spawn
   --wait                          Block until agent finishes (idle). Combine with --message
                                   for fire-and-forget: spawn \u2192 task \u2192 wait \u2192 done.
@@ -1576,15 +1636,14 @@ SPAWN OPTIONS:
   --parent <sessionId>            Set parent session (auto-set from SVAMP_SESSION_ID env)
 
 PERMISSION MODES:
+  bypassPermissions    \u2605 Default. Auto-approve everything. No prompts, no pauses.
+                       Right choice for automation, CI, agent-spawning-agent.
+  acceptEdits          Auto-approve file edits. Still pauses for bash & dangerous tools.
   default              \u26A0 Agent PAUSES and waits for human approval before each tool use.
                        The agent will be stuck (exit code 2) until you run approve/deny.
-                       DO NOT use default mode in automated pipelines \u2014 the agent will hang.
-  acceptEdits          Auto-approve file edits. Still pauses for bash & dangerous tools.
-  bypassPermissions    Auto-approve everything. No prompts, no pauses. Fully autonomous.
-                       Use this for automation, CI, or when spawning from another agent.
+                       Use only when a human is actively watching the session.
 
-  \u26A1 For agents/scripts: ALWAYS pass -p bypassPermissions unless you have a human
-     monitoring the session who can approve/deny tool requests in real time.
+  Tip: pass --require-approval (or -p default) when you want a human gate.
 
 PERMISSION WORKFLOW (only relevant for "default" and "acceptEdits" modes):
   1. svamp session wait <id> --json    \u2192 exit code 2 means permission pending
@@ -1635,32 +1694,32 @@ ID MATCHING:
 EXAMPLES:
 
   # === Common: Spawn agent to do a task and wait ===
-  svamp session spawn claude -d ./my-project -p bypassPermissions \\
+  # Default is bypassPermissions \u2014 no -p flag needed for autonomous runs.
+  svamp session spawn claude -d ./my-project \\
     --message "fix all TypeScript errors, run tsc to verify" --wait
 
   # === Multi-step: Spawn, then send messages interactively ===
-  ID=$(svamp session spawn claude -d ./proj -p bypassPermissions)
+  ID=$(svamp session spawn claude -d ./proj)
   svamp session send $ID "first, read the README" --wait
   svamp session send $ID "now implement the feature described there" --wait
   svamp session messages $ID --last 20
 
   # === Spawn child session from another agent (e.g., in a bash tool) ===
-  # Use -p bypassPermissions so the child doesn't get stuck on approvals.
-  # Use --wait so your script blocks until the child finishes.
-  svamp session spawn claude -d /tmp/test-project -p bypassPermissions \\
+  # bypassPermissions is the default; --wait blocks until done.
+  svamp session spawn claude -d /tmp/test-project \\
     --message "run the test suite and report results" --wait
-  # Then read the child's output:
   svamp session messages <child-id> --last 5
 
-  # === Monitor with permissions (default mode) ===
-  svamp session spawn claude -d ./proj --message "refactor auth module"
+  # === Human-in-the-loop: require approval for every tool ===
+  svamp session spawn claude -d ./proj --require-approval \\
+    --message "refactor auth module"
   svamp session wait abc1 --json       # exit code 2 = permission pending
   svamp session approve abc1           # approve all pending
   svamp session wait abc1              # wait for completion
 
   # === Spawn on a remote machine ===
   svamp session spawn claude -d /workspace -m my-cloud-box \\
-    -p bypassPermissions --message "deploy to staging" --wait
+    --message "deploy to staging" --wait
 
   # === Isolated session with network restrictions ===
   svamp session spawn claude -d /tmp/sandbox --isolate --deny-network