Summary

Describe the problem and fix in 2–5 bullets:

• Problem: sandbox mkdirp safety checks used file-open validation, which treats an already-existing directory target as a validation failure.
• Why it matters: sandboxed write/edit flows call mkdir on parent paths first, so valid /workspace/... writes could fail with Sandbox boundary checks failed even with workspaceAccess: rw.
• What changed: mkdirp now allows the specific existing-directory validation case, while still running canonical mount and writability checks; added regression coverage for existing /workspace directory targets.
• What did NOT change (scope boundary): no changes to read/write/edit path resolution semantics, no expansion of mount permissions, no changes to non-mkdirp safety policy.
• AI-assisted: yes (Codex). Testing degree: fully tested for targeted unit/regression scope.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: Sandbox write/edit tools fail with 'boundary checks failed' despite workspaceAccess: rw #30513
• Related fix: distinguish outside-workspace errors from not-found in fs-safe #29715

User-visible / Behavior Changes

• Sandboxed write/edit flows no longer fail when creating or reusing existing parent directories under /workspace with workspaceAccess: rw.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: sandbox FS bridge unit tests (docker exec mocked)
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.sandbox.workspaceAccess: rw

Steps

1. Configure sandbox with workspaceAccess: rw.
2. Trigger sandboxed file write/edit targeting /workspace/... where parent directories may already exist.
3. Observe mkdirp safety validation behavior.

Expected

• Parent directory validation passes for in-boundary existing directories; write/edit proceeds.

Actual

• Before fix, existing directory targets could fail with Sandbox boundary checks failed; cannot create directories: ....

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Passing after patch:

• pnpm vitest src/agents/sandbox/fs-bridge.test.ts
• pnpm vitest src/agents/pi-tools.workspace-paths.test.ts
• pnpm oxfmt --check src/agents/sandbox/fs-bridge.ts src/agents/sandbox/fs-bridge.test.ts
• pnpm oxlint --type-aware src/agents/sandbox/fs-bridge.ts src/agents/sandbox/fs-bridge.test.ts

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: added/ran regression test confirming bridge.mkdirp({ filePath: "/workspace/skills" }) succeeds when directory already exists; verified docker command path arg remains /workspace/skills.
• Edge cases checked: existing read-only bind-mount write guard test remains passing; canonical path and writable checks still execute after directory-validation allowance.
• What you did not verify: full end-to-end live gateway + real docker sandbox run on a production-like host.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this PR commit.
• Files/config to restore: src/agents/sandbox/fs-bridge.ts, src/agents/sandbox/fs-bridge.test.ts, CHANGELOG.md.
• Known bad symptoms reviewers should watch for: unexpected boundary-pass on unsafe paths (none observed in targeted tests).

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: allowing one additional validation case in mkdirp could accidentally relax safety checks.
  • Mitigation: allowance is restricted to existing-directory targets only, and canonical mount + writability checks still run before command execution.