feat(sandbox): add opt-in Cageforge command sessions

[m62624]

📋 Pull Request

Description

This is a contribution for the BOSS Console Hackathon.

The Cageforge JVM binding was prepared for this hackathon in PR #22. This PR brings that binding into BOSS for opt-in sandboxed command sessions.

The on-demand permission flow uses the API introduced in Cageforge PR #51. The operator-facing sandbox_request_permissions tool sends the exact command, requested rights and reason to BOSS for human approval (once or until BOSS closes). An approved command gets its own immutable sandbox; the requesting agent is not restarted or widened. Dedicated agent-only endpoint/token provisioning remains in progress.

Add explicit opt-in sandboxed command sessions powered by Cageforge, using its Java 0.7.1 binding. Users can launch a selected root executable, including an agent CLI such as Codex, under a project-specific TOML policy. Its shell commands, compilers and other descendants inherit the same native sandbox restrictions.

The policy is fixed for the lifetime of the session. Sandboxed execution is explicitly selected by the user, and a sandbox failure never falls back to an unsandboxed launch. Existing ordinary command execution remains unchanged. The integration includes policy preparation and approval, process lifecycle management, and dedicated native security tests for Linux, macOS and Windows.

This is process-tree isolation, not application-wide or machine-wide isolation. An agent launched outside a sandbox session can execute commands without calling BOSS; only its explicit sandbox launches enter this boundary. When the agent itself is the sandbox root, its descendants remain constrained even without MCP calls. External MCP servers and already-running services are not brought inside that boundary.

The subsystem is disabled by default. Enable it explicitly from Tools > Sandbox command sessions, or start BOSS with boss --sandbox. This does not redirect ordinary command execution. Disabling unregisters its tools, revokes approvals and stops its sandbox sessions; nothing is persisted across BOSS restarts.

🔄 Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 🔧 Configuration change (changes to build scripts, CI/CD, or project configuration)
• 📚 Documentation (documentation only changes)
• 🧹 Refactoring (code change that neither fixes a bug nor adds a feature)
• ⚡ Performance improvement (code change that improves performance)
• 🧪 Tests (adding missing tests or correcting existing tests)

📦 Version Impact

• No version change needed
• Patch version (bug fixes, small improvements) - x.x.+1
• Minor version (new features, enhancements) - x.+1.0
• Major version (breaking changes) - +1.0.0

✅ Testing Checklist

🧪 Local Testing

• I have tested this change locally on my development machine
• All existing tests pass with my changes
• I have added new tests for new functionality (if applicable)
• I have verified the fix/feature works as intended

Current head: c80d5eb1. Local verification passed: 28 sandbox module tests, 14 focused desktop sandbox tests, both modules' detekt/ktlint checks, and native test bundle compilation. The full desktop suite passed before the additional-permission delta and is being rerun. Tests cover default-off activation, startup argument preservation, explicit approval, denial/cancellation cleanup and captured-policy reuse.

Fresh native CI and full BOSS CI are running for this head. The previous head bab763a4 passed both workflows. The new native test verifies that an approved additional command can read its granted file while the original agent remains denied access before, during and after that command. Current-head native results are not yet claimed.

🖥️ Platform Testing

• 🍎 macOS - Tested and working
• 🪟 Windows - Tested and working
• 🐧 Linux - Tested and working
• 📱 Mobile (iOS/Android) - Tested if applicable
• 🌐 Web (WASM) - Tested if applicable

🏗️ Build Verification

• Project builds successfully with my changes
• No new build warnings introduced
• Distribution packages (DMG/MSI/JAR) can be created successfully
• Version system integration tested (if version-related changes)

🔍 Code Quality

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to documentation (if needed)
• My changes generate no new warnings or errors

🚀 CI/CD Integration

• This PR will trigger appropriate CI/CD workflows
• I understand that all status checks must pass before merging
• I have considered the impact on our centralized version management system

📸 Screenshots/Media

Before

No explicit Cageforge command-session launch surface.

After

Tools > Sandbox command sessions now opens the explicit launch form, native permission review, bounded stdout/stderr viewer, stdin controls and stop action. Additional-permission requests use the same consent dialog and explicitly state that the original agent remains unchanged. Screenshots and dedicated agent endpoint provisioning remain pending.

🔗 Related Issues

📝 Additional Context

🎯 Motivation and Context

Provide an explicit way to confine a CLI session and its descendants. MCP remains a tool transport; individual MCP invocations are not separate sandbox boundaries.

🧠 Implementation Details

The standalone JVM module lives under modules/boss-command-sandbox and does not change the plugin sandbox. Cageforge owns TOML inheritance and platform overlays. Approval identifies an immutable snapshot of the executable, separate arguments, working directory and policy. A failed sandbox launch has no unsandboxed fallback.

Cageforge tests use a separate workflow. Linux compiles dependencies and the consumer on the host, then executes the bundle in a prepared QEMU guest. macOS and Windows exercise their native backends, with explicit Windows setup and teardown. Existing BOSS workflows are unchanged.

The new production module uses resource ownership without lint suppressions or generic catch (Throwable).

⚠️ Breaking Changes

None intended. Ordinary command execution stays unchanged. No manual release-version change is included.

🔮 Future Considerations

Completion checklist before leaving draft (required work, not optional follow-ups). Checked items are implemented and locally verified; unchecked items remain incomplete or await current-head verification:

• GUI preparation, permission review, launch, output and stop controls
• Operator-facing CLI/MCP integration through the same session mechanism
• Bounded session I/O, cancellation and lifecycle tests
• Explicit agent-only MCP endpoint/token handling
• Runnable developer CLI policy examples
• Initial GUI tests and complete local composeApp:desktopTest, sandbox tests and lint
• End-to-end agent escalation GUI tests and full repository test/build CI for the current head
• Passing Linux, macOS and Windows native enforcement
• Final security and implementation review

The initial session transport uses pipes; an interactive PTY is not promised. Review Focus Areas below identify requested review topics, not completed verification. All six are selected because this change affects process logic, resource use, security, three desktop platforms, GUI behavior and documentation.

👀 Review Focus Areas

• Logic and Algorithm: Core functionality and business logic
• Performance: Potential performance implications
• Security: Security considerations and best practices
• Platform Compatibility: Cross-platform compatibility
• User Experience: UI/UX improvements or changes
• Documentation: Accuracy and completeness of documentation

🚨 Pre-merge Checklist

The required base for this contribution is the fork's dev, not main. The fork's dev was fast-forwarded to upstream dev at 8c83aef6; this branch was rebased onto it. range-diff confirmed all 17 original contribution commits were unchanged by that rebase. Four GUI/service/MCP integration commits have since been added; the PR diff still contains only this contribution.

• All conversations have been resolved
• Code has been rebased on latest main branch
• Commit messages are clear and descriptive
• PR title accurately describes the change
• Ready for production deployment

---

Thank you for contributing to BOSS! 🎉