Skip to content
Chapter 7 · Decisions 7-17

ADR 0017: Workspace terminal policy

Amended by ADR 0021 on 2026-10-17: full_access is literally full, so the structured protected-path denial below applies to plan and standard only. The terminal classifier and approval reasons in this ADR are unchanged.

Context

Standard already allowed arbitrary user code through build, test and Python file execution, under the current Windows user. Command-form allowlists, interpretation of literal argv as shell text and install-location restrictions added inconsistent approval and tool errors without providing OS confinement. The user authorized redesign of policy and terminal usability after this review.

Decision

Profile version 2 replaces bounded/risky terminal subjects with workspace/external terminal subjects. Standard permits executable and PowerShell launches whose canonical working directory is inside the workspace. Outside and protected cwd ask (terminal_external_cwd_requires_approval, terminal_protected_path_requires_approval); malformed cwd fails closed. Explicit deny and rule_asks rules, Plan read-only mode, terminal_timeout_requires_approval for long foreground calls and hard limits keep their precedence. Full Access also permits external launches. The session-scoped directory grants (external_directory_required) for structured files do not grant terminal permission. This supersedes ADR 0016 and the terminal fallback portions of ADR 0007/0009; execution ownership stays in the Broker.

run preserves literal argv; shell explicitly runs PowerShell with the selected installed runtime. Language, inline scripts, package operations, network metadata and executable installation location no longer determine automatic permission. The PowerShell AST approval classifier and its Microsoft.PowerShell.SDK dependency are removed; the installed shell validates and executes scripts. Sanitized absolute PATH search remains; executable identity and canonical intent are re-resolved and bound to a one-use Broker token before execution. The RU_TRUSTED_EXECUTABLE_DIRS setting and its dependency plumbing are retired. The public tool IDs and schemas remain unchanged. Analyzer classes remain only metadata and compatibility behavior for legacy adapter callers (the retired Python-file exception no longer auto-authorizes legacy calls); production v2 policy does not defer authority back to an analyzer. (Update, 2026-11: the legacy adapter-caller path was removed; analyzer classes are now metadata only and every launch requires Broker authorization.) Historical approval reason codes stay readable. Policy profiles are generated for new runs; historical prompt receipts do not need a database schema migration. Matching saved version-1 selections upgrade transactionally when starting a new run, preserving the chosen preset and selection version. Old run rows keep their pinned profile; startup recovery fails unfinished old-policy runs with permission_profile_changed rather than silently widening them.

Boundary and consequences

Workspace launch permission is not a restriction on subsequent process effects: programs may access outside files and network as the Windows user. This policy intentionally allows package installation and network commands in a workspace. Structured file tools deny harness key/database/descriptor paths in plan and standard (full_access is literally full, ADR-0021). Credential storage, child-environment key filtering, diagnostic redaction, timeout/output bounds, cancellation and process cleanup are retained. These measures do not claim that arbitrary user processes are unable to read credentials.

The prompt distinguishes repairable tool failures from policy denial and directs routine implementation choices to continue without repeated user questions. Web is automatic in all presets; web_approval_required remains a compatibility reason for an explicit ask rule. Neither prompt text nor skills grant execution authority. Real-provider speed and task completion must be measured separately; fewer approval gates do not establish stronger model capability or faster provider latency.

Verification

Behavioral coverage exercises automatic workspace run/shell, external/protected cwd, explicit rules, Plan denial, full-access behavior, exact intent/replay, PATH resolution and literal arguments. Runtime tests execute both modes without user approval and verify current-user filesystem/network semantics. The complete .NET matrix and tooling guards are recorded in operations/verification.md.