plan: add container user access levels

[cboone]

Add a comprehensive plan for restricting the container user's privilege
level via a new container.user_access config option with three levels:
sudo (default), install (apk-only sudo), and standard (no sudo).

Includes implementation details for build-time Containerfile generation,
runtime mismatch detection, agent compatibility, and documentation updates
with pros/cons/mitigations for each access level.

https://claude.ai/code/session_017611X3HHnnp1DahXE2zGpt

[Copilot]

Pull request overview

Adds documentation and a detailed implementation plan for introducing configurable container user privilege levels via a new container.user_access option.

Changes:

• Added a comprehensive plan doc covering access levels (sudo/install/standard), build/runtime behavior, and rollout/testing.
• Updated docs/SECURITY.md with a new “User Access Levels” section and linked to the plan.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
docs/plans/todo/container-user-access-levels.md	New detailed plan for implementing container.user_access with enforcement and compatibility notes.
docs/SECURITY.md	Documents planned user access levels, summarizes tradeoffs, and links to the plan.

[Copilot]

This line looks like it’s intended to be part of the existing top navigation row, but it no longer starts with a leading | (the removed line did). As-is, it will render as plain text with pipe characters rather than a table row. Add the leading | back (and match whatever formatting the rest of that nav uses) so the layout renders consistently.

Suggested change

	[**Hardware-Level Isolation**](#hardware-level-isolation) | [**Defense in Depth**](#defense-in-depth) | [**User Access Levels**](#user-access-levels) | [**Why This Matters for AI Coding**](#why-this-matters-for-ai-coding) | [**Secret Scanning**](#secret-scanning) | [**Networking**](#networking)
	| [**Hardware-Level Isolation**](#hardware-level-isolation) | [**Defense in Depth**](#defense-in-depth) | [**User Access Levels**](#user-access-levels) | [**Why This Matters for AI Coding**](#why-this-matters-for-ai-coding) | [**Secret Scanning**](#secret-scanning) | [**Networking**](#networking)

[Copilot]

The plan contradicts itself about whether sudo is installed in standard mode. Here it states the sudo package is not installed, but later the implementation notes say sudo is still installed (and open questions recommend keeping the binary). Pick one approach and make the standard definition consistent with the implementation details (e.g., ‘sudo installed but no sudoers entry’ vs ‘sudo removed’).

Suggested change

	The `dev` user has no sudo access. The `sudo` package is not installed. This is the most
	restrictive mode.
	The `dev` user has no sudo access. The `sudo` package remains installed, but the `dev` user has
	no sudoers entry and cannot successfully run `sudo`. This is the most restrictive mode.

[Copilot]

In the install level description, you indicate system files can be modified via apk (package-managed changes), but the summary table says ‘System Modification: No’. Consider changing that cell to something like ‘Limited (via apk)’ to avoid understating what apk can change under that mode.

Suggested change

	| `install` | Package management only | Yes | No |
	| `install` | Package management only | Yes | Limited (via apk) |

[Copilot]

This reads like an implemented runtime override, but the section explicitly says the feature is ‘Planned’, and the plan document describes user_access as a build-time setting that requires rebuilds (with mismatch warnings at runtime). Rephrase this to align with the plan (e.g., rebuild with --rebuild --user-access sudo, or clarify that a flag can only affect build/mismatch warnings unless a true runtime override is added later).

Suggested change

	- Use `--user-access sudo` as a runtime override for one-off sessions when needed
	- For one-off sessions that require sudo, rebuild with `--rebuild --user-access sudo`; `user_access` is a build-time setting and runtime flags currently only affect build/mismatch warnings

[Copilot]

These examples use user_access: ... as if it were top-level config, but the plan (and YAML examples) describe it under container.user_access. Update the examples to match the documented config shape (e.g., container.user_access: standard or a correctly-indented YAML snippet) to prevent confusion.

Suggested change

	| `user_access: standard` + `workspace.readonly: true` | Agent cannot modify source or escalate privileges |
	| `user_access: standard` + `--yolo` | Agent runs without prompts but cannot escalate OS privileges |
	| `user_access: install` + secret scanning | Agent can install packages but secrets are blocked from the container |
	| `container.user_access: standard` + `workspace.readonly: true` | Agent cannot modify source or escalate privileges |
	| `container.user_access: standard` + `--yolo` | Agent runs without prompts but cannot escalate OS privileges |
	| `container.user_access: install` + secret scanning | Agent can install packages but secrets are blocked from the container |