Crate agent_bridle_tool_shell 

agent-bridle-tool-shell — capability-confined safe-subset, Brush, and host-shell engines.

Per ADR 0005 the object-capability boundary is L3 (kernel) and this crate supplies complementary L2 engines. The lean ShellTool is an exec funnel: it parses each request itself ([crate::parse]), accepts argv form (program + args) or a restricted free-form cmd, checks the exec/fs leash, spawns directly, and refuses dynamic constructs by design (command substitution $(...), arithmetic expansion $((...)), backticks, and subshells). [BrushShellTool] instead carries full Brush grammar in a dedicated worker; its interceptor gates the worker’s own external spawns and opens. When effective caveats engage an available Landlock, Seatbelt, or AppContainer backend, the worker/process tree inherits that L3 boundary; otherwise the run honestly reports agent_bridle_core::SandboxKind::None (I9). Coverage is per-axis and scope-shaped: inspect the result’s enforcement report rather than inferring every guarantee from the coarse sandbox kind.

The engine (agent-bridle#34 Track A + #45): a sequence of pipelines joined by &&/||/; (short-circuit semantics), each pipeline simple commands with quoted arguments, redirections (> out, >> out, < in, 2> err, 2>&1), filename globbing (*/?/[…]) and allowlisted $VAR expansion — every filesystem/env touch bridle performs (redirect opens, glob directory listings, variable allowlist) is leash-/policy-checked before any spawn. Those dynamic constructs stay refused by the safe-subset engine. The process spawning is behind a Spawner seam (mocked in unit tests; real path in tests/real_spawn.rs). Brush is the carried full-grammar alternative behind the same construction-time registry seam.

Structs

JsonlSink

Network egress audit surface (#124, ADR 0016): the loopback proxy records every proxy-visible connection as a NetAuditEvent through an AuditSink (default off; enable via the BRIDLE_NET_AUDIT setting). The bridle-netmon binary renders the JSON-lines stream as a live monitor. Append each event as one JSON line to a Write (a file, stderr, a pipe).

NetAuditEvent

Network egress audit surface (#124, ADR 0016): the loopback proxy records every proxy-visible connection as a NetAuditEvent through an AuditSink (default off; enable via the BRIDLE_NET_AUDIT setting). The bridle-netmon binary renders the JSON-lines stream as a live monitor. One audited egress connection through the proxy — a complete record of the child’s proxy-visible network activity (#124, ADR 0016). Serialised as one JSON line by JsonlSink; the bridle-netmon binary renders a live view.

NullSink

Network egress audit surface (#124, ADR 0016): the loopback proxy records every proxy-visible connection as a NetAuditEvent through an AuditSink (default off; enable via the BRIDLE_NET_AUDIT setting). The bridle-netmon binary renders the JSON-lines stream as a live monitor. The default sink — discard everything (audit off, zero overhead).

ShellInvocationId

Process-local identity for one shell tool invocation.

ShellTool

The confined shell tool.

Enums

NetDecision

Network egress audit surface (#124, ADR 0016): the loopback proxy records every proxy-visible connection as a NetAuditEvent through an AuditSink (default off; enable via the BRIDLE_NET_AUDIT setting). The bridle-netmon binary renders the JSON-lines stream as a live monitor. The proxy’s allow-list decision for one connection.

NetKind

Network egress audit surface (#124, ADR 0016): the loopback proxy records every proxy-visible connection as a NetAuditEvent through an AuditSink (default off; enable via the BRIDLE_NET_AUDIT setting). The bridle-netmon binary renders the JSON-lines stream as a live monitor. The kind of egress a child requested through the proxy.

ShellOutputStream

The file descriptor from which an observed shell-output chunk originated.

Traits

AuditSink

Network egress audit surface (#124, ADR 0016): the loopback proxy records every proxy-visible connection as a NetAuditEvent through an AuditSink (default off; enable via the BRIDLE_NET_AUDIT setting). The bridle-netmon binary renders the JSON-lines stream as a live monitor. A destination for NetAuditEvents — the operator’s audit trail. record is called from a per-connection thread, so implementations must be thread-safe and must never block the connection for long.

ShellOutputObserver

Receives bounded shell output while a tool invocation is still running.