Documentation
¶
Overview ¶
Package access decides whether a tool may do something: the policies on commands and paths, and the permission requests that go with them. It runs nothing: internal/sandbox does that.
Index ¶
- Constants
- func BuildToolPermissionRequest(req PermissionRequest, opts ToolPermissionOptions) (types.ToolPermissionRequest, error)
- func ErrorForDecision(result DecisionResult) error
- func ErrorForPermissionResult(result types.PermissionResult, fallbackReason string) error
- func ResolveToolPermission(ctx context.Context, checker types.CanUseToolFn, req PermissionRequest, ...) (types.PermissionResult, error)
- type AccessKind
- type ApprovalRequiredError
- type ApprovalScope
- type CommandPolicy
- type Context
- type Decision
- type DecisionResult
- type FilesystemPolicy
- type PathDecision
- type PermissionDecision
- type PermissionDeniedError
- type PermissionRequest
- type ToolAccessPreview
- type ToolPermissionOptions
Constants ¶
const ( MetadataRequestKey = "sandbox_request" MetadataPreviewKey = "sandbox_preview" )
Variables ¶
This section is empty.
Functions ¶
func BuildToolPermissionRequest ¶
func BuildToolPermissionRequest(req PermissionRequest, opts ToolPermissionOptions) (types.ToolPermissionRequest, error)
BuildToolPermissionRequest converts a normalized sandbox request into the runtime permission request expected by the engine.
func ErrorForDecision ¶
func ErrorForDecision(result DecisionResult) error
ErrorForDecision converts a normalized decision into a conventional Go error.
func ErrorForPermissionResult ¶
func ErrorForPermissionResult(result types.PermissionResult, fallbackReason string) error
ErrorForPermissionResult converts a runtime permission result into a conventional Go error.
func ResolveToolPermission ¶
func ResolveToolPermission( ctx context.Context, checker types.CanUseToolFn, req PermissionRequest, opts ToolPermissionOptions, ) (types.PermissionResult, error)
ResolveToolPermission runs the normalized request through the active permission resolver.
Types ¶
type AccessKind ¶
type AccessKind string
AccessKind describes the resource access being requested.
const ( AccessRead AccessKind = "read" AccessWrite AccessKind = "write" AccessCreate AccessKind = "create" AccessDelete AccessKind = "delete" AccessSearch AccessKind = "search" AccessExecute AccessKind = "execute" AccessEscalate AccessKind = "escalate" )
type ApprovalRequiredError ¶
type ApprovalRequiredError struct {
Reason string
}
ApprovalRequiredError is returned when an action is valid but needs approval.
func (*ApprovalRequiredError) Error ¶
func (e *ApprovalRequiredError) Error() string
type ApprovalScope ¶
type ApprovalScope string
ApprovalScope controls how long an approval grant should remain valid.
const ( ApprovalScopeToolCall ApprovalScope = "tool_call" ApprovalScopeTurn ApprovalScope = "turn" ApprovalScopeSession ApprovalScope = "session" )
type CommandPolicy ¶
type CommandPolicy struct {
// contains filtered or unexported fields
}
CommandPolicy is the single authoritative command safety classifier. It replaces the scattered PermissionValidator in the bash package.
Two-tier model (mirrors Codex):
- IsKnownSafe: explicit allowlist → bypass approval entirely
- Evaluate: deny/ask/allow based on danger fragments and command type
func NewDefaultCommandPolicy ¶
func NewDefaultCommandPolicy() *CommandPolicy
func (*CommandPolicy) AskCommands ¶
func (p *CommandPolicy) AskCommands() []string
AskCommands returns the bare command names that always require explicit approval, for introspection (e.g. the get_config tool).
func (*CommandPolicy) DenyFragments ¶
func (p *CommandPolicy) DenyFragments() []string
DenyFragments returns the substrings that cause a command to be hard-denied regardless of mode, for introspection (e.g. the get_config tool).
func (*CommandPolicy) DenyPatterns ¶
func (p *CommandPolicy) DenyPatterns() []string
DenyPatterns returns the regex source strings that cause a command to be hard-denied regardless of mode, for introspection (e.g. the get_config tool).
func (*CommandPolicy) Evaluate ¶
func (p *CommandPolicy) Evaluate(command string) DecisionResult
Evaluate returns the policy decision for a command.
Order of evaluation:
- Known-safe allowlist → Allow (no approval prompt needed)
- Shell wrapper → evaluate composed inner
- Deny fragment match → Deny
- Ask-command list → Ask
- Command type classification: write/vcs/unknown → Ask, read/search/state → Allow
func (*CommandPolicy) IsKnownSafe ¶
func (p *CommandPolicy) IsKnownSafe(command string) bool
IsKnownSafe returns true when every sub-command in the expression is on the explicit safe allowlist, meaning the entire command can be executed without any approval prompt.
Mirrors Codex's is_known_safe_command. If the command is a shell wrapper (bash -c "…") the inner script is split into segments and each is checked.
type Context ¶
type Context struct {
WorkingDirectory string
WorkspaceRoot string
AdditionalRoots []string
Environment sandbox.EnvironmentKind
SandboxEnabled bool
}
Context carries the execution boundary relevant to sandbox decisions.
func (Context) ResolvePath ¶
ResolvePath resolves a candidate path according to the current execution context. When a WorkspaceRoot is configured, relative paths are anchored to the root and validated to stay inside it. Absolute paths bypass workspace containment so the user can approve writes to /tmp or other out-of-workspace directories — the FilesystemPolicy dangerous-prefix check still applies downstream.
type DecisionResult ¶
DecisionResult is the normalized output of a policy decision.
type FilesystemPolicy ¶
type FilesystemPolicy struct {
// contains filtered or unexported fields
}
FilesystemPolicy centralizes common filesystem access checks.
func NewDefaultFilesystemPolicy ¶
func NewDefaultFilesystemPolicy() *FilesystemPolicy
func (*FilesystemPolicy) EvaluatePath ¶
func (p *FilesystemPolicy) EvaluatePath(ctx Context, path string, access AccessKind) (PathDecision, error)
func (*FilesystemPolicy) ReadDeniedPrefixes ¶
func (p *FilesystemPolicy) ReadDeniedPrefixes() []string
ReadDeniedPrefixes returns the path prefixes read access is denied under, for introspection (e.g. the get_config tool) - not a mutable handle.
func (*FilesystemPolicy) WriteDeniedPrefixes ¶
func (p *FilesystemPolicy) WriteDeniedPrefixes() []string
WriteDeniedPrefixes returns the path prefixes write access is denied under, for introspection (e.g. the get_config tool) - not a mutable handle.
type PathDecision ¶
type PathDecision struct {
DecisionResult
ResolvedPath string
}
PathDecision includes the resolved path for filesystem checks.
type PermissionDecision ¶
type PermissionDecision struct {
Decision Decision
Reason string
Scope ApprovalScope
ApprovedPaths []string
Metadata map[string]any
}
PermissionDecision is the normalized response returned by the sandbox/approval layer.
func (PermissionDecision) IsAllowed ¶
func (d PermissionDecision) IsAllowed() bool
IsAllowed reports whether the request was approved.
type PermissionDeniedError ¶
type PermissionDeniedError struct {
Reason string
}
PermissionDeniedError is returned when the sandbox denies an action outright.
func (*PermissionDeniedError) Error ¶
func (e *PermissionDeniedError) Error() string
type PermissionRequest ¶
type PermissionRequest struct {
ToolName string
Description string
Environment sandbox.EnvironmentKind
Access AccessKind
Command string
Paths []string
NetworkTargets []string
Justification string
Scope ApprovalScope
Metadata map[string]any
}
PermissionRequest is the normalized request emitted by tools and runtimes when they need a sandbox/approval decision.
func (PermissionRequest) DescriptionText ¶
func (r PermissionRequest) DescriptionText() string
DescriptionText returns a stable approval-friendly description.
func (PermissionRequest) MetadataMap ¶
func (r PermissionRequest) MetadataMap() map[string]any
MetadataMap returns stable metadata for the shared permission pipeline.
func (PermissionRequest) Validate ¶
func (r PermissionRequest) Validate() error
Validate ensures a permission request is structurally usable by the approval pipeline.
type ToolAccessPreview ¶
type ToolAccessPreview struct {
ToolName string `json:"tool_name"`
Environment string `json:"environment,omitempty"`
Access string `json:"access,omitempty"`
Command string `json:"command,omitempty"`
Paths []string `json:"paths,omitempty"`
NetworkTargets []string `json:"network_targets,omitempty"`
Justification string `json:"justification,omitempty"`
}
ToolAccessPreview is the normalized human-facing summary of what a tool is asking to do.
func BuildPreview ¶
func BuildPreview(req PermissionRequest) ToolAccessPreview
BuildPreview converts a permission request into a stable preview payload.
type ToolPermissionOptions ¶
type ToolPermissionOptions struct {
ToolInput map[string]any
ToolUseID string
SessionID types.SessionID
TurnID types.TurnID
PermissionMode types.PermissionMode
WorkingDirectory string
IsToolRunningInSandbox bool
Stage types.ToolPermissionStage
Intent types.ToolPermissionIntent
Metadata map[string]any
}
ToolPermissionOptions carries runtime-specific fields for the shared permission pipeline request.
Source Files