# Architecture

This module owns three small, instance-scoped tools. `NewRead`, `NewReplace`,
and `NewShell` return the exact public Spice Agent `tool.Tool` interface. The
root package owns validated bounds and static capability declarations.
`autoconfigure` is selected only through an explicit blank import and
contributes three exact fallback beans through ordinary generated Spice DI; it
does not register tools at runtime.

Read opens relative files through `os.Root`, returns bounded offset/limit pages,
and changes to base64 when byte content or JSON escaping requires it. Replace
writes and syncs a same-directory temporary file, revalidates the expected
SHA-256 immediately before an atomic link or replacement, and reports separately
whether the update committed and whether durability was confirmed. A
per-instance lease serializes Spice-originated writes. The expected digest is
stale-write protection, not a filesystem compare-and-swap against another
process changing the file in the final check/commit interval.

Definitions declare behavior used by dispatch policy: read is
`read_only`/`safe`, replace is `mutating`/`idempotent`, and shell is
`mutating`/`unsafe`. Replace replay is idempotent because the successful create
consumes target absence and the successful replace consumes the expected
digest; a repeated call reports already-existing or stale state without a
second mutation. Same-digest replacement is a successful no-op, preventing
inode/metadata churn from defeating this contract. This does not turn a
durability-uncertain result into a safe automatic retry decision.

Shell executes discrete argv without a shell. Its initial working directory is
opened through `os.Root`, symbolic-link components are rejected and revalidated,
and only application-allowlisted host environment variables are inherited.
After process start, the child has the operating-system user's full authority;
it is not confined to the worktree. Unix process groups and Windows kill-on-
close Job Objects provide bounded cleanup for the managed launcher and ordinary
descendants. They are not a containment boundary: a process may deliberately
detach from a Unix group, and a Windows child created before Job Object
attachment is outside that job. `managed_cleanup_completed` therefore means
the requested launcher cleanup and wait completed without error, not that every
possible descendant was terminated. Output and post-force waiting are bounded.

The module may depend on `spice-agent` after its tool contract is tagged. It
must not own an agent loop, model provider, daemon transport, service locator,
global registry, runtime package scanner, or policy engine. Every executable
route must flow through the canonical tool dispatcher so a later permission
decorator can intercept it.

The same-user trust boundary remains explicit. A concurrent actor able to
rename directories or rewrite files can race path-based process startup and the
final stale check. `os.Root`, symlink rejection, immediate revalidation, atomic
replacement, and deterministic diagnostics narrow those races but are not a
sandbox or cross-process transaction.

Expected validation and operating-system failures are terminal model-visible
results. Cooperative cancellation and host/reporting failures are direct,
bounded, call-correlated `*tool.ExecutionError` values with a zero result.
Read/replace pre-commit cancellation is definitive; shell cancellation is
uncertain after process start and never replayable. Wrapped context identity is
preserved for `errors.Is` without exposing unbounded lower-level diagnostics.