Documentation
¶
Overview ¶
Package readfile implements the ReadFile tool: a workspace-contained, denied-path-aware, symlink-rejecting file reader returning line-numbered text capped by the injected ReadGuard. Preparation emits the direct filesystem.read requirement for the canonical resolved path; the tool enforces the approved resolved resource itself at run time.
Index ¶
- type ReadFile
- func (r *ReadFile) AuditSummary(argsJSON string) string
- func (r *ReadFile) Info(context.Context) (*tool.ToolInfo, error)
- func (r *ReadFile) InvokableRun(ctx context.Context, _ string) (*tool.ToolResult, error)
- func (r *ReadFile) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
- type ReadFileOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ReadFile ¶
type ReadFile struct {
// contains filtered or unexported fields
}
ReadFile reads a workspace-contained text file. It depends only on the workspace root, a narrow loop.ReadGuard (least privilege / interface segregation), and the loop's shared observation map: it never sees the full permission gate.
func NewReadFile ¶
func NewReadFile(root string, guard loop.ReadGuard, obs tool.WorkspaceObservations, opts ...ReadFileOption) *ReadFile
NewReadFile constructs a ReadFile bound to the workspace root, read guard, and the loop's shared observation map. A complete read records the raw-content hash into obs so a subsequent same-loop WriteFile/EditFile of the same path is authorized; obs is supplied by Files (one per loop binding).
func (*ReadFile) AuditSummary ¶
AuditSummary returns a redacted, content-free one-line summary: the path only (never file contents). An unparseable args document yields a generic summary.
func (*ReadFile) 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. Every failure mode (denied path, changed resolution, symlink, not-found, not-regular, read error) is returned as a tool-result error string — never a Go error and never echoing a secret's contents.
func (*ReadFile) PrepareCall ¶
func (r *ReadFile) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)
PrepareCall decodes and validates the untrusted arguments ONCE, resolves the canonical read target ONCE, and returns the typed request — one direct filesystem.read requirement whose Scope and Match are the canonical resolved path, empty grant pair — plus the typed artifact InvokableRun executes. Invalid input fails here and never reaches the permission gate.
type ReadFileOption ¶
type ReadFileOption func(*ReadFile)
ReadFileOption configures a ReadFile at construction (functional-options pattern, matching grep.GrepOption).
func WithHostReads ¶
func WithHostReads() ReadFileOption
WithHostReads lets an absolute path resolve OUTSIDE the workspace instead of being rejected at prepare time. It does not itself grant anything: an uncontained resolved path still emits the same filesystem.read requirement PrepareCall always has, so the consumer's bound access source (the selected sandbox.Profile in the product composition root) makes the actual Allow/Deny/Gated decision -- the same authority a spawned Bash command's host reads already go through. Without this option, ReadFile's behavior is unchanged: any path outside the workspace is rejected lexically before a requirement is ever built. A RELATIVE "../" traversal is NEVER widened by this option -- only a literal absolute path argument can resolve outside the workspace (workspace.ResolvedPath). A successful uncontained read never records an observation (see InvokableRun): a host read must not feed the same-loop write-authorization map, since WriteFile/EditFile remain workspace-confined regardless of this option.
Source Files