Spice Agent Coding Tools

Unified documentation: spiceframework.dev/agent/tools/coding.

spice-agent-tools-coding provides the opt-in read, atomic replace/write, and shell tools for Spice Agent. It is standard-library-first, instance-owned, and designed for generated Spice dependency injection.

Install the module and exact Spice compiler tool:

go get github.com/spice-framework/spice-agent-tools-coding@<version>
go get -tool github.com/spice-framework/toolchain/cmd/spice@v0.1.0-preview.1.0.20260806203056-d0b9ac086bd6

Applications opt into defaults only with:

import _ "github.com/spice-framework/spice-agent-tools-coding/autoconfigure"

Importing the root package alone never activates tools. The application owns a typed coding.Config, including its absolute worktree root, byte/time bounds, and inherited-environment allowlist. Direct composition uses exact factories:

read, err := coding.NewRead(config)
replace, err := coding.NewReplace(config)
shell, cleanup, err := coding.NewShell(config, executableResolver, processLauncher)

Construction performs no filesystem or process action. NewShell requires the public Spice Agent process.ExecutableResolver and process.Launcher interfaces and returns a Spice lifecycle.Cleanup; applications provide the platform implementation as ordinary typed beans. The coding-tools module does not contain a second os/exec launcher. The explicit /autoconfigure package contributes those same three factories as fallback beans through generated Spice DI; there is no global registry.

• read uses relative paths and offset/limit paging. A complete page includes a SHA-256 suitable for a later bounded replace. It declares read_only and safe replay.
• replace requires either create=true for no-overwrite creation or the exact lowercase expected_sha256 for replacement. Results distinguish committed state from confirmed durability. It declares mutating and idempotent: replay after a lost acknowledgement cannot repeat the file effect because create observes the existing target and replace observes the consumed digest. A replacement whose content already has the expected digest is an explicit successful no-op (changed=false, committed=false).
• shell accepts discrete argv and an optional relative workdir. It never invokes a command shell. It builds an immutable lookup from that argv, canonical workdir, and the application-allowlisted environment, then launches the resolver's exact absolute path through the injected launcher. It reports captured/observed byte counts plus deterministic truncation metadata. It declares mutating and unsafe replay because an arbitrary process may have committed effects before its outcome becomes unavailable.

Argument, path, operating-system, timeout, exit, stale-write, and durability problems are bounded model-visible tool.Result values. Cancellation and host progress/result-delivery failures return a zero result with one direct, correlated *tool.ExecutionError; cancellation and deadline identity remains available through errors.Is. Callers must inspect both return values and must not infer replay safety from capabilities alone.

Security warning: these tools can read and write files, execute processes, and use network or environment access with the operating-system user's privileges. They provide no sandbox or approval prompt. The shell child's authority is not confined to the configured worktree. Platform containment belongs to the injected launcher. managed_cleanup_completed means the launcher's typed Wait proved its owned resources safe to release; it is not a claim about descendants the platform implementation never owned.

Read and replace paths use os.Root. Shell workdirs reject symbolic-link components and are revalidated before launch; executable discovery uses only the explicit workdir and environment passed to the injected resolver. Same-user concurrent path mutation remains a trust boundary. Expected hashes detect ordinary stale writes; they are not an atomic filesystem compare-and-swap against another process racing the final commit.

See the dependency review, security review, and support matrix.

On a fresh clone, run make tools-bootstrap once to populate the exact product and tools module graphs without changing tracked module files. All ordinary quality targets remain offline; run the complete suite with make verify.

Release contract

spice-release.json is inert, canonical metadata for the centrally authorized go-module-v1 release profile. make verify-release runs the repository's complete local gate. The organization release authority independently binds the repository name, module path, exact preview version, required module graph, commit, and tag before it creates any artifact or release. The current preview graph selects Spice v0.1.0-preview.2, Spice Agent v0.1.0-preview.4, and the unchanged exact Spice toolchain pseudo-version. The release caller is a single step-free reusable-workflow job pinned to the reviewed organization authority; repository verification rejects extra jobs, permissions, local steps, inherited secrets, or mismatched attestation pins.