@awak-app/simy-cli 0.2.0 → 0.2.2

package/README.md

@@ -36,6 +36,14 @@ runs. It builds the requirement charter, runs Codex or Claude Code, audits
 structured completion evidence, and re-instructs the executor within the
 configured attempt budget.
 
+Before Web creates an Agentic Loop, it classifies whether the request actually
+needs a managed PR, verification, evidence, and merge lifecycle. A bounded
+ordinary task is sent to CLI 0.2.2 or newer through the one-time direct executor
+instead. CLI independently recomputes the guardrail, restricts read-only work at
+the Provider command boundary, and permits exactly one Provider invocation. It
+does not create an Agentic Loop ledger, audit session, or retry lifecycle for
+that task.
+
 ## CLI updates
 
 The CLI checks the npm registry at startup and once per hour while it is
@@ -93,6 +101,19 @@ executor updates, repository selection, and CLI reconnection. Web clients must
 validate the action type before rendering or executing it; raw local error text
 is not copied into the recovery contract.
 
+## Provider token budget
+
+Each run accepts a configurable `token_budget` (or the explicit
+`provider_token_budget` alias) from 1 to 10,000,000 Provider tokens. The default
+is 250,000. Provider tokens are the Codex or Claude Code usage reported for the
+run; they are a safety limit and are not billed as SIMY tokens.
+
+When a run reaches this limit, its recovery contract suggests a higher rounded
+limit. SIMY Web can edit that suggestion and call
+`POST /v1/agentic-loop/:run_id/provider-token-budget` with
+`provider_token_budget`. The CLI persists the higher limit and resumes the same
+run. SIMY token consumption remains a separate platform billing record.
+
 ## Interactive console
 
 Running `simy` in a terminal opens the Agentic Loop chat. It discovers the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local SIMY Agentic Loop executor for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -25,12 +25,13 @@
     "test:e2e:hypothesis-retries": "node ./scripts/hypothesis-retries-e2e.js",
     "test:e2e:budgets": "node ./scripts/budget-enforcement-e2e.js",
     "test:e2e:desktop-executor": "node ./scripts/desktop-executor-e2e.js",
+    "test:e2e:pre-guardrail": "node ./scripts/pre-guardrail-e2e.js",
     "test:e2e:console:real-provider": "node ./scripts/real-provider-console-e2e.js",
     "test:e2e:console:fullstack": "node ./scripts/fullstack-cli-smoke.js",
-    "check": "npm run check:auto-update && node --check ./src/desktop-executor.js && node --check ./scripts/desktop-executor-e2e.js && node --check ./scripts/fixtures/fake-desktop-provider.js && npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
+    "check": "npm run check:auto-update && node --check ./src/desktop-executor.js && node --check ./scripts/desktop-executor-e2e.js && node --check ./scripts/pre-guardrail-e2e.js && node --check ./scripts/fixtures/fake-desktop-provider.js && npm run check:syntax && npm run check:real-provider-syntax && npm test && npm run check:package",
     "check:auto-update": "node --check ./src/auto-update.js && node --check ./scripts/auto-update-e2e.js",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js",
-    "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/run-registry.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
+    "check:syntax": "node --check ./src/index.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
     "check:package": "node ./scripts/check-package-contents.js"
   },
   "engines": {

package/src/agent.js

@@ -7,6 +7,7 @@ import {
   continueLocalCodingRun,
   continueLocalCodingRunAfterRepositoryApproval,
   createRun,
+  increaseLocalCodingRunProviderTokenBudget,
   LocalRunRegistry,
   isLocalRepositoryApprovalPending,
   pauseLocalCodingRun,
@@ -69,6 +70,16 @@ import {
   CLI_VERSION,
   withCliContract,
 } from "./cli-contract.js";
+import {
+  createDirectTask,
+  directTaskSnapshot,
+  DirectTaskRegistry,
+  startDirectTask,
+} from "./direct-executor.js";
+import {
+  classifyExecutionRequirement,
+  EXECUTION_GUARDRAIL_POLICY_VERSION,
+} from "./execution-guardrail.js";
 
 const DEVICE_HEARTBEAT_INTERVAL_MS = 20_000;
 
@@ -83,6 +94,7 @@ export async function startAgent({
 } = {}) {
   const apiOrigin = resolveWebOrigin(webOrigin);
   const registry = new LocalRunRegistry();
+  const directRegistry = new DirectTaskRegistry();
   const authNonce = randomBytes(16).toString("base64url");
   let session = await readSession(apiOrigin, sessionRoot);
   if (session && sessionRequiresWebAuthorization(session, apiOrigin)) session = null;
@@ -376,6 +388,112 @@ export async function startAgent({
         void synchronizeAuthorizedSession();
         return;
       }
+      const directExecutionMatch = url.pathname.match(/^\/v1\/direct-execution\/([^/]+)$/);
+      if (req.method === "GET" && directExecutionMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const task = directRegistry.get(decodeURIComponent(directExecutionMatch[1]));
+        if (!task) {
+          json(res, 404, { error: "direct task not found" });
+          return;
+        }
+        json(res, 200, { task: directTaskSnapshot(task) });
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/v1/direct-execution/start") {
+        if (!acceptsNewWork(updateManager)) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const body = await readJson(req);
+        const instruction = String(body.instruction || "").trim();
+        if (!instruction) {
+          json(res, 400, { error: "instruction is required" });
+          return;
+        }
+        if (body.backend !== "codex" && body.backend !== "claude") {
+          json(res, 400, { error: "backend must be codex or claude" });
+          return;
+        }
+        const guardrail = classifyExecutionRequirement(instruction);
+        if (
+          guardrail.decision !== "direct_executor" ||
+          body.guardrail?.policy_version !== EXECUTION_GUARDRAIL_POLICY_VERSION ||
+          body.guardrail?.decision !== "direct_executor"
+        ) {
+          json(res, 409, {
+            error: "This request is not authorized for one-time direct execution.",
+            code: "DIRECT_EXECUTION_GUARD_REQUIRED",
+            guardrail,
+          });
+          return;
+        }
+        if (
+          body.operation !== guardrail.operation ||
+          body.permission_mode !== guardrail.permission_mode ||
+          body.max_provider_invocations !== 1
+        ) {
+          json(res, 409, {
+            error: "Direct execution permissions do not match the pre-guardrail decision.",
+            code: "DIRECT_EXECUTION_GUARD_MISMATCH",
+            guardrail,
+          });
+          return;
+        }
+        const inspection = normalizeBackendInspection(body.backend, availableCapabilities);
+        if (!inspection.compatible) {
+          const summary = backendPreflightSummary(body.backend, inspection);
+          json(res, 409, {
+            error: summary,
+            code: `desktop_executor_${inspection.status}`,
+          });
+          return;
+        }
+        const repository = String(body.repository || "").trim() || null;
+        if (guardrail.repository_required && !repository) {
+          json(res, 400, { error: "repository is required for this direct task" });
+          return;
+        }
+        const indexedRepository = repository ? await ensureRepositoryIndexed(repository) : null;
+        if (repository && !indexedRepository?.local_path) {
+          json(res, 409, {
+            error: `${repository} is not authorized on this SIMY CLI.`,
+            code: "repository_not_authorized",
+          });
+          return;
+        }
+        const repositoryPath = indexedRepository?.local_path || workspace.localPath;
+        if (!repositoryPath) {
+          json(res, 409, {
+            error: "No local workspace is available for this direct task.",
+            code: "local_workspace_unavailable",
+          });
+          return;
+        }
+        const task = createDirectTask({
+          instruction,
+          backend: body.backend,
+          operation: guardrail.operation,
+          permissionMode: guardrail.permission_mode,
+          repository,
+          repositoryPath,
+        });
+        directRegistry.create(task);
+        const runDirectTask = dependencies.runDirectTask || startDirectTask;
+        void Promise.resolve(runDirectTask(task)).catch((error) => {
+          task.status = "failed";
+          task.error = error instanceof Error ? error.message : String(error);
+          task.updated_at = new Date().toISOString();
+        });
+        json(res, 202, { ok: true, task: directTaskSnapshot(task) });
+        return;
+      }
       if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/start") {
         if (!acceptsNewWork(updateManager)) {
           json(res, 503, updateInProgressResponse(updateManager));
@@ -386,6 +504,22 @@ export async function startAgent({
           return;
         }
         const { body, attachments } = await readCodingLoopStart(req);
+        const guardrailSource = String(body.source_message || "").trim();
+        if (guardrailSource) {
+          const guardrail = classifyExecutionRequirement(guardrailSource);
+          if (
+            guardrail.decision !== "agentic_loop" ||
+            body.guardrail?.policy_version !== EXECUTION_GUARDRAIL_POLICY_VERSION ||
+            body.guardrail?.decision !== "agentic_loop"
+          ) {
+            json(res, 409, {
+              error: "This task does not qualify for an Agentic Loop.",
+              code: "AGENTIC_LOOP_NOT_REQUIRED",
+              guardrail,
+            });
+            return;
+          }
+        }
         const verified = await verifyLaunchChallenge({
           apiOrigin,
           apiBaseUrl: session.api_base_url,
@@ -468,7 +602,7 @@ export async function startAgent({
             base_branch: typeof body.base_branch === "string" ? body.base_branch : "dev",
             max_attempts: body.max_attempts,
             retry_budget: body.retry_budget,
-            token_budget: body.token_budget,
+            token_budget: body.provider_token_budget ?? body.token_budget,
             ui_evidence_root:
               typeof body.ui_evidence_root === "string" ? body.ui_evidence_root : "",
             acceptance_criteria: Array.isArray(body.acceptance_criteria)
@@ -553,6 +687,53 @@ export async function startAgent({
         return;
       }
 
+      const providerBudgetMatch = agenticLoopPath.match(
+        /^\/v1\/agentic-loop\/([^/]+)\/provider-token-budget$/,
+      );
+      if (req.method === "POST" && providerBudgetMatch) {
+        if (!acceptsNewWork(updateManager)) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const run = registry.get(decodeURIComponent(providerBudgetMatch[1]));
+        if (!run) {
+          json(res, 404, { error: "run not found" });
+          return;
+        }
+        const body = await readJson(req);
+        let budget;
+        try {
+          budget = await increaseLocalCodingRunProviderTokenBudget(
+            run,
+            body.provider_token_budget,
+          );
+        } catch (error) {
+          json(res, 409, {
+            error: error instanceof Error ? error.message : "Provider token budget was rejected",
+            code: "provider_token_budget_rejected",
+          });
+          return;
+        }
+        const continuation = continueLocalCodingRun(
+          run,
+          String(body.message || "Continue after increasing the Provider token budget."),
+          runOptions,
+        );
+        json(res, 202, {
+          ok: true,
+          run_id: run.id,
+          state: "resuming",
+          provider_token_budget: budget.token_budget,
+          provider_tokens_used: budget.tokens_used,
+        });
+        void continuation.catch((error) => reportProviderBudgetResumeError(error, quiet));
+        return;
+      }
+
       const guidanceMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/guidance$/);
       if (req.method === "POST" && guidanceMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
@@ -743,6 +924,7 @@ export async function startAgent({
     server,
     port,
     registry,
+    directRegistry,
     webOrigin: apiOrigin,
     get loginUrl() {
       return loginUrl?.toString() ?? null;
@@ -964,6 +1146,14 @@ function reportRepositoryResumeError(error, quiet) {
   );
 }
 
+function reportProviderBudgetResumeError(error, quiet) {
+  if (!quiet) {
+    console.error(
+      `Provider token budget was increased, but the run could not resume: ${error instanceof Error ? error.message : error}`,
+    );
+  }
+}
+
 function localRepositoryHilRequestId(run) {
   return `local-repository-scan:${run.id}`;
 }
@@ -1021,6 +1211,7 @@ async function capabilities() {
       repository_scan_approval: true,
       executor_version_preflight: true,
       desktop_executor: true,
+      direct_execution: true,
     },
     session_ttl_hours: 48,
   };

package/src/cli-contract.js

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "0.2.2";
 export const CLI_API_CONTRACT_VERSION = 2;
 
 export function withCliContract(capabilities = {}, installMode = null) {

package/src/desktop-executor.js

@@ -49,11 +49,18 @@ export async function resolveDesktopExecutorCommand({
   backend,
   instruction,
   repositoryPath,
+  executionKind = "agentic_loop",
+  permissionMode = "workspace_write",
   environment = process.env,
   spawnImpl = spawn,
   inspectionOptions = {},
 } = {}) {
   const provider = normalizeBackend(backend);
+  const directExecution = executionKind === "direct";
+  if (executionKind !== "agentic_loop" && !directExecution) {
+    throw new Error("Desktop execution kind must be agentic_loop or direct.");
+  }
+  const normalizedPermissionMode = normalizePermissionMode(permissionMode);
   const target = normalizeDesktopExecutionTarget(DESKTOP_EXECUTION_TARGET);
   const override =
     provider === "claude" ? environment.SIMY_CLAUDE_COMMAND : environment.SIMY_CODEX_COMMAND;
@@ -62,6 +69,8 @@ export async function resolveDesktopExecutorCommand({
       ...shellCommand(override, repositoryPath, instruction, spawnImpl),
       backend: provider,
       execution_target: target,
+      execution_kind: executionKind,
+      permission_mode: normalizedPermissionMode,
       verification: "explicit_command_override",
     };
   }
@@ -77,12 +86,24 @@ export async function resolveDesktopExecutorCommand({
     bin: inspection.executable,
     args:
       provider === "claude"
-        ? claudeBackendArgs(instruction)
-        : ["exec", "--json", instruction],
+        ? directExecution
+          ? claudeDirectBackendArgs(instruction, normalizedPermissionMode)
+          : claudeBackendArgs(instruction)
+        : directExecution
+          ? [
+              "exec",
+              "--json",
+              "--sandbox",
+              normalizedPermissionMode === "read_only" ? "read-only" : "workspace-write",
+              instruction,
+            ]
+          : ["exec", "--json", instruction],
     env: {},
     spawn: spawnImpl,
     backend: provider,
     execution_target: target,
+    execution_kind: executionKind,
+    permission_mode: normalizedPermissionMode,
     verification: "compatible_version",
     installed_version: inspection.installed_version,
   };
@@ -102,11 +123,30 @@ export function claudeBackendArgs(instruction) {
   ];
 }
 
+export function claudeDirectBackendArgs(instruction, permissionMode = "read_only") {
+  const normalized = normalizePermissionMode(permissionMode);
+  return [
+    "-p",
+    instruction,
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    ...(normalized === "read_only"
+      ? ["--permission-mode", "plan"]
+      : ["--dangerously-skip-permissions"]),
+  ];
+}
+
 function normalizeBackend(backend) {
   if (backend === "codex" || backend === "claude") return backend;
   throw new Error("Desktop executor backend must be codex or claude.");
 }
 
+function normalizePermissionMode(value) {
+  if (value === "read_only" || value === "workspace_write") return value;
+  throw new Error("Desktop permission mode must be read_only or workspace_write.");
+}
+
 function desktopExecutorUnavailableError(inspection) {
   const provider = inspection.provider_label;
   let message;
@@ -131,6 +171,7 @@ function shellCommand(command, cwd, instruction, spawnImpl) {
     env: {
       SIMY_AGENTIC_LOOP_REQUIREMENT: instruction,
       SIMY_CODING_LOOP_REQUIREMENT: instruction,
+      SIMY_DIRECT_EXECUTION_INSTRUCTION: instruction,
     },
     spawn: spawnImpl,
   };

package/src/direct-executor.js

@@ -0,0 +1,142 @@
+import { randomUUID } from "node:crypto";
+
+import { resolveDesktopExecutorCommand } from "./desktop-executor.js";
+import { createProviderStreamDecoder } from "./provider-stream.js";
+
+const MAX_OUTPUT_LINES = 400;
+
+export class DirectTaskRegistry {
+  #tasks = new Map();
+
+  create(task) {
+    if (this.#tasks.has(task.id)) throw new Error(`Direct task ${task.id} already exists.`);
+    this.#tasks.set(task.id, task);
+    return task;
+  }
+
+  get(taskId) {
+    return this.#tasks.get(taskId) ?? null;
+  }
+}
+
+export function createDirectTask({
+  instruction,
+  backend,
+  operation,
+  permissionMode,
+  repository = null,
+  repositoryPath,
+}) {
+  const now = new Date().toISOString();
+  return {
+    id: `direct_task_${randomUUID()}`,
+    status: "queued",
+    instruction,
+    backend,
+    operation,
+    permission_mode: permissionMode,
+    repository,
+    repository_path: repositoryPath,
+    invocation_count: 0,
+    output: [],
+    result: null,
+    error: null,
+    token_usage: { records: [] },
+    created_at: now,
+    updated_at: now,
+    child: null,
+  };
+}
+
+export async function startDirectTask(
+  task,
+  { resolveCommand = resolveDesktopExecutorCommand, environment = process.env } = {},
+) {
+  if (!task || task.status !== "queued") throw new Error("Direct task must be queued.");
+  if (task.invocation_count >= 1) throw new Error("Direct tasks allow only one Provider invocation.");
+  const command = await resolveCommand({
+    backend: task.backend,
+    instruction: task.instruction,
+    repositoryPath: task.repository_path,
+    executionKind: "direct",
+    permissionMode: task.permission_mode,
+    environment,
+  });
+  task.status = "running";
+  task.invocation_count = 1;
+  task.updated_at = new Date().toISOString();
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const rawStdout = [];
+    const tokenRecords = [];
+    const child = command.spawn(command.bin, command.args, {
+      cwd: task.repository_path,
+      env: { ...process.env, ...command.env },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+    });
+    task.child = child;
+    const onLine = (line) => {
+      const normalized = String(line || "").trim();
+      if (!normalized) return;
+      task.output.push(normalized);
+      if (task.output.length > MAX_OUTPUT_LINES) {
+        task.output.splice(0, task.output.length - MAX_OUTPUT_LINES);
+      }
+      task.updated_at = new Date().toISOString();
+    };
+    const stdoutDecoder = createProviderStreamDecoder({
+      backend: task.backend,
+      stream: "stdout",
+      onLine,
+      onUsage: (usage) => tokenRecords.push({ ...usage, phase: "direct", backend: task.backend }),
+    });
+    const stderrDecoder = createProviderStreamDecoder({
+      backend: task.backend,
+      stream: "stderr",
+      onLine,
+    });
+    child.stdout?.on("data", (chunk) => {
+      const text = chunk.toString("utf8");
+      rawStdout.push(text);
+      stdoutDecoder.push(text);
+    });
+    child.stderr?.on("data", (chunk) => stderrDecoder.push(chunk.toString("utf8")));
+
+    const finish = ({ exitCode = null, error = null } = {}) => {
+      if (settled) return;
+      settled = true;
+      stdoutDecoder.flush();
+      stderrDecoder.flush();
+      task.child = null;
+      task.token_usage = { records: tokenRecords };
+      task.status = error || exitCode !== 0 ? "failed" : "succeeded";
+      task.error = error || (exitCode !== 0 ? `Provider exited with code ${exitCode}.` : null);
+      task.result = task.output.at(-1) || rawStdout.join("").trim() || null;
+      task.updated_at = new Date().toISOString();
+      resolve(task);
+    };
+    child.on("error", (error) => finish({ error: error.message }));
+    child.on("close", (code) => finish({ exitCode: code }));
+  });
+}
+
+export function directTaskSnapshot(task) {
+  return {
+    id: task.id,
+    status: task.status,
+    instruction: task.instruction,
+    backend: task.backend,
+    operation: task.operation,
+    permission_mode: task.permission_mode,
+    repository: task.repository,
+    invocation_count: task.invocation_count,
+    output: [...task.output],
+    result: task.result,
+    error: task.error,
+    token_usage: structuredClone(task.token_usage),
+    created_at: task.created_at,
+    updated_at: task.updated_at,
+  };
+}

package/src/execution-guardrail.js

@@ -0,0 +1,120 @@
+export const EXECUTION_GUARDRAIL_POLICY_VERSION = "2026-07-21.1";
+
+const OBSERVE_PATTERN =
+  /\b(monitor|watch|observe|track|status|progress|keep an eye on)\b|監視|見守|進捗|状況を?(?:見|確認)|监控|監控|观察|觀察|进度|進度|状态|狀態/i;
+const READ_PATTERN =
+  /\b(explain|summari[sz]e|inspect|review|look at|read|check|diagnose|investigate)\b|説明|要約|確認|調査|レビュー|查看|解释|說明|总结|總結|检查|檢查|调查|調查|诊断|診斷/i;
+const CHANGE_PATTERN =
+  /\b(implement|fix|build|create|change|update|refactor|add|remove|rename|ship|write|edit|merge|release|publish)\b|実装|修正|改善|変更|追加|削除|作成|開発|マージ|公開|发布|發佈|实现|實現|修复|修復|修改|改掉|改一下|新增|删除|刪除|重构|重構|合并|合併/i;
+const OBJECT_PATTERN =
+  /\b(code|file|readme|api|ui|ux|feature|bug|pr|pull request|repository|repo|branch|test|migration|endpoint|component|page|cli|backend|extension)\b|コード|ファイル|機能|不具合|画面|ページ|テスト|移行|组件|組件|页面|頁面|代码|代碼|文件|功能|错误|錯誤|仓库|倉庫|分支/i;
+const VAGUE_PATTERN = /^(?:fix|do|handle|continue|change)?\s*(?:it|this|that)?[.!。！]?$/i;
+const VAGUE_CJK_PATTERN = /^(?:これ|それ|あれ|やって|直して|続けて|这个|這個|那个|那個|处理|處理|修一下)[。！]?$/i;
+const UNSUPPORTED_PATTERN =
+  /\b(?:steal|exfiltrate|bypass authentication|disable audit)\b|認証を迂回|監査を無効|窃取凭证|繞過認證/i;
+
+const MANAGED_SIGNAL_PATTERNS = [
+  ["pr_merge_release", /\b(?:pull request|pr|merge|release|publish|deploy)\b|PR|マージ|リリース|デプロイ|合并|合併|发布|發佈|部署/i],
+  ["verification", /\b(?:test|e2e|integration test|until green|ci)\b|テスト|検証|通过测试|通過測試|直到.*通过|直到.*通過/i],
+  ["browser_evidence", /\b(?:browser|screenshots?|visual evidence|evidence)\b|ブラウザ|スクリーンショット|証跡|截图|截圖|浏览器|瀏覽器|证据|證據/i],
+  ["cross_repository", /\b(?:cross[- ]repo|multiple repos|multi[- ]repo)\b|複数(?:の)?リポジトリ|跨仓库|跨倉庫|多个仓库|多個倉庫/i],
+  ["high_risk_change", /\b(?:migration|authentication|authorization|security|rollback)\b|移行|認証|認可|セキュリティ|ロールバック|迁移|遷移|认证|認證|授权|授權|安全|回滚|回滾/i],
+  ["diagnose_repair_reverify", /\bdiagnos\w*\b[\s\S]*\bfix\w*\b[\s\S]*\b(?:verify|retest)\b|調査[\s\S]*修正[\s\S]*再検証|诊断[\s\S]*修复[\s\S]*复验|診斷[\s\S]*修復[\s\S]*複驗/i],
+];
+
+export function classifyExecutionRequirement(sourceMessage) {
+  const source = String(sourceMessage || "")
+    .replace(/^\s*\/(?:agentic-loop|coding-loop)\b\s*/i, "")
+    .trim();
+  if (!source || VAGUE_PATTERN.test(source) || VAGUE_CJK_PATTERN.test(source)) {
+    const vagueChangeRequested = CHANGE_PATTERN.test(source);
+    return guardrail("needs_clarification", {
+      change_requested: vagueChangeRequested,
+      operation: vagueChangeRequested ? "execute" : "read",
+      permission_mode: vagueChangeRequested ? "workspace_write" : "read_only",
+      reason_code: "goal_not_clear",
+    });
+  }
+  if (UNSUPPORTED_PATTERN.test(source)) {
+    return guardrail("unsupported", {
+      operation: "execute",
+      permission_mode: "workspace_write",
+      reason_code: "prohibited_operation",
+    });
+  }
+  const changeRequested = CHANGE_PATTERN.test(source);
+  const observeRequested = OBSERVE_PATTERN.test(source);
+  const readRequested = READ_PATTERN.test(source);
+  const hasObject = OBJECT_PATTERN.test(source) || source.length >= 24;
+  const agenticSignals = MANAGED_SIGNAL_PATTERNS.filter(([, pattern]) => pattern.test(source)).map(
+    ([signal]) => signal,
+  );
+  if (changeRequested && hasObject && agenticSignals.length >= 2) {
+    return guardrail("agentic_loop", {
+      change_requested: true,
+      managed_lifecycle_required: true,
+      repository_required: true,
+      operation: "execute",
+      permission_mode: "workspace_write",
+      agentic_signals: agenticSignals,
+      reason_code: "managed_change_lifecycle_required",
+    });
+  }
+  if (observeRequested && !changeRequested) {
+    return guardrail("direct_executor", {
+      repository_required: /\b(?:repo|repository|pr|branch)\b|リポジトリ|仓库|倉庫|分支/i.test(source),
+      operation: "observe",
+      permission_mode: "read_only",
+      direct_signals: ["bounded_observation", "no_persistent_change"],
+      reason_code: "observe_existing_provider_session",
+    });
+  }
+  if (changeRequested && hasObject) {
+    return guardrail("direct_executor", {
+      change_requested: true,
+      repository_required: true,
+      operation: "execute",
+      permission_mode: "workspace_write",
+      agentic_signals: agenticSignals,
+      direct_signals: ["single_bounded_change", "managed_lifecycle_not_required"],
+      reason_code: "bounded_change_direct_execution",
+    });
+  }
+  if (changeRequested) {
+    return guardrail("needs_clarification", {
+      change_requested: true,
+      operation: "execute",
+      permission_mode: "workspace_write",
+      reason_code: "change_target_missing",
+    });
+  }
+  if (readRequested || source.length >= 8) {
+    return guardrail("direct_executor", {
+      repository_required: /\b(?:repo|repository|pr|file|code)\b|コード|ファイル|仓库|倉庫|文件|代码|代碼/i.test(source),
+      operation: "read",
+      permission_mode: "read_only",
+      direct_signals: ["single_read_task", "no_managed_lifecycle"],
+      reason_code: "bounded_read_direct_execution",
+    });
+  }
+  return guardrail("needs_clarification", {
+    operation: "read",
+    permission_mode: "read_only",
+    reason_code: "action_missing",
+  });
+}
+
+function guardrail(decision, overrides) {
+  return {
+    policy_version: EXECUTION_GUARDRAIL_POLICY_VERSION,
+    decision,
+    change_requested: false,
+    managed_lifecycle_required: false,
+    repository_required: false,
+    operation: "read",
+    permission_mode: "read_only",
+    agentic_signals: [],
+    direct_signals: [],
+    ...overrides,
+  };
+}

package/src/orchestrator/budget.js

@@ -2,7 +2,8 @@ import { clampAttempts } from "./shared.js";
 
 export const DEFAULT_TOKEN_BUDGET = 250_000;
 export const DEFAULT_RETRY_BUDGET = 2;
-const MAX_TOKEN_BUDGET = 10_000_000;
+export const MAX_PROVIDER_TOKEN_BUDGET = 10_000_000;
+const PROVIDER_TOKEN_BUDGET_STEP = 250_000;
 
 export function resolveRunBudgets(request = {}) {
   const legacyMaxAttempts = clampAttempts(request.max_attempts);
@@ -12,12 +13,47 @@ export function resolveRunBudgets(request = {}) {
       ? legacyMaxAttempts - 1
       : Math.min(4, Math.max(0, explicitRetryBudget));
   return {
-    token_budget: normalizeTokenBudget(request.token_budget),
+    token_budget: normalizeTokenBudget(request.provider_token_budget ?? request.token_budget),
     retry_budget: retryBudget,
     max_attempts: retryBudget + 1,
   };
 }
 
+export function suggestedProviderTokenBudget(value) {
+  const state = value?.schema_version === 1 ? value : budgetState(value);
+  if (state.tokens_used >= MAX_PROVIDER_TOKEN_BUDGET) return null;
+  const required = Math.max(
+    state.token_budget * 2,
+    state.tokens_used * 1.25,
+    state.tokens_used + PROVIDER_TOKEN_BUDGET_STEP,
+  );
+  return Math.min(
+    MAX_PROVIDER_TOKEN_BUDGET,
+    Math.ceil(required / PROVIDER_TOKEN_BUDGET_STEP) * PROVIDER_TOKEN_BUDGET_STEP,
+  );
+}
+
+export function increaseProviderTokenBudget(snapshot, value) {
+  const requested = integer(value);
+  if (requested === null || requested <= 0) {
+    throw new Error("Provider token budget must be a positive integer.");
+  }
+  if (requested > MAX_PROVIDER_TOKEN_BUDGET) {
+    throw new Error(
+      `Provider token budget cannot exceed ${MAX_PROVIDER_TOKEN_BUDGET.toLocaleString("en-US")}.`,
+    );
+  }
+  const current = budgetState(snapshot);
+  if (requested <= current.token_budget) {
+    throw new Error("Provider token budget must be higher than the current limit.");
+  }
+  if (requested <= current.tokens_used) {
+    throw new Error("Provider token budget must be higher than the Provider tokens already used.");
+  }
+  snapshot.charter.token_budget = requested;
+  return refreshBudgetState(snapshot);
+}
+
 export function budgetState(snapshot, pendingAttempt = null) {
   const attempts = [
     ...(Array.isArray(snapshot?.attempts) ? snapshot.attempts : []),
@@ -93,7 +129,7 @@ function recordTokenTotal(value) {
 function normalizeTokenBudget(value) {
   const parsed = integer(value);
   if (parsed === null || parsed <= 0) return DEFAULT_TOKEN_BUDGET;
-  return Math.min(MAX_TOKEN_BUDGET, parsed);
+  return Math.min(MAX_PROVIDER_TOKEN_BUDGET, parsed);
 }
 
 function normalizeRetryBudget(value, maxAttempts) {

package/src/orchestrator/loop.js

@@ -469,7 +469,7 @@ async function stopForBudget({ snapshot, attempt, reason, onUpdate }) {
   if (attempt) attempt.budget = budget;
   const message =
     reason === "token_budget_exhausted"
-      ? "Agentic loop exhausted its token budget."
+      ? "Agentic loop reached its Provider token budget."
       : "Agentic loop exhausted its retry budget.";
   appendEvent(snapshot, "blocked", message, {
     code: reason,
@@ -487,8 +487,8 @@ function budgetFinding(reason, budget) {
       passed: false,
       code: "TOKEN_BUDGET_EXHAUSTED",
       severity: "blocker",
-      target: "token_budget",
-      explanation: `The run used ${budget.tokens_used} of ${budget.token_budget} provider tokens, so no additional executor or reviewer call can start.`,
+      target: "provider_token_budget",
+      explanation: `The run used ${budget.tokens_used} of ${budget.token_budget} Provider tokens, so no additional executor or reviewer call can start until the Provider token budget is increased. Provider tokens are not billed as SIMY tokens.`,
       repairability: "manual",
       auto_fix_hint: null,
     };

package/src/orchestrator/recovery.js

@@ -1,3 +1,5 @@
+import { suggestedProviderTokenBudget } from "./budget.js";
+
 const RECOVERABLE_STATES = new Set(["waiting_human", "blocked", "failed"]);
 
 export function recoveryContractForEvent({ snapshot, state, message, detail = {} }) {
@@ -6,7 +8,7 @@ export function recoveryContractForEvent({ snapshot, state, message, detail = {}
 
   const reasonCode = recoveryReasonCode(state, message, detail);
   const attemptNumber = positiveInteger(detail.attempt_number);
-  const actions = recoveryActions(reasonCode);
+  const actions = recoveryActions(reasonCode, detail.budget);
   return {
     schema_version: 1,
     state,
@@ -18,6 +20,8 @@ export function recoveryContractForEvent({ snapshot, state, message, detail = {}
       event_code: clean(detail.code) || null,
       attempt_number: attemptNumber,
       max_attempts: positiveInteger(snapshot?.charter?.max_attempts),
+      provider_token_budget: positiveInteger(snapshot?.charter?.token_budget),
+      provider_tokens_used: nonNegativeInteger(detail?.budget?.tokens_used),
       token_budget: positiveInteger(snapshot?.charter?.token_budget),
       retry_budget: nonNegativeInteger(snapshot?.charter?.retry_budget),
       tokens_used: nonNegativeInteger(detail?.budget?.tokens_used),
@@ -136,7 +140,7 @@ function recoveryMessage(reasonCode) {
       "SIMY needs the missing requirement or approval before implementation can start.",
     human_input_required: "SIMY needs your decision or clarification before it can continue.",
     token_budget_exhausted:
-      "This run used its token budget. Start a new run if you want SIMY to continue with a fresh limit.",
+      "This run reached its Provider token safety limit. Provider tokens are not billed by SIMY. Increase the limit to continue this run.",
     retry_budget_exhausted:
       "This run used its automatic retry budget. Start a new run to continue with a fresh limit.",
     automatic_progress_blocked:
@@ -149,7 +153,7 @@ function recoveryMessage(reasonCode) {
   return messages[reasonCode] || messages.automatic_progress_blocked;
 }
 
-function recoveryActions(reasonCode) {
+function recoveryActions(reasonCode, budget = null) {
   if (reasonCode === "repository_authorization_required") {
     return [
       {
@@ -182,7 +186,25 @@ function recoveryActions(reasonCode) {
       newRunAction(),
     ];
   }
-  if (reasonCode === "token_budget_exhausted" || reasonCode === "retry_budget_exhausted") {
+  if (reasonCode === "token_budget_exhausted") {
+    const suggestedBudget = suggestedProviderTokenBudget(budget);
+    if (!suggestedBudget || budget?.retry_exhausted === true) return [newRunAction()];
+    return [
+      {
+        id: "increase_provider_token_budget",
+        type: "increase_provider_token_budget",
+        label: "Increase Provider token budget",
+        description:
+          "Raise this run's safety limit and continue. Provider tokens are usage diagnostics and are not billed as SIMY tokens.",
+        command: null,
+        payload: {
+          ...(suggestedBudget ? { suggested_provider_token_budget: suggestedBudget } : {}),
+        },
+      },
+      newRunAction(),
+    ];
+  }
+  if (reasonCode === "retry_budget_exhausted") {
     return [newRunAction()];
   }
   if (reasonCode === "local_execution_interrupted") {

package/src/runner.js

@@ -19,7 +19,7 @@ import {
   redactExecutionText,
 } from "./orchestrator/execution-io.js";
 import { summarizeCodingLoopEvent } from "./orchestrator/presentation.js";
-import { refreshBudgetState } from "./orchestrator/budget.js";
+import { increaseProviderTokenBudget, refreshBudgetState } from "./orchestrator/budget.js";
 import { appendEvent } from "./orchestrator/shared.js";
 import {
   createProviderStreamDecoder,
@@ -252,6 +252,35 @@ export async function continueLocalCodingRun(run, guidance, dependencies = {}) {
   return executeLocalCodingRun(run, dependencies, { humanGuidance: message, resume: true });
 }
 
+export async function increaseLocalCodingRunProviderTokenBudget(run, value) {
+  if (run.operation || run.child) {
+    throw new Error("Provider token budget can change only while the run is waiting.");
+  }
+  if (!RESUMABLE_STATES.has(run.status)) {
+    throw new Error("Provider token budget can change only for a blocked or waiting run.");
+  }
+  const currentBudget = refreshBudgetState(run.snapshot);
+  if (currentBudget.retry_exhausted) {
+    throw new Error("The Agentic Loop run also used its retry budget. Start a new run to continue.");
+  }
+  const previousBudget = currentBudget.token_budget;
+  const budget = increaseProviderTokenBudget(run.snapshot, value);
+  run.request.token_budget = budget.token_budget;
+  appendEvent(
+    run.snapshot,
+    "waiting_human",
+    `Provider token budget increased from ${previousBudget} to ${budget.token_budget}.`,
+    {
+      code: "provider_token_budget_increased",
+      previous_provider_token_budget: previousBudget,
+      provider_token_budget: budget.token_budget,
+      budget,
+    },
+  );
+  await updateRun(run, "waiting_human");
+  return budget;
+}
+
 export async function continueLocalCodingRunAfterRepositoryApproval(
   run,
   { repository, localPath } = {},