@lazyingart/agintiflow 0.20.56 → 0.20.58

package/README.md

@@ -73,6 +73,16 @@ aginti auth venice
 aginti login grsai
 ```
 
+Provider signup and key pages:
+
+| Provider | Register / key page | API base URL used by AgInTiFlow |
+| --- | --- | --- |
+| DeepSeek | [https://platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) | `https://api.deepseek.com` |
+| Venice | [https://venice.ai/settings/api](https://venice.ai/settings/api) | `https://api.venice.ai/api/v1` |
+| OpenAI | [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys) | `https://api.openai.com/v1` |
+| Qwen / DashScope | [https://bailian.console.aliyun.com/](https://bailian.console.aliyun.com/) | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
+| GRS AI image tools | [https://grsai.ai/dashboard/api-keys](https://grsai.ai/dashboard/api-keys) | Configure with `/auxiliary grsai` or `aginti login grsai` |
+
 Launch the web UI from the same project:
 
 ```bash
@@ -133,6 +143,31 @@ aginti --resume <session-id> \
   "Take a fresh screenshot of the running app in the emulator, save it with a durable filename in this project, and keep git status clean."
 ```
 
+Permission behavior is intentionally consistent: writes inside the current project are allowed through file tools, network/setup runs are normal in approved Docker workspace mode, and outside-project or trusted-host actions stop with a clear blocker plus a suggested rerun command. See [runtime modes and autonomy](docs/runtime-modes-and-autonomy.md) for the full contract.
+
+## Permission Recipes
+
+Use these when you want explicit control instead of the default interactive policy:
+
+| Mode | Command | What it permits |
+| --- | --- | --- |
+| Strict inspection | `aginti --sandbox-mode docker-readonly --package-install-policy block --allow-shell --no-file-tools --no-web-search "inspect this project without edits"` | Enforced read-only project inspection through shell commands such as `ls`, `rg`, `cat`, and test commands that do not write. No file-tool writes, web calls, workspace writes, or installs. |
+| Full write in current folder | `aginti --sandbox-mode docker-workspace --package-install-policy allow --approve-package-installs --allow-shell --allow-file-tools "build and test this project"` | Read/write inside the current project folder, run network/setup commands in Docker, keep host safer. |
+| Full host computer access | `aginti --sandbox-mode host --package-install-policy allow --approve-package-installs --allow-shell --allow-file-tools --allow-destructive "perform the trusted host maintenance task"` | Direct host shell and destructive actions. Use only when you trust the task and want whole-host access. |
+
+For resume:
+
+```bash
+aginti --resume <session-id> \
+  --sandbox-mode host \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  --allow-destructive \
+  "continue with trusted host access"
+```
+
 ## Real Screenshots
 
 | CLI launch | Web app overview |

package/docs/runtime-modes-and-autonomy.md

@@ -42,6 +42,77 @@ Docker package installs are safe when they match the sandbox contract.
 
 This is why a task can safely install Python packages in Docker, but cannot keep an interactive tmux server alive inside a one-shot Docker command.
 
+## Permission Contract
+
+The runtime must be consistent when an action is not permitted. A blocked action should not become a loop of slight command variants, and a failed setup step should not be reported as success just because a stale folder already exists.
+
+Current contract:
+
+- Workspace file tools may read and write inside the configured project folder when file tools are enabled.
+- Workspace writes outside that folder, secret paths, `.git` internals, and dependency folders such as `node_modules` are blocked.
+- `git clone`, `git fetch`, `git pull --ff-only`, `git push`, `curl`, and `wget` are classified as network operations.
+- Network/setup commands are allowed in `docker-workspace` only when package installs are approved.
+- Host `sudo` and host OS package installs are not automatic. The agent should ask the user to run a manual command or switch to a safer Docker setup.
+- Destructive host shell/git operations need explicit trusted host mode.
+
+When a tool is blocked, the tool result includes `permissionAdvice` with three choices: refuse/stop, approve a safer rerun, or switch to a trusted host run. The model prompt requires the agent to present that blocker and avoid retrying variants until the user approves a path.
+
+The common controlled rerun shape is:
+
+```bash
+aginti --resume <session-id> \
+  --cwd /path/to/project \
+  --sandbox-mode docker-workspace \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  "Continue after approval and verify the output was created in this run."
+```
+
+Three practical permission recipes:
+
+```bash
+# Strict inspection: enforced read-only shell inspection, no file-tool writes, no web, no installs.
+aginti --sandbox-mode docker-readonly \
+  --package-install-policy block \
+  --allow-shell \
+  --no-file-tools \
+  --no-web-search \
+  "inspect this project without edits"
+
+# Full write in the current project folder, with setup commands isolated in Docker.
+aginti --sandbox-mode docker-workspace \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  "build and test this project"
+
+# Full host computer access for trusted maintenance.
+aginti --sandbox-mode host \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  --allow-destructive \
+  "perform the trusted host maintenance task"
+```
+
+For host-only work, use the stricter trusted form deliberately:
+
+```bash
+aginti --resume <session-id> \
+  --cwd /path/to/project \
+  --sandbox-mode host \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  --allow-destructive \
+  "Continue after trusted host approval. Inspect first and keep unrelated files untouched."
+```
+
 ## Recommended Defaults
 
 Default daily coding:
@@ -103,4 +174,3 @@ The documentation should be maintained as product code:
 - Add smoke tests when a workflow becomes behavior, not just guidance.
 - Update `AGINTI.md` for project-specific operating memory.
 - Treat docs changes as part of the release checklist before publishing npm.
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.56",
+  "version": "0.20.58",
   "type": "module",
   "description": "Low-cost, project-aware Web and CLI agents with DeepSeek/Venice/OpenAI routing, visible tool calls, durable sessions, scouts, AAPS, SCS, and guarded local execution.",
   "license": "Apache-2.0",

package/public/app.js

@@ -930,6 +930,14 @@ function renderWorkspacePanel(workspace = lastWorkspace, activity = lastWorkspac
       const label = blocked ? t("blockedLabel") : t("changedLabel");
       const path = escapeHtml(item.path || "");
       const reason = blocked ? `<div class="subtle">${escapeHtml(item.reason || "")}</div>` : "";
+      const advice =
+        blocked && item.permissionAdvice
+          ? `<div class="subtle"><strong>${escapeHtml(item.permissionAdvice.summary || "Permission advice")}</strong>${
+              item.permissionAdvice.suggestedCommand
+                ? `<br /><code>${escapeHtml(item.permissionAdvice.suggestedCommand)}</code>`
+                : ""
+            }</div>`
+          : "";
       const diff = item.diff ? `<pre class="change-diff">${renderDiffHtml(item.diff, 1200)}</pre>` : "";
       const hashes =
         item.beforeHash || item.afterHash
@@ -944,6 +952,7 @@ function renderWorkspacePanel(workspace = lastWorkspace, activity = lastWorkspac
           </div>
           <strong class="change-path">${path}</strong>
           ${reason}
+          ${advice}
           ${hashes}
           ${diff}
         </article>

package/scripts/smoke-auto-update.js

@@ -53,8 +53,10 @@ assert(skipped.skipped === "source-checkout", "source checkout update guard fail
 const tempHome = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-auto-update-"));
 const previousHome = process.env.AGINTIFLOW_HOME;
 const previousStartupInterval = process.env.AGINTIFLOW_AUTO_UPDATE_STARTUP_INTERVAL_MS;
+const previousCi = process.env.CI;
 process.env.AGINTIFLOW_HOME = tempHome;
 process.env.AGINTIFLOW_AUTO_UPDATE_STARTUP_INTERVAL_MS = String(24 * 60 * 60 * 1000);
+delete process.env.CI;
 await fs.mkdir(tempHome, { recursive: true });
 await fs.writeFile(
   path.join(tempHome, "update-check.json"),
@@ -96,5 +98,7 @@ if (previousHome === undefined) delete process.env.AGINTIFLOW_HOME;
 else process.env.AGINTIFLOW_HOME = previousHome;
 if (previousStartupInterval === undefined) delete process.env.AGINTIFLOW_AUTO_UPDATE_STARTUP_INTERVAL_MS;
 else process.env.AGINTIFLOW_AUTO_UPDATE_STARTUP_INTERVAL_MS = previousStartupInterval;
+if (previousCi === undefined) delete process.env.CI;
+else process.env.CI = previousCi;
 
 console.log("auto-update smoke ok");

package/scripts/smoke-coding-tools.js

@@ -6,9 +6,11 @@ import { fileURLToPath } from "node:url";
 import { repairModelMessageHistory, runAgent } from "../src/agent-runner.js";
 import { resolveRuntimeConfig } from "../src/config.js";
 import { readCodebaseMap } from "../src/codebase-map.js";
+import { evaluateCommandPolicy } from "../src/command-policy.js";
 import { engineeringGuidanceForTask, recommendedMaxStepsForTask } from "../src/engineering-guidance.js";
 import { selectModelRoute } from "../src/model-routing.js";
 import { listParallelScouts, runParallelScouts, shouldRunParallelScouts } from "../src/parallel-scouts.js";
+import { buildFailedCommandAdvice, buildPermissionAdvice } from "../src/permission-advice.js";
 import { SessionStore } from "../src/session-store.js";
 import { searchWeb } from "../src/web-search.js";
 import { executeWorkspaceTool } from "../src/workspace-tools.js";
@@ -202,6 +204,48 @@ try {
     guidance.includes("find . -type d -name __pycache__"),
     "engineering guidance did not include recursive Python transient checks"
   );
+  const dockerWorkspacePolicy = {
+    allowShellTool: true,
+    useDockerSandbox: true,
+    sandboxMode: "docker-workspace",
+    packageInstallPolicy: "allow",
+    commandCwd: workspace,
+  };
+  const curlPolicy = evaluateCommandPolicy("curl -s -o /dev/null -w '%{http_code}' https://github.com/lazyingart/AgInTiFlow.git", dockerWorkspacePolicy);
+  assert(curlPolicy.allowed, "curl URL probe with flags should be allowed in docker-workspace allow mode");
+  assert(curlPolicy.needsNetwork, "curl URL probe with flags was not classified as network");
+  const clonePolicy = evaluateCommandPolicy("git clone https://github.com/lazyingart/AgInTiFlow.git", dockerWorkspacePolicy);
+  assert(clonePolicy.allowed, "git clone should be allowed in docker-workspace allow mode");
+  assert(clonePolicy.needsNetwork, "git clone was not classified as network");
+  assert(clonePolicy.writesWorkspace, "git clone was not classified as workspace-writing");
+  const unsafeCloneTarget = evaluateCommandPolicy("git clone https://github.com/lazyingart/AgInTiFlow.git ../AgInTiFlow", dockerWorkspacePolicy);
+  assert(!unsafeCloneTarget.allowed, "git clone outside the workspace should be blocked");
+  const blockedClonePolicy = evaluateCommandPolicy("git clone https://github.com/lazyingart/AgInTiFlow.git", {
+    ...dockerWorkspacePolicy,
+    packageInstallPolicy: "block",
+  });
+  assert(!blockedClonePolicy.allowed, "git clone should be blocked when Docker package/network setup is blocked");
+  const permissionAdvice = buildPermissionAdvice({
+    toolName: "run_command",
+    args: { command: "git clone https://github.com/lazyingart/AgInTiFlow.git" },
+    guard: blockedClonePolicy,
+    config: dockerWorkspacePolicy,
+    state: { sessionId: "coding-policy-smoke" },
+  });
+  assert(permissionAdvice.suggestedCommand.includes("coding-policy-smoke"), "permission advice did not include resume session id");
+  assert(permissionAdvice.suggestedCommand.includes("--sandbox-mode docker-workspace"), "permission advice did not suggest docker-workspace recovery");
+  const failedNetworkAdvice = buildFailedCommandAdvice({
+    args: { command: "git clone https://github.com/lazyingart/AgInTiFlow.git" },
+    commandPolicy: clonePolicy,
+    commandResult: { ok: false, stderr: "fatal: unable to access 'https://github.com/lazyingart/AgInTiFlow.git/': Could not resolve host: github.com" },
+    config: dockerWorkspacePolicy,
+    state: { sessionId: "coding-network-smoke" },
+  });
+  assert(failedNetworkAdvice?.failureKind === "network", "network failure advice was not generated");
+  assert(
+    failedNetworkAdvice.instruction.includes("Stop and present this blocker"),
+    "network failure advice did not tell the model to stop and ask"
+  );
   assert(
     shouldRunParallelScouts(
       {
@@ -459,6 +503,8 @@ try {
           "large_profile_pro_route",
           "auto_system_pro_route",
           "auto_engineering_guidance",
+          "command_policy_git_clone_network",
+          "permission_recovery_advice",
           "parallel_scout_trigger",
           "parallel_scout_roster",
           "parallel_scout_count_clamp",

package/src/agent-runner.js

@@ -27,6 +27,7 @@ import { hostShellOption, platformInfo, platformLabel } from "./platform.js";
 import { captureTmuxPane, listTmuxSessions, sendTmuxKeys, startTmuxSession } from "./tmux-tools.js";
 import { languageInstruction } from "./i18n.js";
 import { flushHousekeeping } from "./housekeeping.js";
+import { buildFailedCommandAdvice, buildPermissionAdvice } from "./permission-advice.js";
 import {
   buildSupervisorInstruction,
   createScsPlan,
@@ -358,6 +359,8 @@ async function createInitialState(config, sessionId) {
               ? `A shell command tool is available inside Docker sandbox mode ${config.sandboxMode}. Docker workspace mode with approved package installs supports broader setup and network commands. The project is mounted at /workspace and the persistent agent toolchain is mounted at /aginti-env with caches under /aginti-cache.`
               : `A host shell command tool is available under the configured trust policy on ${platformLabel(platform)}. On native Windows, prefer PowerShell/cmd-compatible commands or switch to WSL/Docker for bash-like toolchains.`
             : "No shell command tool is available.",
+          "Permission contract: current-workspace file writes are allowed through workspace file tools when enabled. Outside-workspace paths, host sudo, host OS package installs, destructive git/shell actions, and blocked network/setup must not be bypassed by retrying variants. If a tool result includes permissionAdvice or suggestedCommand, stop, explain the blocker, and ask the user to approve/rerun that mode or choose a safer workspace-relative path.",
+          "If an operation fails but a directory, artifact, or file already exists, treat it as pre-existing unless you have evidence this run created or updated it. Verify expected outputs before claiming success.",
           config.allowShellTool
             ? "Host tmux tools are available for long-running terminals: list sessions, capture panes, send safe keys/text, and start detached sessions. Prefer these tools for monitoring long installs/tests/dev servers without blocking; capture before sending input and never send secrets or sudo passwords. Do not start or install tmux inside Docker run_command containers because those containers are short-lived."
             : "",
@@ -856,12 +859,20 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
   });
 
   if (!guard.allowed) {
+    const permissionAdvice = buildPermissionAdvice({
+      toolName: toolCall.function.name,
+      args: safeArgs,
+      guard,
+      config,
+      state,
+    });
     await store.appendEvent("tool.blocked", {
       toolName: toolCall.function.name,
       args: safeArgs,
       reason: guard.reason,
       category: guard.category,
       needsApproval: guard.needsApproval,
+      permissionAdvice,
     });
     observers.event("tool.blocked", {
       toolName: toolCall.function.name,
@@ -869,6 +880,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
       reason: guard.reason,
       category: guard.category,
       needsApproval: guard.needsApproval,
+      permissionAdvice,
     });
     return {
       ok: false,
@@ -876,6 +888,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
       reason: guard.reason,
       category: guard.category,
       needsApproval: guard.needsApproval,
+      permissionAdvice,
       toolName: toolCall.function.name,
       args: safeArgs,
     };
@@ -1014,17 +1027,27 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
         const result = await executeWorkspaceTool(toolCall.function.name, args, config);
         const eventResult = sanitizeToolResult(result);
         if (result.blocked) {
+          const permissionAdvice = buildPermissionAdvice({
+            toolName: toolCall.function.name,
+            args: safeArgs,
+            guard: result,
+            config,
+            state,
+          });
+          result.permissionAdvice = permissionAdvice;
           await store.appendEvent("tool.blocked", {
             toolName: toolCall.function.name,
             args: safeArgs,
             reason: result.reason,
             category: result.category,
+            permissionAdvice,
           });
           observers.event("tool.blocked", {
             toolName: toolCall.function.name,
             args: safeArgs,
             reason: result.reason,
             category: result.category,
+            permissionAdvice,
           });
           return result;
         }
@@ -1049,6 +1072,15 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
           await ensureDockerSandboxReady(config, observers);
         }
         const commandResult = await runShellCommand(String(args.command), config, policy);
+        const permissionAdvice = commandResult.ok === false
+          ? buildFailedCommandAdvice({
+              args: safeArgs,
+              commandPolicy: policy,
+              commandResult,
+              config,
+              state,
+            })
+          : null;
         const result = {
           ok: commandResult.ok !== false,
           toolName: "run_command",
@@ -1062,6 +1094,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
             writesWorkspace: Boolean(policy.writesWorkspace),
           },
           ...commandResult,
+          ...(permissionAdvice ? { permissionAdvice } : {}),
         };
         await store.appendEvent("tool.completed", result);
         observers.event("tool.completed", result);
@@ -1743,6 +1776,7 @@ export async function runAgent(config) {
             commandPolicy: toolResult.commandPolicy,
             blocked: Boolean(toolResult.blocked),
             error: toolResult.error || toolResult.reason || "",
+            permissionAdvice: toolResult.permissionAdvice || null,
           });
         }
 

package/src/auth-onboarding.js

@@ -41,13 +41,14 @@ export const MAIN_AUTH_PROVIDERS = [
     label: "Qwen",
     keyName: "QWEN_API_KEY",
     description: "Qwen OpenAI-compatible route",
+    keyUrl: "https://bailian.console.aliyun.com/",
   },
   {
     id: "venice",
     label: "Venice",
     keyName: "VENICE_API_KEY",
     description: "Venice OpenAI-compatible text and image routes",
-    keyUrl: "https://venice.ai",
+    keyUrl: "https://venice.ai/settings/api",
   },
 ];
 
@@ -56,6 +57,7 @@ const AUXILIARY_AUTH_PROVIDER = {
   label: "GRS AI / Nano Banana",
   keyName: "GRSAI",
   description: "optional image generation",
+  keyUrl: "https://grsai.ai/dashboard/api-keys",
 };
 
 const AUTH_ALIASES = {

package/src/command-policy.js

@@ -42,8 +42,8 @@ const SAFE_WORKSPACE_WRITE_PATTERNS = [/^mkdir\s+-p\s+[-\w./]+$/];
 const PERMISSION_CHANGE_PATTERNS = [/^(?:sudo\s+)?chmod\s+[-+=,rwxugoXst0-7]+\s+[-\w./]+$/];
 
 const NETWORK_FETCH_PATTERNS = [
-  /^curl\s+(?:-[A-Za-z0-9]*\s+)*https?:\/\/\S+(?:\s+-o\s+[-\w./]+)?$/,
-  /^wget\s+(?:-[A-Za-z0-9]*\s+)*(?:-O\s+[-\w./]+\s+)?https?:\/\/\S+$/,
+  /^curl\b(?=[\s\S]*https?:\/\/\S+)[\s\S]*$/,
+  /^wget\b(?=[\s\S]*https?:\/\/\S+)[\s\S]*$/,
 ];
 
 const GIT_WORKFLOW_PATTERNS = [
@@ -163,6 +163,29 @@ function isSafeVirtualWorkspaceDir(value) {
   return isSafeRelativeDir(normalized.replace(/^\/workspace\//, ""));
 }
 
+function classifyGitClone(normalized) {
+  const match = normalized.match(
+    /^git\s+clone(?:\s+--depth\s+\d+)?(?:\s+--branch\s+[-\w./]+)?\s+(https:\/\/\S+)(?:\s+([-\w./]+))?$/
+  );
+  if (!match) return null;
+
+  const target = match[2] || "";
+  if (target && !isSafeRelativeDir(target) && !isSafeVirtualWorkspaceDir(target)) {
+    return {
+      category: "blocked",
+      reason: `git clone target must be a safe workspace-relative directory: ${target}`,
+    };
+  }
+
+  return {
+    category: "git-remote",
+    needsNetwork: true,
+    writesWorkspace: true,
+    virtualWorkspacePath: Boolean(target && isSafeVirtualWorkspaceDir(target)),
+    reason: "Git clone writes into the workspace and requires network access.",
+  };
+}
+
 function classifySimpleCommand(normalized) {
   if (ALWAYS_BLOCKED_PATTERNS.some((pattern) => pattern.test(normalized))) {
     return { category: "blocked", reason: "Command is blocked because it may expose secrets or publish packages." };
@@ -205,6 +228,8 @@ function classifySimpleCommand(normalized) {
       reason: "Git workflow command. Agent should run git status/diff first and stop on conflicts or divergence.",
     };
   }
+  const gitCloneClassification = classifyGitClone(normalized);
+  if (gitCloneClassification) return gitCloneClassification;
 
   const lowered = ` ${normalized.toLowerCase()} `;
   if (BLOCKED_WRITE_TOKENS.some((part) => lowered.includes(part))) {

package/src/interactive-cli.js

@@ -561,6 +561,12 @@ function printCommandOutputLog(data = {}) {
     for (const line of preview.shown) outputLine(`${color(" | ", ansi.systemBg)} ${line}`);
     if (preview.hidden > 0) outputLine(`${color(" | ", ansi.systemBg)} ... ${preview.hidden} more line(s) folded`);
   }
+  if (data.permissionAdvice) {
+    const advice = data.permissionAdvice;
+    outputLine(`${label("perm", ansi.red)} ${compactLine(advice.summary || advice.reason || "Permission advice available.", 104)}`);
+    if (advice.suggestedCommand) outputLine(`${color(" | ", ansi.red)} rerun: ${compactLine(advice.suggestedCommand, 120)}`);
+    if (advice.trustedHostCommand) outputLine(`${color(" | ", ansi.red)} host: ${compactLine(advice.trustedHostCommand, 120)}`);
+  }
 }
 
 function printHeading(text) {
@@ -3199,6 +3205,12 @@ async function runPrompt(prompt, state, packageDir) {
           printWorkspaceChange(data);
         } else if (type === "tool.blocked") {
           printStatusEvent(state, "tool_blocked", data.toolName || data.reason || "unknown");
+          if (data.permissionAdvice) {
+            const advice = data.permissionAdvice;
+            outputLine(`${label("perm", ansi.red)} ${compactLine(advice.summary || advice.reason || "Permission advice available.", 104)}`);
+            if (advice.suggestedCommand) outputLine(`${color(" | ", ansi.red)} rerun: ${compactLine(advice.suggestedCommand, 120)}`);
+            if (advice.trustedHostCommand) outputLine(`${color(" | ", ansi.red)} host: ${compactLine(advice.trustedHostCommand, 120)}`);
+          }
         } else if (type === "loop.guard") {
           printStatusEvent(state, "loop_guard", data.toolName || "");
         } else if (type === "conversation.queued_input_applied") {

package/src/permission-advice.js

@@ -0,0 +1,199 @@
+import { redactSensitiveText } from "./redaction.js";
+
+const NETWORK_FAILURE_PATTERNS = [
+  /could not resolve host/i,
+  /temporary failure in name resolution/i,
+  /name or service not known/i,
+  /network is unreachable/i,
+  /failed to connect/i,
+  /connection timed out/i,
+  /unable to access ['"].*?:/i,
+];
+
+function quoteShell(value = "") {
+  const text = String(value || "");
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+function compactLine(value = "", max = 220) {
+  const text = redactSensitiveText(String(value || "")).replace(/\s+/g, " ").trim();
+  return text.length <= max ? text : `${text.slice(0, max - 3)}...`;
+}
+
+function sessionIdFrom(config = {}, state = {}) {
+  return state.sessionId || config.resume || config.sessionId || "<session-id>";
+}
+
+function cwdFrom(config = {}) {
+  return config.commandCwd || process.cwd();
+}
+
+function resumeCommand({ config = {}, state = {}, sandboxMode = "docker-workspace", destructive = false, prompt = "Continue the same task from the last blocker. Do not repeat the blocked command without new permission evidence." } = {}) {
+  const parts = [
+    "aginti",
+    "--resume",
+    quoteShell(sessionIdFrom(config, state)),
+    "--cwd",
+    quoteShell(cwdFrom(config)),
+    "--sandbox-mode",
+    sandboxMode,
+    "--package-install-policy",
+    "allow",
+    "--approve-package-installs",
+    "--allow-shell",
+    "--allow-file-tools",
+  ];
+  if (destructive) parts.push("--allow-destructive");
+  parts.push(quoteShell(prompt));
+  return parts.join(" ");
+}
+
+function currentMode(config = {}) {
+  return {
+    sandboxMode: config.sandboxMode || "",
+    packageInstallPolicy: config.packageInstallPolicy || "",
+    allowShellTool: Boolean(config.allowShellTool),
+    allowFileTools: Boolean(config.allowFileTools),
+    allowDestructive: Boolean(config.allowDestructive),
+    commandCwd: cwdFrom(config),
+  };
+}
+
+function adviceForCategory(category = "", { toolName = "", args = {}, config = {}, state = {}, reason = "" } = {}) {
+  const command = compactLine(args.command || "");
+  const base = {
+    category: category || "permission",
+    reason: compactLine(reason || "The runtime policy blocked this operation."),
+    currentMode: currentMode(config),
+    blockedOperation: command ? `run_command: ${command}` : toolName,
+    instruction:
+      "Stop and present this blocker to the user instead of repeatedly trying variants. Continue only after the user approves a safer mode, changes the workspace, or gives a replacement instruction.",
+  };
+
+  if (category === "workspace-path") {
+    return {
+      ...base,
+      summary:
+        "The requested path is outside the configured project workspace or is a protected path. Current-folder writes are allowed; outside-folder writes need the user to change the working directory or choose a trusted run.",
+      options: [
+        "Refuse: keep all outputs inside the current workspace and ask for a workspace-relative path.",
+        "Allow this project: rerun from the intended project folder with --cwd <project-folder>.",
+        "Trusted host: only if the user explicitly wants host-wide writes, rerun in host mode with --allow-destructive.",
+      ],
+      suggestedCommand: resumeCommand({
+        config,
+        state,
+        sandboxMode: "host",
+        destructive: true,
+        prompt: "Continue after the user approved writing outside the previous workspace. Keep a clear audit trail and do not touch unrelated files.",
+      }),
+    };
+  }
+
+  if (category === "host-sudo" || category === "system-package-install") {
+    return {
+      ...base,
+      summary:
+        "Host sudo and host OS package installs are not run automatically. Use Docker workspace setup when possible, or ask the user to run the exact host command manually.",
+      options: [
+        "Refuse: report the exact missing dependency and the manual host command.",
+        "Allow contained setup: rerun in docker-workspace with package installs approved.",
+        "Manual host setup: user runs the sudo command, then resumes the session.",
+      ],
+      suggestedCommand: resumeCommand({
+        config,
+        state,
+        sandboxMode: "docker-workspace",
+        prompt: "Continue using Docker workspace setup where possible. If host sudo is still required, stop and provide the exact manual command.",
+      }),
+    };
+  }
+
+  if (category === "package-install" || category === "env-setup" || category === "network-fetch" || category === "git-remote") {
+    return {
+      ...base,
+      summary:
+        "This operation needs network or environment setup. It is allowed when shell is enabled in docker-workspace mode with package installs approved.",
+      options: [
+        "Refuse: stop and explain that network/setup is not approved.",
+        "Allow this task: rerun with docker-workspace and approved package installs.",
+        "Trusted host: use host mode only when the user specifically needs host tools or host network behavior.",
+      ],
+      suggestedCommand: resumeCommand({
+        config,
+        state,
+        sandboxMode: "docker-workspace",
+        prompt: "Continue the same task with network/setup approved in Docker workspace mode. Verify the operation actually creates the expected output before reporting success.",
+      }),
+    };
+  }
+
+  if (category === "destructive" || category === "permission-change" || category === "general-shell") {
+    return {
+      ...base,
+      summary:
+        "This command is broader or destructive enough to require a stronger trust mode. Prefer Docker workspace for project-local work; use trusted host mode only when necessary.",
+      options: [
+        "Refuse: explain the blocked command and ask for a safer project-local alternative.",
+        "Allow contained broad shell: rerun in docker-workspace with package installs approved.",
+        "Allow trusted host: rerun in host mode with --allow-destructive when the user accepts host risk.",
+      ],
+      suggestedCommand: resumeCommand({
+        config,
+        state,
+        sandboxMode: "docker-workspace",
+        prompt: "Continue with broad shell access inside Docker workspace. Avoid destructive host actions and verify outputs before finishing.",
+      }),
+      trustedHostCommand: resumeCommand({
+        config,
+        state,
+        sandboxMode: "host",
+        destructive: true,
+        prompt: "Continue after the user approved trusted host execution. Inspect first, avoid unrelated files, and keep git status understandable.",
+      }),
+    };
+  }
+
+  return {
+    ...base,
+    summary:
+      "The current runtime policy blocked this tool. Ask the user whether to keep the task inside the current workspace, approve a stronger mode, or stop.",
+    options: [
+      "Refuse: report the blocker and do not continue.",
+      "Allow this task: rerun with explicit shell/file/package flags appropriate to the blocker.",
+      "Change request: ask the user for a safer workspace-relative output or a manual setup step.",
+    ],
+    suggestedCommand: resumeCommand({ config, state }),
+  };
+}
+
+export function buildPermissionAdvice({ toolName = "", args = {}, guard = {}, config = {}, state = {}, reason = "" } = {}) {
+  const category = guard.category || "permission";
+  return adviceForCategory(category, {
+    toolName,
+    args,
+    config,
+    state,
+    reason: reason || guard.reason || "",
+  });
+}
+
+export function looksLikeNetworkFailure(result = {}) {
+  const text = `${result.stdout || ""}\n${result.stderr || ""}`;
+  return NETWORK_FAILURE_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+export function buildFailedCommandAdvice({ args = {}, commandPolicy = {}, commandResult = {}, config = {}, state = {} } = {}) {
+  if (!looksLikeNetworkFailure(commandResult)) return null;
+  return {
+    ...adviceForCategory(commandPolicy.needsNetwork ? "network-fetch" : "general-shell", {
+      toolName: "run_command",
+      args,
+      config,
+      state,
+      reason:
+        "The command failed with a network-resolution/connectivity error. Do not report success unless a later check proves the expected artifact was created in this run.",
+    }),
+    failureKind: "network",
+  };
+}

package/web.js

@@ -527,6 +527,7 @@ async function collectWorkspaceActivity(limit = 24) {
           path: event.data?.args?.path || "",
           reason: event.data?.reason || "",
           category: event.data?.category || "",
+          permissionAdvice: event.data?.permissionAdvice || null,
         });
       }
     }