Documentation
¶
Overview ¶
Package grep implements the Grep tool: a workspace-contained content search that prefers ripgrep and falls back to a stdlib scan, with two-layer denied-path enforcement. Preparation emits one direct filesystem.read requirement for the canonical walked root using the tree match encoding, so a durable tree rule covers it.
Index ¶
- type Grep
- func (g *Grep) AuditSummary(argsJSON string) string
- func (g *Grep) Info(context.Context) (*tool.ToolInfo, error)
- func (g *Grep) InvokableRun(ctx context.Context, _ string) (*tool.ToolResult, error)
- func (g *Grep) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
- type GrepOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Grep ¶
type Grep struct {
// contains filtered or unexported fields
}
Grep searches workspace file contents. It depends only on the workspace root and the narrow loop.ReadGuard. useRg is resolved at construction (ripgrep on PATH) and is overridable in tests to force the deterministic fallback. argvRunner is the OPTIONAL confined-execution seam (§10.1): nil means the rg backend execs ripgrep directly (the bare-harness default), non-nil routes the built rg argv through the injected runner (e.g. the sandbox Executor).
func NewGrep ¶
func NewGrep(root string, guard loop.ReadGuard, opts ...GrepOption) *Grep
NewGrep constructs a Grep bound to the workspace root and read guard, preferring ripgrep when it is found on PATH.
func (*Grep) AuditSummary ¶
AuditSummary returns a redacted one-line summary: the pattern (and path if present) only — never any matched file content.
func (*Grep) 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. It runs the chosen backend over the approved root and renders capped, denied-filtered matches. Every failure is a tool-result string.
func (*Grep) PrepareCall ¶
func (g *Grep) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
PrepareCall decodes and validates the untrusted arguments ONCE (including compiling the pattern), resolves the canonical walk root ONCE, and returns the typed request — ONE filesystem.read requirement for the walked root (plain canonical path as Scope, canonical tree encoding as Match, empty grant pair) — plus the typed artifact InvokableRun executes. Invalid input fails here and never reaches the permission gate.
type GrepOption ¶
type GrepOption func(*Grep)
GrepOption configures a Grep at construction (functional-options pattern).
func WithArgvRunner ¶
func WithArgvRunner(r tool.ArgvRunner) GrepOption
WithArgvRunner injects a confined argv runner. When set, the rg backend routes the built ripgrep argv through r.RunArgv instead of exec.CommandContext. A nil runner (the default) preserves the exact bare-harness direct-execution behavior.
func WithHostReads ¶
func WithHostReads() GrepOption
WithHostReads lets an absolute search path resolve OUTSIDE the workspace instead of being rejected at prepare time -- the Grep counterpart to readfile.WithHostReads(). It does not itself grant anything: an uncontained resolved search root still emits the same filesystem.read requirement PrepareCall always has, so the consumer's bound access source makes the actual Allow/Deny/Gated decision. A RELATIVE "../" traversal is never widened by this option -- only a literal absolute path argument can resolve outside the workspace. Matched file paths in an uncontained (host) search are displayed relative to the SEARCHED directory itself, not the workspace root (which a host path has no meaningful relative spelling against).
Source Files