Migrating from legacy `--yolo`

TL;DR

--yolo alone no longer works; it must explicitly acknowledge the SEC bypasses you want to re-enable.
Fastest one-flag migration: agents-fleet --yolo --acknowledge-all-sec ....
Better long-term migration: replace broad --yolo with the minimum permissions config your workflow actually needs.

What broke and why

PR #154 changed --yolo from an all-in-one permission bypass into an explicit migration switch. A bare --yolo now exits before provider startup because it no longer re-opens SEC findings unless you acknowledge each bypass with --acknowledge-* flags. This is intentional and breaking: scripts that used only --yolo must add acknowledgements, use the temporary legacy environment variable, or move to permissions config.

The security motivation is that agents-fleet now has safer alternatives to one global escape hatch. Per-agent-type permissions, per-spawn permissionOverrides, MCP trust controls, and /diagnose make it possible to grant only the capability a workflow needs. The acknowledgement flags keep trusted autopilot and CI workflows unblocked while making every restored bypass visible and auditable.

Decision tree: pick your scenario

I just want my command working RIGHT NOW

Add the all-SEC acknowledgement:

bash

agents-fleet --yolo --acknowledge-all-sec -p "/feature implement the queued task"

This restores the old full-bypass behavior. Treat it as a short-term migration step unless your workflow is intentionally trusted autopilot.

My CI script broke and I cannot change command lines

Set this environment variable around the existing command:

bash

AGENTS_FLEET_YOLO_LEGACY=1

AGENTS_FLEET_YOLO_LEGACY=1 behaves like --yolo --acknowledge-all-sec and appears in /diagnose as env-legacy. Use it only when you cannot edit the command line quickly.

I want to migrate to the safer permissions config

Skip --yolo and grant the minimum capabilities in ~/.fleet/config.json. Start with Migrating away from --yolo to permissions config.

I only need ONE specific bypass

Keep --yolo, but acknowledge only the bypass you need:

bash

agents-fleet --yolo --acknowledge-sec2          # Claude bypassPermissions only
agents-fleet --yolo --acknowledge-sec4          # Restricted approve-all/write/shell bypass only
agents-fleet --yolo --acknowledge-mcp-bypass    # MCP allowlist bypass only
agents-fleet --yolo --acknowledge-sec-r3-2      # Unknown permission kind approval only

Step-by-step CI recovery

Starting point

A GitHub Actions workflow previously ran a trusted unattended feature command:

yaml

name: fleet

on:
  workflow_dispatch:

jobs:
  feature:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Run agents-fleet
        run: npx agents-fleet --unattended --yolo -p "/feature implement the release checklist"

Symptom

After PR #154, that step fails before provider startup with an error like:

text

--yolo requires at least one --acknowledge-* flag. Use --acknowledge-all-sec for legacy full-bypass behavior, or set AGENTS_FLEET_YOLO_LEGACY=1 for CI scripts that cannot change command lines. See docs/yolo-migration.md or docs/security.md for details.

Quick fix without changing command lines

Add AGENTS_FLEET_YOLO_LEGACY=1 to the step or job environment:

yaml

name: fleet

on:
  workflow_dispatch:

jobs:
  feature:
    runs-on: ubuntu-latest
    env:
      AGENTS_FLEET_YOLO_LEGACY: "1"
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Run agents-fleet
        run: npx agents-fleet --unattended --yolo -p "/feature implement the release checklist"

If you can edit the command line, prefer the explicit flag instead:

yaml

- name: Run agents-fleet
  run: npx agents-fleet --unattended --yolo --acknowledge-all-sec -p "/feature implement the release checklist"

Verify in CI with `/diagnose --json`

Add a temporary diagnostic step using the same environment:

yaml

- name: Verify agents-fleet permission posture
  env:
    AGENTS_FLEET_YOLO_LEGACY: "1"
  run: npx agents-fleet --unattended -p "/diagnose --json"

Look for permissions.active_bypasses and env-legacy source attribution:

json

{
  "permissions": {
    "schema_version": 1,
    "yolo": { "active": true, "source": null, "env": true },
    "yolo_acks": {
      "sec2": { "active": true, "source": "env-legacy" },
      "sec4": { "active": true, "source": "env-legacy" },
      "mcp_bypass": { "active": true, "source": "env-legacy" },
      "sec_r3_2": { "active": true, "source": "env-legacy" }
    },
    "active_bypasses": [
      "SEC-2: Claude bypass via AGENTS_FLEET_YOLO_LEGACY=1",
      "SEC-4: privilege escalation via AGENTS_FLEET_YOLO_LEGACY=1",
      "MCP allowlist via AGENTS_FLEET_YOLO_LEGACY=1",
      "SEC-R3-2: unknown-kind fail-closed via AGENTS_FLEET_YOLO_LEGACY=1"
    ]
  }
}

Migrating away from `--yolo` to permissions config

Preferred migration path:

Run once with the smallest acknowledgement you think you need.
Use /diagnose to confirm which bypasses are active.
Read worker logs for permission denials or SEC references.
Replace broad bypasses with permissions entries in ~/.fleet/config.json.
Remove --yolo and run again.

The config file lives at ~/.fleet/config.json on macOS/Linux and %USERPROFILE%\.fleet\config.json on Windows.

The effective worker permission profile is resolved in this order:

Canonical agent-type profile.
Config wildcard: permissions["*"].
Config type entry: permissions["explorer"], permissions["tester"], etc.
Per-spawn permissionOverrides.

Later entries win. writeScopes replace lower-precedence scopes instead of unioning with them.

Example A: I only needed explorer to run shell

Before:

bash

agents-fleet --yolo -p "/ask explorer inspect npm test output"

After, use config only:

json

{
  "permissions": {
    "explorer": { "canShell": true }
  }
}

Then run without --yolo:

bash

agents-fleet -p "/ask explorer inspect npm test output"

This keeps explorer read-only for writes and meta-agent access while allowing shell commands.

Example B: I needed Claude bypass

If you truly need Claude restricted agent types to use bypassPermissions, acknowledge only SEC-2:

bash

agents-fleet --provider claude --yolo --acknowledge-sec2 -p "/code-review"

Safer alternatives are usually better:

spawn a trusted type such as coder or general-purpose for work that needs write/shell access;
grant only the missing capability with permissionOverrides for a specific spawn;
use config such as { "permissions": { "tester": { "canShell": true } } } if the need is stable.

Example per-spawn override:

json

{
  "name": "shell-tester",
  "agent_type": "tester",
  "prompt": "Run the focused regression test and summarize failures",
  "permissionOverrides": { "canShell": true }
}

Example C: I needed MCP bypass for a trusted server

Before:

bash

agents-fleet --yolo -p "/feature use the project MCP server to inspect backlog state"

If the server is trusted and defined in project MCP config, prefer explicitly trusting project MCP discovery instead of bypassing all worker MCP allowlists:

bash

agents-fleet --trust-project-mcp -p "/feature use the project MCP server to inspect backlog state"

Only use the bypass when you intentionally want per-worker MCP allowlists ignored:

bash

agents-fleet --yolo --acknowledge-mcp-bypass -p "/feature use the project MCP server to inspect backlog state"

Example D: I am running autopilot with full bypass

For a trusted, isolated autopilot environment where full bypass is intentional, keep the legacy behavior explicit:

bash

agents-fleet --unattended --yolo --acknowledge-all-sec -p "/loop-target 60 \"finish the release checklist\""

Document why the workflow needs full bypass and verify /diagnose reports all four SEC bypasses as active. Avoid AGENTS_FLEET_YOLO_LEGACY=1 for long-lived workflows if you can edit command lines.

Verifying your migration with `/diagnose`

Use /diagnose to confirm the effective permission posture after changing flags or config.

Human-readable:

bash

agents-fleet -p "/diagnose"

JSON:

bash

agents-fleet -p "/diagnose --json"

What good looks like: no active bypasses

Human output:

text

Permission posture: All SEC restrictions in effect. No bypasses active.

JSON excerpt:

json

{
  "permissions": {
    "schema_version": 1,
    "config_overrides": {},
    "allow_privilege_escalation": { "active": false, "source": null },
    "yolo": { "active": false, "source": null, "env": false },
    "yolo_acks": {
      "sec2": { "active": false, "source": null },
      "sec4": { "active": false, "source": null },
      "mcp_bypass": { "active": false, "source": null },
      "sec_r3_2": { "active": false, "source": null }
    },
    "active_bypasses": []
  }
}

What minimal bypass looks like

Command:

bash

agents-fleet --yolo --acknowledge-sec2 -p "/diagnose"

Human output excerpt:

text

Permission posture:
  Effective restrictions: 1 SEC bypasses ACTIVE
  - SEC-2 (Claude bypass): ACTIVE via --yolo --acknowledge-sec2
  - SEC-4 (privilege escalation): NOT ACTIVE (would require --yolo --acknowledge-sec4)
  - MCP allowlist: NOT BYPASSED
  - SEC-R3-2: NOT BYPASSED
  Config overrides: none

JSON excerpt:

json

{
  "permissions": {
    "yolo": { "active": true, "source": "cli", "env": false },
    "yolo_acks": {
      "sec2": { "active": true, "source": "cli" },
      "sec4": { "active": false, "source": null },
      "mcp_bypass": { "active": false, "source": null },
      "sec_r3_2": { "active": false, "source": null }
    },
    "active_bypasses": [
      "SEC-2: Claude bypass via --yolo --acknowledge-sec2"
    ]
  }
}

active_bypasses is the fastest field to inspect in CI. Source attribution tells you whether the bypass came from CLI flags, ~/.fleet/config.json, or AGENTS_FLEET_YOLO_LEGACY=1.

Per-SEC acknowledgement reference

Finding	Acknowledgement	What it gates	When you need it	Safer alternative
SEC-2	`--yolo --acknowledge-sec2`	Re-enables Claude `permissionMode: "bypassPermissions"` for yolo sessions.	You run Claude provider workflows that intentionally need provider-level bypass behavior for restricted agent types.	Use a trusted agent type, config/per-spawn permissions for the missing capability, or keep Claude restricted types on default permission mode.
SEC-4	`--yolo --acknowledge-sec4`	Re-enables restricted-type approve-all plus write/shell approvals.	You intentionally want restricted types such as `explorer` or `reviewer` to act with broad write/shell approval.	Grant targeted `canShell`, `canWrite`, `writeScopes`, or use `--allow-privilege-escalation` only when elevating profile trust is deliberate.
MCP allowlist	`--yolo --acknowledge-mcp-bypass`	Re-enables bypassing per-worker MCP allowlist checks.	You need a trusted workflow to ignore worker MCP allowlists.	Use `--trust-project-mcp` for trusted project MCP discovery and keep per-worker allowlists enforced.
SEC-R3-2	`--yolo --acknowledge-sec-r3-2`	Re-enables approval of unknown Copilot permission request kinds.	You intentionally accept unknown permission kinds from the provider instead of failing closed.	Leave fail-closed behavior enabled and update agents-fleet if a legitimate new permission kind appears.

Convenience flag:

bash

agents-fleet --yolo --acknowledge-all-sec

--acknowledge-all-sec is equivalent to all four acknowledgements and restores legacy full-bypass behavior.

FAQ

Why did this break suddenly?

Issue #88 and PR #154 deliberately changed --yolo after agents-fleet gained safer permission controls. The old single flag re-opened multiple SEC findings at once. The new behavior requires explicit acknowledgement for each restored bypass.

Can I just keep using `--yolo`?

Yes. Use --yolo --acknowledge-all-sec for the legacy full-bypass behavior, or set AGENTS_FLEET_YOLO_LEGACY=1 temporarily for scripts that cannot change command lines.

Will `--yolo` be removed?

Yes, in a future major version. Migrate to permissions config or targeted acknowledgements now.

How do I know which bypasses my workflow needs?

Start with the smallest acknowledgement you think is needed and run the workflow. If it fails, read the permission error, /code-review output, or worker logs to see which SEC behavior was used. Run /diagnose to confirm active bypasses. For quick isolation, try one acknowledgement at a time instead of jumping directly to --acknowledge-all-sec.

Does `AGENTS_FLEET_YOLO_LEGACY=1` work on Windows, macOS, and Linux?

Yes. Set it using your shell or CI environment syntax.

PowerShell:

powershell

$env:AGENTS_FLEET_YOLO_LEGACY = "1"
agents-fleet --yolo -p "/feature finish migration"

cmd.exe:

bat

set AGENTS_FLEET_YOLO_LEGACY=1
agents-fleet --yolo -p "/feature finish migration"

macOS/Linux shells:

bash

AGENTS_FLEET_YOLO_LEGACY=1 agents-fleet --yolo -p "/feature finish migration"

What if I am using both `--yolo` and `config.json`?

For yolo activation, CLI --yolo takes precedence over config.yolo. AGENTS_FLEET_YOLO_LEGACY=1 also activates yolo when neither CLI nor config does.

For acknowledgement sources, precedence is:

CLI acknowledgement flags, including --acknowledge-all-sec.
~/.fleet/config.json yoloAcks.
AGENTS_FLEET_YOLO_LEGACY=1.

For worker permissions, precedence is separate:

Canonical agent-type profile.
Config wildcard permissions["*"].
Config type entry such as permissions["explorer"].
Per-spawn permissionOverrides.

Can I disable a specific bypass per spawn?

Use per-spawn permissionOverrides to narrow worker capabilities when migrating away from broad yolo behavior. For example, spawn a worker with permissionOverrides: { "canShell": false } or narrower writeScopes when that worker should not inherit a broader config grant. See the security model for the permission override model.

Do not rely on per-spawn overrides to cancel a global yolo acknowledgement for the same session. If a SEC bypass should not apply, do not enable that acknowledgement in the first place.

Migrating from legacy --yolo ​

TL;DR ​

What broke and why ​

Decision tree: pick your scenario ​

I just want my command working RIGHT NOW ​

My CI script broke and I cannot change command lines ​

I want to migrate to the safer permissions config ​

I only need ONE specific bypass ​

Step-by-step CI recovery ​

Starting point ​

Symptom ​

Quick fix without changing command lines ​

Verify in CI with /diagnose --json ​

Migrating away from --yolo to permissions config ​

Example A: I only needed explorer to run shell ​

Example B: I needed Claude bypass ​

Example C: I needed MCP bypass for a trusted server ​

Example D: I am running autopilot with full bypass ​

Verifying your migration with /diagnose ​

What good looks like: no active bypasses ​

What minimal bypass looks like ​

Per-SEC acknowledgement reference ​

FAQ ​

Why did this break suddenly? ​

Can I just keep using --yolo? ​

Will --yolo be removed? ​

How do I know which bypasses my workflow needs? ​

Does AGENTS_FLEET_YOLO_LEGACY=1 work on Windows, macOS, and Linux? ​

What if I am using both --yolo and config.json? ​

Can I disable a specific bypass per spawn? ​

Migrating from legacy `--yolo`

TL;DR

What broke and why

Decision tree: pick your scenario

I just want my command working RIGHT NOW

My CI script broke and I cannot change command lines

I want to migrate to the safer permissions config

I only need ONE specific bypass

Step-by-step CI recovery

Starting point

Symptom

Quick fix without changing command lines

Verify in CI with `/diagnose --json`

Migrating away from `--yolo` to permissions config

Example A: I only needed explorer to run shell

Example B: I needed Claude bypass

Example C: I needed MCP bypass for a trusted server

Example D: I am running autopilot with full bypass

Verifying your migration with `/diagnose`

What good looks like: no active bypasses

What minimal bypass looks like

Per-SEC acknowledgement reference

FAQ

Why did this break suddenly?

Can I just keep using `--yolo`?

Will `--yolo` be removed?

How do I know which bypasses my workflow needs?

Does `AGENTS_FLEET_YOLO_LEGACY=1` work on Windows, macOS, and Linux?

What if I am using both `--yolo` and `config.json`?

Can I disable a specific bypass per spawn?