Documentation
¶
Overview ¶
Package shell hosts shell-side tools: Bash, Ls, Grep, Tree.
Bash is synchronous shell execution; Ls/Tree are filesystem listing helpers (cheaper than a Bash round-trip when you just want to look at a directory); Grep is a regex search across files. Long-running process monitoring is intentionally elsewhere (the monitor package).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Bash tools.Tool = &BashTool{}
Bash is the singleton BashTool. Stateless — every invocation spawns a fresh shell process so one instance suffices across all agents.
var Grep tools.Tool = &GrepTool{}
Grep is the singleton GrepTool. Delegates to system grep via Bash.
var Tree tools.Tool = &TreeTool{}
Tree is the singleton TreeTool. Stateless.
Functions ¶
Types ¶
type BashTool ¶
type BashTool struct{}
func (*BashTool) Description ¶
func (*BashTool) Schema ¶
func (t *BashTool) Schema() json.RawMessage
type Classification ¶
Classification is the structured result of Classify.
Matched is the rule entry that triggered the verdict — for ReadOnly it's the binary name; for Dangerous it's the prefix that matched. Surfaced in the approval UI so the user knows *why* a prompt is showing.
IsCommonFS is an orthogonal flag (NOT a Risk level) set when the binary is one of {mkdir, touch, mv, cp, rmdir, ln, chmod, chown}. The gate uses it to auto-allow these in accept_edits mode while leaving them as regular RiskMutate calls in default mode (which still asks).
func Classify ¶
func Classify(command string) Classification
Classify inspects a shell command string and returns a structured Risk assessment. The classifier:
- Splits on safe operators (`|`, `&&`) and recurses on each segment. The combined Risk is the max — a chain is only ReadOnly if every segment is ReadOnly, and is Dangerous if any segment is Dangerous.
- Blocks unsafe operators (`;`, `||`, `>`, `>>`, `<`) — they collapse the command to RiskUnknown so the gate asks.
- Strips leading `VAR=value` env assignments (POSIX prefix; not the same as `env VAR=value cmd`).
- Checks the first non-env token against the dangerous-prefix list.
- Checks the first token against the read-only allowlist.
Empty input is RiskUnknown — defensive.
type GrepTool ¶
type GrepTool struct{}
func (*GrepTool) Description ¶
func (*GrepTool) Schema ¶
func (t *GrepTool) Schema() json.RawMessage
type Risk ¶
type Risk int
Risk classifies a shell command's safety from the gate's perspective.
The gate uses Risk to drive auto mode (RiskReadOnly → allow, RiskDangerous → ask with a hint, RiskMutate/RiskUnknown → ask without a hint). Default mode treats every risk level as "ask," so a misclassification can't bypass the user — at worst it shows a prompt that didn't need to appear.
Conservative bias: RiskUnknown is the catch-all. Anything we can't confidently rate as ReadOnly stays Unknown, which forces ask.
Source Files