feat(process): read-only file-injection in spawn-request

[joshuajbouw]

Summary

Adds the file-injection record + injection-placement variant and a file-injections field (honored by every tier) to spawn-request in astrid:[email protected]. The host exposes host-verified, read-only bytes to a spawned child's existing OS sandbox. content is opaque to the host; the capsule supplies the bytes plus how the child should find them, and the host owns placement, integrity, and exposure.

Two placement modes (same verified bytes, read-only)

• env-pointer(env-var) — the host materializes the snapshot at a host-owned path, exposes it read-only, and sets the named env var to it. OS-agnostic (Linux + macOS); the host owns the path, so there's no caller-chosen target and no host write to a caller-named path. For agents whose un-overridable tier is reachable via an env-redirected file: Claude CLAUDE_CODE_MANAGED_SETTINGS_PATH, Gemini GEMINI_CLI_SYSTEM_SETTINGS_PATH.
• fixed-path(path) — the host --ro-binds the snapshot at an absolute in-sandbox path. Linux-only (bwrap remap); rejected on macOS with invalid-input (no remap; a host write to a caller-named path would be an escalation). For agents whose enforced tier is a fixed path with no env redirect: Codex /etc/codex/requirements.toml.

Guarantees

• Write-protection invariant: the bytes are unwritable by the child AND by the spawning principal's capsule fs_* surface.
• Integrity contract: snapshot → host-owned path outside every VFS mount, BLAKE3 hash pinned + verified before exposure, hash recorded in the spawn audit, never a live bind of the source bytes.
• No new capability / no escalation: rides host_process, into the caller's own child only; the host owns placement in both modes, so it never writes to a caller-named host path.

Notes

• Specified in the Host ABI RFC: RFC: Host ABI rfcs#22 ("Read-only file injection").
• scripts/validate-wit.sh passes.
• Consumed by the core implementation (feat(capsule): read-only file-injection for sandboxed spawns astrid#890); core pins this commit as its wit/ submodule.
• Supersedes the earlier {source, target, read-only} shape (force-pushed): content bytes remove the host-side read / read-gate and the home-staged file, and the two-mode placement makes the capsule OS-agnostic in env-pointer mode while removing a macOS arbitrary-write escalation present in the prior shape.

[gemini-code-assist]

Code Review

This pull request introduces a new file-injection record and a file-injections field to the spawn-request record in the host/[email protected] interface, allowing read-only files to be materialized inside a spawned child's OS sandbox. The review comments suggest clarifying the behavior when the parent directory of a target path does not exist, and specifying how duplicate target paths in the file-injections list are handled.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The behavior when the parent directory of the target path does not exist should be explicitly defined, especially given the platform-specific differences (Linux bwrap vs. macOS Seatbelt). Clarifying whether the host implicitly creates missing parent directories or if the spawn fails with invalid-input ensures consistent host implementations.

        /// Absolute path at which the child reads the injected bytes. See the
        /// per-OS mechanism above for the platform constraints on `target`.
        /// Non-absolute paths or paths where the parent directory cannot be
        /// created/resolved fail the spawn with `invalid-input`.
        target: string,

[gemini-code-assist]

Specifying how duplicate target paths in the file-injections list are handled is important to prevent conflicting mounts or undefined behavior. If multiple injections specify the same target, the spawn should be explicitly rejected with invalid-input.

        /// Read-only files the host materializes inside the child's sandbox.
        /// Applies to EVERY tier. Each entry places host-verified, unmodifiable
        /// bytes at an absolute path (see `file-injection`); empty => no
        /// injection. Duplicate `target` paths are rejected with `invalid-input`.
        /// The host never parses the bytes; the BLAKE3 hash of each
        /// snapshot is recorded in the spawn audit.
        file-injections: list<file-injection>,