claw-code/docs/g002-security-verification-map.md

# G002 alpha security map and verification plan

Generated by `worker-4` for OMX team task 5 on 2026-05-14.

## Scope and coordination

- Active goal context: `G002-alpha-security` / Stream 6 day-one security and permissions gate.
- Worker ownership: `worker-1` owns minimal implementation changes for workspace/path enforcement. `worker-4` owns this repository map, integration verification plan, changed-file/commit report, and exact verification evidence.
- Boundary: this report does not mutate `.omx/ultragoal` and does not edit shared security/path tests.
- Parallel probe status: three native subagents were spawned for repository map, test probe, and change-slice probe, but all failed before returning findings with `429 Too Many Requests`; local mapping below is based on direct repository inspection.

## Current permission and path enforcement map

### Runtime permission policy and enforcer

- `rust/crates/runtime/src/permissions.rs`
  - Owns the `PermissionMode` ordering and `PermissionPolicy` authorization contract.
  - Existing tests cover read-only denial, workspace-write escalation, prompt approvals/denials, danger-full-access allowance, override recording, and required-mode reporting.
  - Integration risk: any new dynamic file/path rule must preserve the existing `PermissionPolicy::authorize` semantics so prompt/override audit events remain stable.

- `rust/crates/runtime/src/permission_enforcer.rs`
  - `PermissionEnforcer::check`, `check_with_required_mode`, `check_file_write`, and `check_bash` convert policy outcomes into structured `EnforcementResult` payloads.
  - `check_file_write` currently has the direct write gate for workspace-write mode.
  - `is_within_workspace` is a string-prefix boundary check after simple relative-path joining; it does not canonicalize symlinks, `..`, Windows drive prefixes, or case variants.
  - Existing tests cover read-only denial, workspace-write inside/outside paths, trailing slashes, root equality, bash read-only heuristics, prompt-mode denial payloads, and structured denied fields.

### File tool path handling

- `rust/crates/runtime/src/file_ops.rs`
  - `read_file`, `write_file`, and `edit_file` normalize paths before filesystem operations but do not themselves require a workspace root.
  - `read_file_in_workspace`, `write_file_in_workspace`, and `edit_file_in_workspace` exist as boundary-enforced wrappers.
  - `validate_workspace_boundary` canonicalizes through the caller-provided resolved path and checks `starts_with(workspace_root)`.
  - `is_symlink_escape` detects direct symlink escapes by comparing canonical target to canonical workspace root.
  - Search tools (`glob_search`, `grep_search`) derive walk roots and prune heavy directories, but they are separate from the write enforcement path.
  - Existing tests cover oversized/binary reads, workspace-boundary read rejection, symlink escape detection, glob brace expansion, ignored directories, and grep/glob behavior.

### Bash command validation

- `rust/crates/runtime/src/bash_validation.rs`
  - `validate_command` runs mode validation, sed validation, destructive warning checks, then path validation.
  - `validate_read_only` blocks write-like commands, state-modifying commands, write redirects, and mutating git subcommands in read-only mode.
  - `validate_mode` warns when workspace-write commands appear to target hard-coded system paths.
  - `validate_paths` warns for `../`, `~/`, and `$HOME` references; it is intentionally heuristic and does not resolve shell expansion or canonical targets.
  - Existing tests cover read-only blockers, destructive warnings, sed in-place blocking, path traversal/home warnings, command classification, and full pipeline allow/block/warn outcomes.

### Sandbox and diagnostics surfaces

- `rust/crates/runtime/src/sandbox.rs`
  - Owns container/sandbox status detection and workspace-only sandbox command construction.
  - Relevant for day-one security because sandbox status must not overstate filesystem isolation.

- `rust/crates/rusty-claude-cli/src/main.rs`
  - Owns CLI permission-mode parsing, direct JSON/text diagnostic output, `/permissions`, `/status`, `/doctor`, and command dispatch paths.
  - Existing CLI integration tests under `rust/crates/rusty-claude-cli/tests/` cover permission prompt scenarios and output-format contracts.

- `rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs`
  - End-to-end harness includes `bash_permission_prompt_approved`, `bash_permission_prompt_denied`, read/write file allow/deny, and plugin workspace-write scenarios.

## Existing G002-adjacent coverage

- Unit-level permission coverage:
  - `cargo test -p runtime permissions::tests`
  - `cargo test -p runtime permission_enforcer::tests`
  - `cargo test -p runtime bash_validation::tests`
  - `cargo test -p runtime file_ops::tests`

- CLI and integration coverage:
  - `cargo test -p rusty-claude-cli --test mock_parity_harness`
  - `cargo test -p rusty-claude-cli --test output_format_contract`
  - `cargo test -p rusty-claude-cli --test cli_flags_and_config_defaults`

- Board/report validation coverage:
  - `python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json`
  - `python3 .omx/cc2/validate_issue_parity_intake.py .omx/cc2/issue-parity-intake.json`

## Recommended safe work slices

### Implementation lane (owned by worker-1 unless re-scoped)

1. Replace string-prefix workspace boundary checks with canonical path comparison in the runtime enforcement path.
   - Primary files: `rust/crates/runtime/src/permission_enforcer.rs`, possibly shared helper extraction from `rust/crates/runtime/src/file_ops.rs`.
   - Regression cases: `../` traversal, symlink escape, root prefix collision (`/workspace` vs `/workspacex`), relative paths, trailing slash root equality.

2. Ensure direct file tools call workspace-aware wrappers when active permission mode is `workspace-write`.
   - Primary files: likely `rust/crates/runtime/src/mcp_tool_bridge.rs` and/or the runtime tool execution bridge that calls `file_ops`.
   - Regression cases: direct read/write paths, missing parent creation, symlink parent escape, and error payload stability.

3. Keep bash validation as a warning/classification layer unless a real shell-expansion resolver is introduced.
   - Primary files: `rust/crates/runtime/src/bash_validation.rs`, `rust/crates/runtime/src/bash.rs`.
   - Risk: heuristic parsing cannot faithfully resolve shell expansion, globs, aliases, or platform-specific path rules; avoid claiming hard enforcement unless execution sandbox or command resolver proves it.

### Test lane (coordinate with worker-3/worker-1 before editing)

1. Add unit regressions close to each enforcement function before changing behavior.
   - `permission_enforcer.rs`: canonical path boundary and Windows-shaped path cases.
   - `file_ops.rs`: write/edit workspace wrappers with symlink parent escapes and missing file parent canonicalization.
   - `bash_validation.rs`: shell expansion/glob/path warnings remain warnings unless a resolver is introduced.

2. Add at least one integration test proving the runtime bridge actually routes file tools through workspace enforcement, not only helper functions.
   - Candidate: `rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs` for direct write denial and no file created outside workspace.

3. Preserve existing prompt/event visibility tests.
   - Candidate surfaces: permission prompt scenarios in `mock_parity_harness.rs`, status/doctor JSON in `output_format_contract.rs`.

### Docs/reporting lane (owned by worker-4)

1. Keep this file as the integration handoff artifact for G002 mapping and verification.
2. Report changed files and commits relative to `origin/main` so the leader can integrate worker branches deterministically.
3. Include exact command evidence in the task lifecycle result.

## Changed files relative to `origin/main` at map time

The worktree currently contains these files added relative to `origin/main` before this task report:

- `.omx/cc2/board.json`
- `.omx/cc2/board.md`
- `.omx/cc2/issue-parity-intake.json`
- `.omx/cc2/issue-parity-intake.md`
- `.omx/cc2/render_board_md.py`
- `.omx/cc2/validate_issue_parity_intake.py`
- `scripts/cc2_board.py`
- `scripts/generate_cc2_board.py`
- `scripts/validate_cc2_board.py`

This task adds:

- `docs/g002-security-verification-map.md`

## Commits relative to `origin/main` at map time

- `8311655` — `omx(team): auto-checkpoint worker-1 [1]`
- `c6e2a7d` — `omx(team): merge worker-1`
- `481585f` — `omx(team): auto-checkpoint worker-1 [1]`
- `74bbf4b` — `omx(team): auto-checkpoint worker-4 [unknown]`
- `5c77896` — `omx(team): auto-checkpoint worker-1 [1]`
- `07dad88` — `Classify issue and parity intake for CC2 board integration`
- `424825f` — `task: G001 human board and docs rendering`
- `d15268e` — `Create a canonical CC2 board so every frozen ROADMAP heading is verifiably mapped`
- `45b43b5` — `Make the CC2 board schema executable for G001`

## Verification checklist for leader integration

Run these from the repository root unless noted:

1. Python board/schema validation:
   - `python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json`
   - `python3 .omx/cc2/validate_issue_parity_intake.py .omx/cc2/issue-parity-intake.json`

2. Rust formatting and lint/type checks:
   - `scripts/fmt.sh --check`
   - `(cd rust && cargo check --workspace)`
   - `(cd rust && cargo clippy --workspace --all-targets -- -D warnings)`

3. Targeted G002 security tests:
   - `(cd rust && cargo test -p runtime permissions::tests permission_enforcer::tests bash_validation::tests file_ops::tests)`
   - `(cd rust && cargo test -p rusty-claude-cli --test mock_parity_harness)`

4. Full regression:
   - `(cd rust && cargo test --workspace)`


## Worker-4 verification evidence (2026-05-14)

PASS:

- `python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json` → `PASS cc2 board validation`; 729 items; ROADMAP headings `124/124`; ROADMAP actions `542/542`.
- `python3 .omx/cc2/validate_issue_parity_intake.py .omx/cc2/issue-parity-intake.json` → `PASS issue/parity intake: 19 issue rows, 9 parity rows`.
- `scripts/fmt.sh --check` → no output and zero exit before Rust checks continued.
- `(cd rust && cargo check --workspace)` → `Finished dev profile` successfully.
- `(cd rust && cargo test -p runtime permissions::tests)` → 9 passed.
- `(cd rust && cargo test -p runtime permission_enforcer::tests)` → 21 passed.
- `(cd rust && cargo test -p runtime bash_validation::tests)` → 32 passed.
- `(cd rust && cargo test -p runtime file_ops::tests)` → 14 passed.
- `(cd rust && cargo test -p rusty-claude-cli --test mock_parity_harness)` → 1 passed.

FAIL / integration blockers observed on this worktree:

- `(cd rust && cargo clippy --workspace --all-targets -- -D warnings)` failed in existing runtime code, not this docs-only task:
  - `rust/crates/runtime/src/compact.rs:215` / `:216`: `clippy::match_same_arms`.
  - `rust/crates/runtime/src/policy_engine.rs:5`: `clippy::duration-suboptimal-units`.
  - `rust/crates/runtime/src/sandbox.rs:295-302`: `clippy::map_unwrap_or`.
- `(cd rust && cargo test --workspace)` failed after broad success in API/commands/plugins/runtime tests because `rusty-claude-cli` unit test `tests::session_lifecycle_prefers_running_process_over_idle_shell` asserted `RunningProcess` but observed `IdleShell`.
- Rerun of the specific failing test confirmed deterministic failure: `(cd rust && cargo test -p rusty-claude-cli --bin claw tests::session_lifecycle_prefers_running_process_over_idle_shell -- --exact --nocapture)` → 0 passed, 1 failed with the same `IdleShell` vs `RunningProcess` assertion.

Recommended owner for failures: not `worker-4` unless re-scoped. These failures are outside the docs/report artifact and touch shared runtime/CLI implementation files.