Sandbox structured cask operations

[MikeMcQuaid]

• Run each complete cask step block in one isolated subprocess and all generated completions in another phase-scoped sandbox.
• Share sandbox selection, fork fallback, install-hook rules and child error reporting with formula build, post-install and test processes.
• Restrict home, network and filesystem access while preserving brew and supporting explicit command write paths.
• Keep JSON payloads compact and independent of cask Ruby files.
• Remove the completed official-tap migration plan.

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• I did not use AI/LLM to create this PR, or I disclosed the tool/model below and reviewed its output; I did not attribute commits to AI and will answer maintainer questions and review comments myself without AI/LLM.

Codex 5.6 Sol xhigh with local review and testing.

---

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR centralizes forked-child error reporting, expands sandbox helpers, and runs cask install-step and completion-generation work inside a sandboxed Ruby subprocess (aligning behavior with formula post-install sandboxing).

Changes:

• Add shared Utils helpers for receiving the error pipe and serializing child exceptions.
• Introduce Sandbox.use_for?, Sandbox.run_or_fork, and Sandbox.with_preserved_brew_file, and refactor call sites to use them.
• Sandbox cask install steps + generated completions by delegating to a new cask_artifact.rb runner subprocess, plus documentation and test updates.

Reviewed changes

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

Show a summary per file

File	Description
docs/Formula-Cookbook.md	Documents that run in formula post-install steps executes inside the post-install sandbox.
docs/Cask-Cookbook.md	Clarifies sandboxing model for cask generated completions and steps blocks.
Library/Homebrew/utils/fork.rb	Adds shared helpers to read error pipe and serialize/report forked child errors.
Library/Homebrew/test/utils/fork_spec.rb	Adds coverage for Utils.child_error_hash preserving BuildError details.
Library/Homebrew/test/sandbox_shared_spec.rb	Adds tests for new sandbox helper APIs and shared install hook rules.
Library/Homebrew/test/rubocops/cask/install_steps_spec.rb	Updates expected step DSL usage to include new writable path declarations.
Library/Homebrew/test/install_steps_spec.rb	Updates run-step serialization expectations to include writable_paths.
Library/Homebrew/test/formula_spec.rb	Ensures post-install isolated home is created under HOMEBREW_TEMP.
Library/Homebrew/test/formula_installer_spec.rb	Adds coverage for sandboxed structured post-install steps; updates sandbox execution expectations.
Library/Homebrew/test/cask/artifact/install_steps_spec.rb	Adds integration coverage asserting full block sandboxing including system commands.
Library/Homebrew/test/cask/artifact/generated_completion_spec.rb	Refactors generated completion tests to run through the new sandboxed subprocess payload.
Library/Homebrew/test.rb	Refactors error pipe handling via Utils.forked_child_error_pipe and shared reporting.
Library/Homebrew/sandbox.rb	Adds use_for?, run_or_fork, with_preserved_brew_file, and add_install_hook_rules.
Library/Homebrew/postinstall.rb	Refactors error pipe handling via new shared Utils helpers.
Library/Homebrew/json_api_postinstall_preflight_postflight_plan.md	Removes the (now obsolete) migration plan doc from the repo.
Library/Homebrew/install_steps.rb	Adds writable_paths to run steps and computes sandbox write-paths for steps.
Library/Homebrew/formula_installer.rb	Uses Sandbox.run_or_fork and Sandbox.with_preserved_brew_file for build/post-install execution.
Library/Homebrew/formula.rb	Creates post-install isolated HOME under HOMEBREW_TEMP.
Library/Homebrew/dev-cmd/test.rb	Uses Sandbox.run_or_fork for running formula tests in a sandbox when available.
Library/Homebrew/cask_artifact.rb	New sandboxed subprocess entrypoint to run cask install steps and generated completions from JSON payloads.
Library/Homebrew/cask/artifact/install_steps.rb	Runs cask install steps either directly or via sandboxed subprocess payload.
Library/Homebrew/cask/artifact/generated_completion.rb	Runs completion generation either directly or via sandboxed subprocess payload.
Library/Homebrew/cask/artifact/abstract_artifact.rb	Switches cask sandboxing to a full subprocess model with JSON payloads and shared sandbox rules.
Library/Homebrew/build.rb	Refactors error pipe handling via new shared Utils helpers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.