Documentation
¶
Overview ¶
Package bash implements the Bash tool: single-command shell execution inside a workspace-contained working directory, with a bounded timeout and a capped combined-output capture. Preparation (prepare.go) owns the whole argument boundary and emits one typed, command-backed access request — the exact normalized command plus one requirement per explicitly declared filesystem/network delta (a request for authority, never a grant). Execution runs directly via `sh -c` or through an optional injected confined runner.
supervised.go routes a SUPERVISED Bash call (background or yield_time_ms, normalized by prepare.go's normalizeSupervision into bashArtifact.supervised) through the shared, runner-free process.Supervisor. A legacy call never reaches this file: bash.go's InvokableRun dispatches to runSupervised only when the prepared artifact says so; every other call keeps executing the unchanged synchronous `sh -c` (or injected tool.CommandRunner) path.
The concrete BashTool built by NewSupervisedFactory already owns, from its bound construction data (Bindings, resolved once at Build), the async process runner, the session resource registry, the owning session/loop identity, the workspace coordinator, and the observation capability. runSupervised never looks up invocation provenance to select a runner — b.asyncRunner is a fixed field set at Build.
Index ¶
- type BashOption
- type BashTool
- func (b *BashTool) AuditSummary(argsJSON string) string
- func (b *BashTool) Info(context.Context) (*tool.ToolInfo, error)
- func (b *BashTool) InvokableRun(ctx context.Context, _ string) (*tool.ToolResult, error)
- func (b *BashTool) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
- type Factory
- type SupervisedFactory
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BashOption ¶
type BashOption func(*BashTool)
BashOption configures a BashTool at construction (functional-options pattern).
func WithFamilyCatalog ¶
func WithFamilyCatalog(eligible permission.FamilyEligibility) BashOption
WithFamilyCatalog injects the consumer's explicit eligible-prefix catalog for AUTOMATIC family candidate proposal (spec: unknown prefixes fail closed to an exact proposal). The catalog affects only which reusable candidate is DISPLAYED; it never widens the requirement or the issued exact-command grant. Nil (the default) proposes exact candidates only.
func WithObservations ¶
func WithObservations(obs tool.WorkspaceObservations) BashOption
WithObservations binds the loop's shared file-observation set so a command run invalidates it wholesale afterward (the changed paths are unknowable). A nil or typed-nil set is ignored (no invalidation).
func WithRunner ¶
func WithRunner(r tool.CommandRunner) BashOption
WithRunner injects a confined command runner. When set, InvokableRun routes the command through r.RunCommand instead of the direct `sh -c` path. A nil runner (the default) preserves the exact bare-harness direct-execution behavior.
func WithWorkspaceCoordinator ¶
func WithWorkspaceCoordinator(coord tool.WorkspaceCoordinator) BashOption
WithWorkspaceCoordinator binds the session workspace coordinator so a command run holds the EXCLUSIVE whole-workspace mutation permit (design §"File-tool optimistic concurrency and binding"). A nil or typed-nil coordinator is ignored (the tool runs coordinator-free — the standalone/bare path).
type BashTool ¶
type BashTool struct {
// contains filtered or unexported fields
}
BashTool runs a single shell command in a workspace-contained directory. It depends on the workspace root and an optional confined-execution runner; command policy is decided by the harness gate over the prepared request, against rules stored in the permission package's workspace store. A nil runner means direct `sh -c` execution (the bare-harness default), while an invalid option or typed-nil runner fails closed through a model-safe error.
func NewBash ¶
func NewBash(root string, opts ...BashOption) *BashTool
NewBash constructs a BashTool bound to the workspace root. With no options, or WithRunner(nil), the tool uses direct execution. Invalid options and typed-nil runners are retained as initialization errors and fail closed when invoked.
func (*BashTool) AuditSummary ¶
AuditSummary returns the command itself — it is exactly what the user approves at the gate, so it is the right (and only) redacted summary. No secrets are added beyond the command the user already sees. An unparseable args document yields a generic summary.
func (*BashTool) InvokableRun ¶
InvokableRun executes the PREPARED artifact bound to this call — the raw argsJSON is never reparsed, so mutating it after preparation changes nothing; without its artifact the tool fails closed. The command runs through the bound runner with the PreparedCall's issued grant tokens (the runner MAC verifies them; Bash only carries the opaque strings). A non-zero exit is a normal result; a timeout or start failure is a tool-result error string. It never returns a Go error.
func (*BashTool) PrepareCall ¶
func (b *BashTool) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
PrepareCall decodes, validates, and normalizes one Bash call and produces its typed access request: the command.execute requirement (grant class command.start.v1, grant target = Match = the exact normalized command) plus one requirement per declared delta, all in ONE request so a gated command and its deltas share a single combined approval.
type Factory ¶
type Factory func(root string, coordinator tool.WorkspaceCoordinator, observations tool.WorkspaceObservations) *BashTool
Factory is an immutable Bash construction blueprint. It resolves options once and binds per-Loop workspace services without reapplying caller closures.
func NewFactory ¶
func NewFactory(options ...BashOption) (Factory, error)
NewFactory validates and seals Bash options for use by a definition builder.
type SupervisedFactory ¶
type SupervisedFactory func(bindings tool.Bindings, runner tool.AsyncProcessRunner) (*BashTool, error)
SupervisedFactory builds a session-supervised BashTool bound to bindings and the caller's already-resolved, validated tool.AsyncProcessRunner. bindings must satisfy tool.RequiresWorkspace|tool.RequiresProcessServices (the harness Definition.Build boundary validates SessionID/LoopID/ Workspace/Process before any factory ever runs); runner is a per-Build input the caller resolved from the validated bound LoopID BEFORE calling this factory — never derived here from ctx or invocation provenance. Task 19's root definition owns that resolver; this task only accepts its already-resolved result.
func NewSupervisedFactory ¶
func NewSupervisedFactory(options ...BashOption) (SupervisedFactory, error)
NewSupervisedFactory validates and seals Bash options once, exactly like NewFactory, for a session-supervised binding. It never adds a Runner field to tool.ProcessBinding and never accepts a runner as one of options: the async runner is a distinct per-Build input to the returned SupervisedFactory, not a sealed BashOption.
Source Files