feat(code): classifier-backed Auto approval mode

[Mason Daugherty (mdrxy)]

Deep Agents Code now offers an opt-in Auto approval mode. Auto immediately runs a narrow, deterministic set of routine actions. For other approval-gated actions, the active model checks whether they match the user's literal request. It runs approved actions and blocks the rest. After repeated denials or classifier failures, Auto sends the next batch to the normal approval UI, then continues in Auto mode.

Auto is experimental and currently limited to interactive, local TUI sessions using FilesystemBackend. Manual remains the default.

Warning

Auto is an authorization heuristic for a local coding agent. It is not sandbox containment, an operating-system boundary, or a guarantee that model-generated actions are safe.

Enable Auto

1. Set DEEPAGENTS_CODE_EXPERIMENTAL=1.
2. Select Auto in one of these ways:
   • In-app: use Shift+Tab or Ctrl+T to toggle between Manual and Auto.
   • At launch: pass -y or --auto-approve.
   • By default: set [startup].mode = "auto" in ~/.deepagents/config.toml.

-y and --auto-approve now select Auto rather than unrestricted execution. Users who want the previous unrestricted behavior must choose --yolo. The removed dangerously-auto startup value is no longer recognized and falls back to Manual.

---

Why

The previous approval modes forced a binary choice:

• Manual preserved a human checkpoint, but repeatedly interrupted routine coding work.
• YOLO removed that checkpoint entirely, including for actions that exceeded the user's request (blanket approval).

Auto introduces a third policy: keep the low-friction path for clearly routine work, but make authorization explicit for potentially consequential actions.

Mode	Policy	Entry points	Availability
Manual	Uses the normal human approval UI for gated actions	Default; [startup].mode = "manual"	All interactive sessions
Auto	Uses narrow deterministic rules, then classifier review, with human fallback after repeated denials or failures	-y, --auto-approve, [startup].mode = "auto", or the live keyboard toggle	Experimental, local, unsandboxed TUI sessions
YOLO	Runs gated actions without review	--yolo or [startup].mode = "yolo"	Interactive sessions after a one-time acknowledgement

How Auto handles a proposed action

flowchart TD
    A[Model proposes tool calls] --> B{Covered by the approval policy?}
    B -->|No| X[Existing tool behavior is unchanged]
    B -->|Yes| S{Is this thread still in Auto, with readable denial/failure history?}
    S -->|No| J[Open the existing approval HITL widget]
    S -->|Yes| C{Narrow deterministic allow?}
    C -->|Yes| R[Execute without a classifier call]
    C -->|No| D[Build one structured decision batch]
    D --> H{Was this batch already reviewed, or do earlier denials/failures require human review?}
    H -->|Yes| J
    H -->|No| E[Active model reviews effects against user request/input]
    E -->|Allow| R
    E -->|Deny| Q{Total-denial threshold reached?}
    Q -->|No| F[Return a sanitized error result]
    Q -->|Yes| J
    E -->|Unavailable or invalid| G[Return a compact unavailable result]
    F --> I[Agent can revise its plan]
    G --> I
    J -->|Approve| R
    J -->|Reject| K[Return a rejection result]
    J -->|Switch to Manual| L[Persist Manual, then review the full gated batch]
    R --> M[Reconcile the result and continue]
    K --> M
    I --> M
    L --> M

Loading

In practice:

1. Auto starts with Manual's existing human-in-the-loop (HITL) rules. It changes only how HITL-gated actions are reviewed.
   • These built-in tools are not HITL-gated: ls, read_file, glob, grep, ask_user, get_goal, get_rubric, and update_goal.
   • MCP tools with valid read-only annotations, the optional js_eval tool, and caller-supplied tools without HITL configuration continue to run normally.
2. Only narrow cases resolve locally. The deterministic policy can allow, never deny:

   • A routine write such as src/parser.py can proceed based on its resolved path and suffix; a sensitive target such as .github/workflows/ci.yml goes to classifier review.

   • A read-only Git command such as git status can proceed; a mutating command such as git commit -m change goes to classifier review. Explicit shell allow-list entries still apply after Auto removes broad and wildcard rules.

   • An MCP tool with a valid read-only annotation can proceed; tools without read-only annotations, or with contradictory or malformed annotations, go to classifier review.

     How MCP read-only annotations are evaluated

     MCP servers can attach standard ToolAnnotations when advertising a tool. Deep Agents Code copies those annotations into the wrapped tool's metadata and lets the tool bypass classifier review only when:

     • readOnlyHint is the literal Boolean true;
     • destructiveHint is absent, null, or false; and
     • every supplied standard hint (readOnlyHint, destructiveHint, idempotentHint, or openWorldHint) is a Boolean or null, rather than a string or another type.

     For example:

     • readOnlyHint: true, destructiveHint: false proceeds without classifier review.
     • No readOnlyHint goes to review because the tool never explicitly claimed to be read-only.
     • readOnlyHint: true, destructiveHint: true goes to review because the hints contradict each other.
     • readOnlyHint: true, destructiveHint: "false" goes to review because "false" is a string, not a Boolean.

     In Auto, tools that do not pass this check enter the classifier batch. In Manual, they use the normal approval UI; headless runtimes reject them because they have no approval UI. The annotation is a server-provided assertion that Deep Agents Code does not independently verify.

3. The classifier reviews all unresolved calls together. Only pre-expansion literal user text can authorize an action. Referenced paths, summarized arguments, prior tool calls, and MCP metadata provide effect context but cannot grant permission. Expanded files, assistant prose, and tool results are excluded.
   • Example: For the literal request Research issue #123, update @src/parser.py, and open a PR, proposed fetch_url and git push calls can be reviewed in one batch and receive separate decisions. The referenced path and summarized call arguments help identify what each action would affect, but the expanded file contents are not sent. Instructions found in that file, assistant prose, or a prior tool result therefore cannot widen the user's request or authorize another action.
4. Auto revalidates before side effects. The decision plan is bound to the thread, mode, batch, and exact gated calls. Missing or invalid state, a mode race, or a replay falls back to human review. Denied calls are skipped and receive sanitized error results so the agent can revise its plan.
   • Examples: If the user switches to Manual while classifier review is in progress, an earlier Auto decision cannot execute silently; the normal approval UI opens instead. A plan associated with another thread, a different set of tool-call IDs, missing decisions, or a previously processed batch also requires human review. If Auto denies a proposed delete, it returns an error result with that call's ID instead of invoking the tool, allowing the agent to propose a safer next step.

Limits and user-visible behavior

• The Manual approval menu can enable Auto for the current thread. Threshold fallback can switch permanently to Manual or perform a one-off review while leaving Auto enabled.
• Denials, classifier failures, and fallbacks appear as short sanitized transcript events rather than raw classifier output.
• Auto requested without the experimental opt-in, or in a sandboxed session, falls back to Manual with a warning. Explicit autonomous-mode flags are rejected in non-interactive and ACP entry points.
• The active model is not an independent security authority. MCP read-only annotations are trusted as a deliberate beta tradeoff.
• Parent-level Auto review does not cover actions performed inside delegated subagents or broader explicitly configured PTC/js_eval fan-out. Model providers and tracing backends may still observe classifier inputs and outputs even though the TUI hides them.

Implementation and reviewer details

Approval boundary and decision inputs

The following tools are HITL-gated:

• execute, write_file, edit_file, and delete;
• web_search and fetch_url;
• task;
• start_async_task, update_async_task, and cancel_async_task;
• compact_conversation when optional compaction approval is enabled; and
• MCP tools without valid read-only annotations.

For deterministic writes and edits, the fast path uses only the resolved target path and suffix; it does not inspect proposed content. Dependency and lock files, sensitive names and locations, shell scripts, unsupported file types, and paths outside the trusted root do not qualify. Selected Git inspection commands must also pass shell-control and outside-worktree path checks. Configured shell entries remain an explicit user trust exception, but broad commands and wildcard entries are ignored by Auto.

The classifier receives one typed batch containing:

• up to 20 client-attached, pre-expansion prompt rows, including literal prompts, referenced path names, and turn IDs;
• trusted project-root and redacted-origin facts; and
• depth- and length-limited effect context from current arguments, prior AI tool calls after the latest trusted prompt, and selected MCP annotations.

Only literal_user_text is authorizing. Content-bearing write/edit arguments are reduced to character counts. The classifier must return exactly one unique decision for every unresolved tool-call ID; missing, duplicated, unknown, or malformed decisions make the classifier unavailable rather than partially authorizing the batch.

Before routing calls, Auto re-reads the live mode and validates its private decision plan. Manual mode, invalid control state, mismatched calls, or replayed batches require human review. Classifier review uses a second call to the active session model with a 20-second timeout. Raw classifier text and tool-call chunks are hidden from the transcript, while usage accounting and tracing are retained.

Denial reasons are sanitized before persistence or display by removing control characters, known credential values, credential-like assignments, and URL credentials or query values. MCP tools without valid read-only annotations are HITL-gated; headless runtimes reject them because no approval UI is available.

Failure and fallback behavior

Condition	Result
Selected mode cannot be persisted	Persist Manual instead; if that also fails, block graph execution
Classifier timeout, provider error, or invalid response	Block the affected calls and return a compact unavailable result
Three consecutive policy denials in one user turn	Send the next classifier-review-eligible calls to one-off human review
Two consecutive classifier-unavailable results	Send the next classifier-review-eligible calls to one-off human review
A denial raises the thread's total denial count to 20	Require human review for that call immediately
Counter state cannot be read or reset before classification	Require human review for every gated call in the batch
Counter state cannot be written after classification	Require human review for classifier-path decisions; deterministic fast-path allows remain eligible
Decision plan is missing, malformed, replayed, or bound to another thread	Require Manual review
User chooses Switch to Manual during fallback	Persist Manual before presenting the full gated batch for review

Python API and state compatibility

• Existing Boolean compatibility input retains its previous meaning: auto_approve=True maps to YOLO, not Auto.
• Per-thread Store records persist the typed mode instead of a Boolean. Missing, legacy, or malformed records fail closed.
• Startup and live mode changes take effect only after the Store write succeeds.
• YOLO requires a versioned local acknowledgement and cannot be entered through the live keyboard toggle.

Reviewer guide

Suggested review order:

1. Mode semantics and persistence — ApprovalMode, Store payloads, acknowledgement, startup resolution, and live mode writes.
2. Authorization policy — AutoModeHITLMiddleware, literal prompt metadata, deterministic routing, structured classification, sanitization, counters, and checkpoint validation.
3. Graph boundary — middleware replacement, the gated-tool inventory, MCP annotation handling, headless rejection, PTC, and delegated-subagent scope.
4. Client behavior — stream metadata, classifier-output filtering, fallback interrupts, keyboard toggles, status presentation, and transcript events.

Highest-risk invariants:

• every consequential tool in the supported boundary is gated or explicitly outside scope;
• path-based writes and selected Git fast paths stay within their documented checks;
• only literal user prompts can authorize classifier-reviewed effects;
• malformed output, Store failures, mode races, and checkpoint replay fail closed; and
• hidden classifier chunks never create transcript content while usage accounting remains intact.

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

[corridor-security]

Auto mode's _fixed_repo_command_allowed regex omits the single & shell control operator, allowing an attacker-influenced execute tool call like pytest & rm -rf . to bypass deterministic approval and run an arbitrary background command without human review.

[corridor-security]

The new deterministic allow logic in Auto mode unconditionally bypasses classifier review for build/test/package-manager commands (make, npm/yarn/pnpm, pytest, cargo, go, uv run) that execute arbitrary project-defined code, creating an unreviewed code-execution path for users working against a malicious or compromised repository when Auto is enabled.