[aponcedeleonch]

Stage: Implementation. Implements the Plan / Interface contract in #1730, as revised by the review proposal in #1935 (comment). Stacked on #1730.

What it does

Five session permission modes that each change what the session may do: plan, default, accept-edits, auto, yolo.

• One startup control. --permission-mode (on mecated, mecatui, mecak8s, mecatequi) and the operator-tier permissionMode: key set the mode new sessions start in and the server ceiling, the most permissive mode a session may switch to (accept-edits for plan/default/accept-edits; auto; yolo).
• Modes are session-scoped. Allow-all (auto/yolo), loose substitution (yolo only; auto keeps the command-substitution guard for the main agent and children), the out-of-workspace path-escape decision, and serving a relative ../ path after an approved escape all follow the session's current mode, so switching from yolo to default restores ordinary approvals. Guardrail demotion and startup narration follow the session mode or the server ceiling, not the legacy posture. Deny rules and configured asks win in every mode.
• auto needs an enforcing checker at startup, on create, and on SetMode; missing, --guardrails off, and advisory-only all refuse. Unchecked autonomy is an explicit yolo, where a configured checker is advisory.
• Stored sessions are re-admitted. A persisted session in a mode the current deployment doesn't admit is refused (FailedPrecondition) at run, retry, approval resume, fork, clear, and MCP-authorization continue before any provider or tool work, history untouched, until the owner switches it.
• One mode ordering. session.PermissionMode.Rank orders all five modes and replaces the local rank tables, so an agent definition's permissionMode ceiling clamps auto/yolo requests (explicit or from the server default), and fork/clear of an agent-bound auto/yolo session keeps its mode.
• Mode changes and pending approvals. A session awaiting an approval cannot change mode; the pending ask resolves under the mode it was raised in (narrower contract agreed in review). The exception is a stored session awaiting an approval in a mode the server no longer admits: switching it to an admitted, lower mode cancels the pending turn without running it (refused_mode_recovery).
• Trust is separate. A --permission-mode token never grants project trust; use --trust-project, trustedWorkspaces, or remembered trust. Only the deprecated --posture keeps its interactive trust floor.
• Delegates inherit. Subagent children, Parallel branches, and Team members of an auto/yolo session run in that mode, unless explicitly configured narrower.
• Clients. mecatui cycles all five modes on shift+tab; an unavailable mode keeps the current mode and draft and explains what's needed in the footer. A renderer-owned auto/yolo badge stays in the header whatever the template (server-wide state on legacy servers). /posture shows the subagent ask reviewer state and says "server-wide allow-all" on servers without session_permission_modes. ACP starts sessions in the server default and offers only admitted modes. HTTP rejects an unrecognised mode string with 400 instead of falling back to the server default. The TypeScript SDK supports Auto/Yolo over gRPC and HTTP.
• Wrappers. The Helm chart gains permissionMode (default auto) and a checker choice: guardrails.model, guardrails.fromSettings: true (the checker comes from mounted settings), or guardrails.disabled. It refuses to render auto without a checker or with disabled, and rejects --posture/--permission-mode/--yolo/--guardrails/--guardrails-model in extraArgs. The mecatequi action's guardrails-model is empty = inherit, off = kill-switch, else a model; under auto the step fails early when there's no model and no operator settings file, or with off. The reusable workflow forwards a new permission-mode input.
• Deprecated aliases. --posture, --yolo, mecatui --mode, and the posture: key still resolve, each warning once with the replacement token; combining them with --permission-mode is a startup error. mecated, mecak8s, and mecatequi share one flag helper and help text in internal/app.

API compatibility

Assessment: breaking change to the observable session-mode contract. API major not bumped (stays 1).

The wire policy asks for a major bump when existing conforming clients must change to stay correct. This change does require that for some clients (listed below). I, as the operator, approved keeping major 1 and recording the break here instead, with discovery through feature identifiers and the upgrade notes below.

Old contract:

• A gRPC CreateSession with PERMISSION_MODE_UNSPECIFIED produced a DEFAULT session; the only modes on the wire were DEFAULT, PLAN, ACCEPT_EDITS.
• Allow-all was process-wide: on a --posture auto|yolo server every session, including an explicit DEFAULT one, ran allow-all. Under --posture auto the main agent also ran unprovable command substitutions without asking.
• ServerCapabilities.posture was display-only.

New contract:

• Five session modes on the wire (adds AUTO=4, YOLO=5). An unspecified create (gRPC, HTTP, ACP, schedules, and the TS SDK's HTTP transport) resolves to the server's configured default, which can be AUTO or YOLO. SetMode treats UNSPECIFIED as DEFAULT.
• HTTP create and SetMode accept the bare and PERMISSION_MODE_-prefixed spellings; any other unrecognised mode string is now 400 InvalidArgument instead of falling back to the server default.
• Allow-all belongs to the session mode. An explicit DEFAULT session gets ordinary approvals on every server. Only YOLO lifts the command-substitution guard; AUTO keeps it for the main agent and children.
• A session can switch to modes up to the server ceiling; AUTO additionally needs an enforcing checker. ServerCapabilities.posture now bounds which modes a client may cycle to.
• ApprovePlan rejects AUTO and YOLO as target modes (InvalidArgument on gRPC and HTTP).
• A stored session in a mode the current deployment doesn't admit is refused (FailedPrecondition) at run, retry, approval resume, fork, clear, and MCP-authorization continue until the owner switches it; history is untouched.
• Mode changes are refused while a session awaits an approval, with one exception advertised by refused_mode_recovery: for a stored session awaiting an approval in a mode the server no longer admits, a change to an admitted, strictly lower mode cancels the pending turn without running it and applies the mode.

Affected clients:

• SDKs and mecatui builds that predate AUTO/YOLO may reject an AUTO/YOLO session snapshot or report it as unspecified.
• Clients relying on process-wide allow-all for DEFAULT sessions now see asks.
• An older TS SDK over HTTP sends an explicit "default" when no mode is given, so its sessions start in DEFAULT rather than the server default until upgraded.

Discovery:

• New feature identifiers session_permission_modes and refused_mode_recovery.
• Additive: optional ServerCapabilities.project_trusted (32) and ServerCapabilities.subagent_ask_reviewer (33, on/off/inert).
• Clients should gate AUTO/YOLO on session_permission_modes and check the echoed mode: an older server silently turns AUTO/YOLO into DEFAULT.

Upgrade implications:

• Upgrade clients (TS SDK, mecatui) together with servers, or pass explicit modes from older clients.
• Deployments that ran --posture auto without a checker must configure an enforcing checker or choose --permission-mode yolo. The mecak8s chart now fails at render time for permissionMode: auto without guardrails.model (or guardrails.fromSettings: true), so existing releases must make the choice before upgrading. The mecatequi action fails the step early under auto without a checker; callers of the reusable workflow with defaults must set guardrails-model or permission-mode: yolo.
• Headless --posture auto deployments whose main agent ran $(...), backtick, or subshell commands unattended now get approval requests for them; use yolo if they must run unattended.
• --permission-mode no longer grants project trust; use --trust-project or trustedWorkspaces.
• Stored sessions keep their mode and are re-admitted on use.

Go source: engine adds session.ModeAuto/ModeYolo and PermissionMode.Rank (Added), and delegated children inherit an auto/yolo parent's mode (Changed, no signature change); see engine/CHANGELOG.md.

Stored data: no schema change. Rolling back to a release without session-scoped modes still loads AUTO/YOLO sessions but treats them as DEFAULT (ordinary approvals unless that server's own --posture allows all tools, reported as DEFAULT over gRPC). The stored mode is kept, so upgrading again restores it and re-admits it.

User-facing documentation: user-docs/features/security-and-execution/permissions-and-posture.md#upgrade-from-the-posture-model.

Gates

• task lint: clean except a pre-existing darwin-only gosec finding in environment/microvm (untouched).
• task docs, task site:build, task api:check, task sdk:*: pass.
• Go tests: pass except tests that also fail on main on the author's macOS machine (socket paths, /private temp symlinks, git worktrees, microVM). Chart tests need HELM_NAMESPACE=default with a non-default kube context.
• After the review fixes: task lint and task test:race rerun. Every remaining failure also fails on the pre-fix head 950fbd8ef (mecated/mecatui sockets, executionexecutor, deploy/mecatl-execution-kind) or passes in isolation (race-load flakes).
• go run ./cmd/mecademo: tool call, permission ask/approval, and result.

[JAORMX]

I think we should go further with the convergence here. If I choose default after running in yolo, I expect ordinary permission evaluation to come back. Changing only the session half while the server keeps its allow-all posture makes the mode selector hard to rely on. Putting restart-only choices into the cycle also makes discovery interrupt the work.

What I'd propose is five permission modes that actually change the session's behavior:

• plan: inspect and plan, with mutations denied.
• default: ordinary permission approvals.
• accept-edits: automatically accept file edits; other mutations follow ordinary approval rules.
• auto: autonomous execution with enforcing guardrails. An enforcing checker must be available to enter this mode.
• yolo: autonomous execution without preventive model checking. Advisory monitoring may remain.

Explicit deny and deliberately configured human-required approval rules should still apply in every mode. Permission modes also remain separate from execution isolation: automatic approval does not imply sandboxing.

Workspace trust should be a separate yes/no decision, rather than another permission mode. That removes trusted and trusted-accept-edits from the list. Trust decides whether we automatically adopt the workspace's project instructions and configuration. It does not decide whether we can read its files! Inspecting an unfamiliar repository is often the whole reason to start an agent. We should still be able to read and search an untrusted workspace, including reading AGENTS.md as data without automatically treating it as authoritative. Executing repository scripts remains subject to execution permissions and isolation.

The UI could show something like Accept edits · Workspace instructions enabled. Revoking workspace trust may need a fresh session, since instructions the model already consumed cannot simply be unread.

For switching, the server should define which modes a session is allowed to select, and selecting one should apply its full behavior within that boundary. Switching from yolo to auto must restore checker enforcement; switching to default must remove the session's automatic allow-all behavior. Changes should take effect at a defined execution boundary, with pending approvals re-evaluated and already-running actions clearly identified. A mode change cannot undo a command that has already started. Unavailable choices should explain what's missing without blocking the composer.

I'd also avoid translating an empty checker setting into --guardrails off in the deployment wrappers. Inheriting configuration, configuring a checker, and explicitly disabling it are different choices. And when a model reviewer can approve eligible subagent requests, that delegation should be visible to the operator.

This is a larger change than adding startup presets: it needs session-specific effective policy bounded by server policy, rather than a fixed process-wide posture doing most of the work. But it addresses the actual UX problem. One control for what the agent may do, a separate decision for whether workspace instructions are authoritative, and mode switches that do what their labels say.

[JAORMX]

The move to five real session modes and per-session guardrail composition is the right direction. The separate trust indicator and improved mode confirmation/refusal handling help too. But some permission layers and callers still use the old process-posture assumptions, so the selected mode does not yet reliably describe what will execute.

This follows the proposal in #1935 (comment). Reviewed the full change with independent spec, standards, test, security, architecture/API, UX, deployment and reuse reviewers. The branch was rebased during review; git range-diff confirms all 22 PR patches are unchanged. This review is pinned to 98fc96fa2f8be61916de443a17262adc50c050d0. Findings are from source tracing and CI inspection, not locally executed reproductions.

What needs fixing before merge

The inline comments cover persisted-session admission, checkerless default-auto, filesystem permissions surviving a downgrade, the incomplete TypeScript/API migration, trust still being implied by startup mode, wrapper checker opt-outs, and composer blocking.

There is one additional execution-path blocker outside a changed hunk: cmd/mecatequi/run.go:166 still calls CreateSession(ctx, session.ModeDefault, limits). It never inherits the mode resolved from the CLI. Since allow-all is now mode-driven, auto/yolo runs can ask and cancel on ordinary mutations, accept-edits does not take effect, and plan loses its hard mutation restriction (a configured Allow can authorize a write under the incorrectly selected default mode). Pass the unspecified mode so the service default applies, and test the actual CLI/composition/run boundary. Source:

mecatl/cmd/mecatequi/run.go

Lines 165 to 166 in 98fc96f

	func run(ctx context.Context, svc *server.Service, limits session.Limits, prompt string, w io.Writer) (runOutcome, error) {
	sess, err := svc.CreateSession(ctx, session.ModeDefault, limits)

The requested pending-approval behavior is also absent: engine/session/session.go:1188 rejects mode changes in StateAwaiting, and the TUI only cycles at idle/running. This is safely fail-closed; I am not claiming a stale verdict runs under a newly accepted mode. But it does not implement the requested ability to apply a mode transition and re-evaluate a pending ask. We should implement that boundary or explicitly agree on a narrower contract rather than describe it as completed.

Standards and test adequacy

• internal/app/build.go:9165,9251 still tells the model there are exactly three session modes and advertises the removed trusted tokens. Update the real prompt factories and test the five-mode semantics through them. The user permissions guide, keybinding reference, action input help and mecatequi recovery message also retain removed tokens or old posture behavior. The PR description still claims seven modes and no engine/proto changes.
• Advertise runtime-mode support through a stable feature identifier. An older server can already advertise auto/yolo posture, so posture does not establish support for the new mode enums. Document the actual wire and stored-session compatibility decision; additive enum numbering alone is not enough.
• internal/adapter/server/mode_admission_test.go:152–163 currently requires checkerless default-auto to succeed. That is a contrary acceptance condition, not coverage of the requested guarantee.
• The strongest new guardrail switch test changes mode before the first run. Add production-path runs before and after switches, persisted-session reload under a tighter ceiling, external file effects, and delegated children. Include planted configured Deny/Ask rules and positive controls.
• Wrapper tests that only record argv and policy tests supplied with a mode manually miss callers such as mecatequi. The UI tests also explicitly require the composer blocking we asked to remove.

Other follow-ups

These are nonblocking findings, separate from the enforcement and compatibility blockers above:

• Ordinary subagents/parallel branches still construct default-mode children (engine/agent/subagent.go:4201, engine/agent/parallel.go:1187). The new inheritance comment is not backed by propagation, so a yolo parent's substitution behavior can turn into child asks/review/denials. Children retain their existing builtin allow-all floor; this is not a claim that all child mutations fail.
• ACP explicitly creates default sessions and retains its three-mode picker (internal/adapter/acp/agent.go:296,321,462). Define and migrate that integration's mode behavior.
• The blocked-mode/help guidance says yolo needs a checker, although only auto has that prerequisite.
• Existing Helm extraArgs with --posture=strict now conflict with the template's unconditional --permission-mode=auto. Add a chart-level mode choice and migration guidance.
• The legacy posture-to-replacement-token mapping is copied across three command packages; reuse the composition mapping rather than maintaining three switches.
• Exposing reviewer delegation in /posture would help discovery. Startup diagnostics already disclose it, so this is not a blocker.

I am not carrying forward the initial concern about the chart's old default image as a release blocker: release automation synchronizes the chart/image versions. Nor am I treating the pre-existing HTTP unknown-mode fallback as a newly introduced escalation.

CI on this rebased head is still running, with the two Node SDK jobs already failing. The request for changes is based on the source-level defects above, not red checks alone. The immediate priorities are admission on restored execution, enforcing auto consistently, and removing the remaining startup-posture authority from runtime mode changes.

[JAORMX]

Blocker: this changes an existing wire contract, independently of whether adding enum values is protobuf-compatible. Previously an unspecified gRPC create produced DEFAULT; it can now produce AUTO/YOLO on the same permissive deployment. Existing conforming clients can reject those snapshots. An old client explicitly requesting DEFAULT also loses the former process-wide allow-all behavior now that policy is session-driven.

Please assess this against docs/architecture/api-surface.md:61–89. Preserve the existing contract or obtain explicit approval for a coordinated breaking transition with client/server upgrade and stored-session implications. We also need a stable feature identifier for runtime-mode support; the old posture field does not provide it. The latest commit's additive assessment and the PR body's 'no engine/proto change' statement do not account for these observable changes.

[aponcedeleonch]

Assessed and approved by the operator as a break: unspecified creates resolve to the server default (possibly AUTO/YOLO), and an explicit DEFAULT no longer inherits process-wide allow-all. The major stays at 1 by the operator's decision. Discovery is via the new session_permission_modes feature identifier. The API compatibility statement in the PR description now covers the old and new contracts, affected clients, and stored-session and upgrade implications. User-facing upgrade notes are in permissions-and-posture.md#upgrade-from-the-posture-model.

[aponcedeleonch]

Thanks for the thorough review. Inline blockers are answered in their threads; all changes are in 9d276cc. The rest of the review body:

Blockers

• mecatequi run mode: run now creates its session with an unspecified mode so the --permission-mode default applies. TestRunUsesPermissionModeFromFlags drives parseFlags → appConfig → Build → run.
• Pending-approval mode switch: we're taking the narrower contract. A session awaiting an approval can't change mode; the ask resolves under the mode it was raised in, and a mode change never stops a started command. This is documented in permissions-and-posture.md and docs/architecture/governance.md, not described as a re-evaluation.

Standards / tests

• Prompt text: the self-knowledge prompt now describes five modes, the ceiling, auto's checker requirement, and trust as a separate decision. Its behavioural claims are pinned against the implementation.
• Stale text: the permissions guide, keybindings, using-the-tui, secure-and-expose, CLI help, the action/reusable-workflow descriptions, the mecatequi no-approver message, and the generated config/CLI references are updated.
• Feature identifier: session_permission_modes is advertised and mirrored in the TS SDK.
• Tests: coverage now includes production-path runs across a mode switch, a persisted-session reload under a tighter ceiling, an external-file effect, and delegated-child behaviour, with a configured-Deny positive control.

Non-blocking follow-ups (done)

• Delegated children: Subagent children, Parallel branches, and Team members of an auto/yolo session inherit that mode (effectiveChildMode); an explicitly narrower configured mode is kept. A real parent-run test covers it, and it's recorded in engine/CHANGELOG.md.
• ACP: sessions start in the server's default mode, and the picker offers only modes the server admits (Service.AdmittedModes), including auto/yolo when admitted.
• Help guidance: only auto mentions a checker.
• Helm: a chart-level permissionMode; extraArgs carrying --posture/--permission-mode/--yolo fails rendering with migration guidance.
• Posture mapping: the legacy mapping is consolidated into app.PostureReplacementToken.
• Reviewer visibility: an optional ServerCapabilities.subagent_ask_reviewer (on/off/inert), shown in /posture.

Known remaining

• Serving of external relative ../ paths still follows the startup ceiling. The authorization decision follows the session mode, so this only affects whether an approved relative escape is served below yolo.
• The repo's own mecatequi.yml now runs yolo with guardrails-model: off, since unchecked auto now refuses.

[jhrozek]

Rechecked at c472bd9: the three HIGH findings and nearly all MEDIUM/LOW findings from the earlier review are addressed. Thanks for the thorough follow-up.

[aponcedeleonch]

Thanks for the thorough review, @jhrozek. Everything is addressed in the latest push except the crash-orphan recovery, which moves to #2425. I replied on each thread.

For the items outside the diff:

• The API compatibility statement in the description is rewritten. It now covers refused_mode_recovery, project_trusted, the new meaning of posture, ApprovePlan rejecting AUTO/YOLO, client gating on session_permission_modes, and an explicit record of the major-1 exception.
• Posture no longer drives guardrail demotion, GuardrailsAdvisory or the startup narration; those follow the session mode or the ceiling. The capabilities posture value is unchanged, since deriving it from the ceiling would report strict instead of trusted for --trust-project deployments. Only its docs changed.
• The false docs, the examples workflow, the missing retry/configured-Ask/deprecation tests, the help and --trust-project wording, and the shared flag helper are all in.

One thing I found along the way: ApprovePlan with UNSPECIFIED approves, while the proto says it denies. It's the same on main, so I'll handle it in #2425.