Crate locode_host 

locode-host — the one place the system touches the OS (ADR-0008).

Every side effect funnels through the Host: a path jail, shell execution with a timeout + output cap, jailed filesystem helpers, and the shared post-processes. Tools never call std::fs/Command directly — they go through a Host. This crate is a sibling of locode-tools, so it defines its own plain error types; the harness pack (which depends on both) maps them to ToolError::Respond.

Structs

DirEntry

One entry in a directory listing.

ExecLimits

Limits on shell execution. Defaults mirror Grok Build (the primary model).

ExecOutput

The captured result of a command (completed, timed out, or cancelled).

ExecRequest

A command to run through the host’s shell.

FileRead

A file’s contents plus its stat (the stat is the freshness token edits compare).

FileStat

A file’s size and last-modified time.

FrontBackCapture

The combined front/back capture (present when the request asked for it).

FrontBackSpec

Opt-in combined-stream retention (Task 26 Slice 0b; grok’s bash capture shape): keep the first and last halves of a char budget, stream the full output to a host-owned spill file. The pack renders separators/headers — the host returns structure only.

Host

The injectable side-effect seam (ADR-0008). Construct once per session, share behind an Arc; holds the jail root + policy and the exec/truncation limits.

HostConfig

Construction-time configuration for a Host.

ShellSpec

A harness’s shell invocation shape (plan-finalization Q5, 2026-07-21): the choice rides the request; execution stays behind the host door. Grok’s shape is { detect_program: true, login_arg: false, login_path_probe: true }.

WalkEntry

One traversal entry (the root itself is not reported).

WalkOptions

Options for Host::walk.

Enums

ExecError

A failure to spawn or capture — not a failed command (that is a successful capture with a non-zero exit_code).

FsError

A filesystem operation failure.

PathError

A path-jail failure.

PathPolicy

Whether the filesystem tools are jailed to the workspace root (ADR-0008 amendment).

Constants

SPILL_RETAIN_MAX

Hard cap on bytes written to a spill file (grok retains ≤ 64 MiB).

Functions

rg_program

The ripgrep program to invoke: the LOCODE_RG_PATH override, else bare rg on PATH (invoked by name — PATH-hijack hygiene, per Claude Code).