sandbox

type Action string

type AnalysisResult struct {
	Interactive bool
	Destructive bool
	Network     bool
	// TooComplex is set when the script cannot be parsed (obfuscated or invalid),
	// so a caller can treat it as higher-risk instead of trusting a clean result.
	TooComplex bool
	// Programs lists the distinct top-level command names found, for diagnostics.
	Programs []string
}

type Backend struct {
	Name            BackendName `json:"name"`
	Available       bool        `json:"available"`
	Platform        string      `json:"platform,omitempty"`
	Fallback        bool        `json:"fallback"`
	CommandWrapping bool        `json:"commandWrapping"`
	NativeIsolation bool        `json:"nativeIsolation"`
	Executable      string      `json:"executable,omitempty"`
	// ExecutableArgsPrefix is prepended to a wrapped command's args before the
	// sandbox arguments. Non-empty only for the Windows self-dispatch helper,
	// where Executable is the running zero binary and this carries the hidden
	// subcommand token (e.g. "__windows-command-runner"). nil for every other
	// backend, so their serialized form is unchanged.
	ExecutableArgsPrefix []string `json:"executableArgsPrefix,omitempty"`
	Message              string   `json:"message,omitempty"`
}

type BackendCapability struct {
	Key    string           `json:"key"`
	Status CapabilityStatus `json:"status"`
	Detail string           `json:"detail"`
}

type BackendName string

type BackendOptions struct {
	GOOS             string
	LookupExecutable func(string) (string, error)
}

type BackendPlan struct {
	Backend                 Backend             `json:"backend"`
	TargetBackend           BackendName         `json:"targetBackend"`
	WorkspaceRoot           string              `json:"workspaceRoot"`
	Policy                  Policy              `json:"policy"`
	PermissionProfile       PermissionProfile   `json:"permissionProfile"`
	CommandWrapped          bool                `json:"commandWrapped"`
	SandboxEnvMarkers       []string            `json:"sandboxEnvMarkers,omitempty"`
	EnforcementLevel        EnforcementLevel    `json:"enforcementLevel"`
	DowngradeReason         string              `json:"downgradeReason,omitempty"`
	SupportLevel            BackendSupportLevel `json:"supportLevel"`
	RequiresPlatformSandbox bool                `json:"requiresPlatformSandbox"`
	Capabilities            []BackendCapability `json:"capabilities"`
	Restrictions            []string            `json:"restrictions"`
	Warnings                []string            `json:"warnings,omitempty"`
}

type BackendSupportLevel string

type Block struct {
	Code        BlockCode `json:"code"`
	ToolName    string    `json:"toolName,omitempty"`
	Action      Action    `json:"action"`
	Risk        Risk      `json:"risk"`
	Path        string    `json:"path,omitempty"`
	Reason      string    `json:"reason"`
	Recoverable bool      `json:"recoverable"`
}

type BlockCode string

type CapabilityStatus string

type CommandPlan struct {
	Backend                 Backend           `json:"backend"`
	TargetBackend           BackendName       `json:"targetBackend"`
	WorkspaceRoot           string            `json:"workspaceRoot"`
	Policy                  Policy            `json:"policy"`
	PermissionProfile       PermissionProfile `json:"permissionProfile"`
	Wrapped                 bool              `json:"wrapped"`
	SandboxEnvMarkers       []string          `json:"sandboxEnvMarkers,omitempty"`
	EnforcementLevel        EnforcementLevel  `json:"enforcementLevel"`
	DowngradeReason         string            `json:"downgradeReason,omitempty"`
	RequiresPlatformSandbox bool              `json:"requiresPlatformSandbox"`
	Name                    string            `json:"name"`
	Args                    []string          `json:"args"`
	Dir                     string            `json:"dir,omitempty"`
	Env                     []string          `json:"env,omitempty"`
	SandboxDir              string            `json:"sandboxDir,omitempty"`
	// MonitorTag, when non-empty, is the unique marker embedded in the
	// sandbox-exec profile's denial messages; a caller passes it to
	// StartDenialMonitor to capture what the sandbox blocked. Empty unless
	// Policy.MonitorDenials is set on a macOS sandbox-exec plan.
	MonitorTag string `json:"monitorTag,omitempty"`
	// Notes records auditable least-privilege downgrade notes, such as native
	// isolation being unavailable in the selected environment. Surfaced to the
	// operator; never affects enforcement.
	Notes []string `json:"notes,omitempty"`
	// contains filtered or unexported fields
}

type CommandPrefixGrant struct {
	ToolName   string   `json:"toolName"`
	Prefix     []string `json:"prefix"`
	ApprovedAt string   `json:"approvedAt,omitempty"`
	Reason     string   `json:"reason,omitempty"`
	Session    bool     `json:"session,omitempty"`
}

type CommandPrefixInput struct {
	ToolName string
	Prefix   []string
	Reason   string
}

type CommandSpec struct {
	Name string
	Args []string
	Dir  string
	Env  []string
}

type Decision struct {
	Action       Action `json:"action"`
	Reason       string `json:"reason,omitempty"`
	Risk         Risk   `json:"risk"`
	GrantMatched bool   `json:"grantMatched,omitempty"`
	Grant        *Grant `json:"grant,omitempty"`
	Block        *Block `json:"block,omitempty"`
	// AutoAllowed marks an allow that the sandbox itself authorized without a user
	// prompt or persistent grant, such as a workspace-write file mutation or an
	// opted-in sandboxed shell command. Enforcement points treat it like a
	// grant-authorized allow so a prompt tool runs without a separately-recorded
	// PermissionGranted.
	AutoAllowed bool `json:"autoAllowed,omitempty"`
}

type DenialMonitor struct{}

type EnforcementLevel string

type Engine struct {
	// contains filtered or unexported fields
}

type EngineOptions struct {
	WorkspaceRoot string
	Policy        Policy
	Store         *GrantStore
	Backend       Backend
	Scope         *Scope
}

type FileSystemAccessMode string

type FileSystemPath struct {
	Kind    string `json:"kind,omitempty"`
	Type    string `json:"type,omitempty"`
	Path    string `json:"path,omitempty"`
	Pattern string `json:"pattern,omitempty"`
}

type FileSystemPermissions struct {
	Read             []string                 `json:"read,omitempty"`
	Write            []string                 `json:"write,omitempty"`
	DenyRead         []string                 `json:"deny_read,omitempty"`
	GlobScanMaxDepth *int                     `json:"glob_scan_max_depth,omitempty"`
	Entries          []FileSystemSandboxEntry `json:"entries,omitempty"`
}

type FileSystemPolicy struct {
	Kind                 FileSystemPolicyKind `json:"kind"`
	ReadRoots            []string             `json:"readRoots,omitempty"`
	WriteRoots           []WritableRoot       `json:"writeRoots,omitempty"`
	DenyRead             []string             `json:"denyRead,omitempty"`
	DenyWrite            []string             `json:"denyWrite,omitempty"`
	IncludePlatformRoots bool                 `json:"includePlatformRoots,omitempty"`
	AllowTemp            bool                 `json:"allowTemp,omitempty"`
}

type FileSystemPolicyKind string

type FileSystemSandboxEntry struct {
	Path   FileSystemPath       `json:"path"`
	Access FileSystemAccessMode `json:"access"`
}

type Grant struct {
	ToolName   string        `json:"toolName"`
	Scope      string        `json:"scope,omitempty"`     // absolute path, host, or "" for tool-wide
	ScopeKind  ScopeKind     `json:"scopeKind,omitempty"` // file | dir | host | "" (tool-wide)
	Decision   GrantDecision `json:"decision"`
	ApprovedAt string        `json:"approvedAt"`
	Reason     string        `json:"reason,omitempty"`
	Session    bool          `json:"session,omitempty"`
}

type GrantDecision string

type GrantInput struct {
	ToolName string
	Decision GrantDecision
	Reason   string
	// Scope is the raw path or host the grant covers; ScopeKind classifies it.
	// engine.Grant resolves path scopes to absolute paths and normalizes host
	// scopes before persisting. Both empty means a tool-wide grant.
	Scope     string
	ScopeKind ScopeKind
}

type GrantLookup struct {
	Matched bool  `json:"matched"`
	Grant   Grant `json:"grant,omitempty"`
}

type GrantStore struct {
	// contains filtered or unexported fields
}

type InteractiveCommandResult struct {
	// Interactive is true when the command launches a program that waits for
	// terminal input the agent cannot supply.
	Interactive bool
	// Command is the matched program/segment (e.g. "vim", "git rebase -i").
	Command string
	// Reason is a short human-readable explanation of why it would hang.
	Reason string
	// Suggestion is an actionable non-interactive alternative.
	Suggestion string
}

type LinuxSandboxBwrapOptions struct {
	Config     LinuxSandboxHelperConfig
	HelperPath string
}

type LinuxSandboxCommandArgsOptions struct {
	SandboxPolicyCWD     string
	CommandCWD           string
	PermissionProfile    PermissionProfile
	UseLandlock          bool
	ApplySeccompThenExec bool
	BlockUnixSockets     bool
	NoProc               bool
	Command              []string
}

type LinuxSandboxHelperCommand struct {
	Name       string
	ArgsPrefix []string
	Dir        string
}

type LinuxSandboxHelperConfig struct {
	SandboxPolicyCWD     string
	CommandCWD           string
	PermissionProfile    PermissionProfile
	UseLandlock          bool
	ApplySeccompThenExec bool
	BlockUnixSockets     bool
	NoProc               bool
	Command              []string
}

type NetworkMode string

type NetworkPermissions struct {
	Enabled *bool `json:"enabled,omitempty"`
}

type NetworkPolicy struct {
	Mode NetworkMode `json:"mode"`
}

type Permission string

type PermissionGrantScope string

type PermissionMode string

type PermissionProfile struct {
	FileSystem FileSystemPolicy `json:"fileSystem"`
	Network    NetworkPolicy    `json:"network"`
}

type Policy struct {
	Mode             PolicyMode  `json:"mode"`
	Network          NetworkMode `json:"network"`
	EnforceWorkspace bool        `json:"enforceWorkspace"`
	// BlockUnixSockets, when true on the Linux helper backend, installs a
	// best-effort seccomp filter in the inner helper stage that denies AF_UNIX
	// socket creation. It is an extra hardening layer over the native sandbox and
	// is ignored on non-Linux backends.
	BlockUnixSockets bool `json:"blockUnixSockets,omitempty"`
	// MonitorDenials, when true on macOS, tags the sandbox-exec profile's denials
	// and tails `log stream` for them so blocked operations can be surfaced back to
	// the agent. Off by default: it starts a `log stream` subprocess per command and
	// appends a <sandbox_blocks> note to the command's stderr, so it is opt-in.
	// Ignored on non-macOS backends, and a no-op where the OS does not deliver
	// seatbelt denials to the unified log.
	MonitorDenials bool `json:"monitorDenials,omitempty"`
	// AllowRead/DenyRead/AllowWrite/DenyWrite are fine-grained path lists layered
	// ON TOP of the workspace + Scope guards; they never bypass the symlink /
	// out-of-workspace protections. Each entry is home-expanded, made absolute, and
	// symlink-resolved (an entry that does not exist is dropped). All default empty,
	// so an unconfigured policy behaves exactly as before. Semantics:
	//
	//   - Read: a path readable under the base workspace/Scope guard is denied if it
	//     falls under a DenyRead entry, UNLESS a more-specific AllowRead entry (one
	//     nested inside that DenyRead entry) re-includes it. AllowRead only
	//     re-includes within a DenyRead carve-out; it never extends reads beyond the
	//     workspace.
	//   - Write: DenyWrite wins over everything; otherwise a path writable under the
	//     workspace/Scope guard is allowed; otherwise an absolute path under an
	//     AllowWrite root is allowed; otherwise it is denied. AllowWrite roots are
	//     also reflected in the OS backend write binds, and on sandbox-exec DenyWrite
	//     entries are emitted as explicit deny rules so the precedence holds for
	//     shell commands too.
	AllowRead  []string `json:"allowRead,omitempty"`
	DenyRead   []string `json:"denyRead,omitempty"`
	AllowWrite []string `json:"allowWrite,omitempty"`
	DenyWrite  []string `json:"denyWrite,omitempty"`
}

type PolicyMode string

type ReadExclusions struct {
	// contains filtered or unexported fields
}

type Request struct {
	WorkspaceRoot     string         `json:"workspaceRoot,omitempty"`
	ToolName          string         `json:"toolName"`
	SideEffect        SideEffect     `json:"sideEffect"`
	Permission        Permission     `json:"permission"`
	PermissionGranted bool           `json:"permissionGranted,omitempty"`
	PermissionMode    PermissionMode `json:"permissionMode"`
	Args              map[string]any `json:"args,omitempty"`
	Reason            string         `json:"reason,omitempty"`
}

type RequestPermissionProfile struct {
	Network    *NetworkPermissions    `json:"network,omitempty"`
	FileSystem *FileSystemPermissions `json:"file_system,omitempty"`
}

type RequestPermissionsResponse struct {
	Permissions      RequestPermissionProfile `json:"permissions"`
	Scope            PermissionGrantScope     `json:"scope"`
	StrictAutoReview bool                     `json:"strict_auto_review,omitempty"`
}

type Risk struct {
	Level      RiskLevel `json:"level"`
	Categories []string  `json:"categories,omitempty"`
	Reason     string    `json:"reason,omitempty"`
}

type RiskLevel string

type SandboxExecutionRequest struct {
	Command                 CommandSpec         `json:"command"`
	WorkspaceRoot           string              `json:"workspaceRoot"`
	PermissionProfile       PermissionProfile   `json:"permissionProfile"`
	Backend                 Backend             `json:"backend"`
	TargetBackend           BackendName         `json:"targetBackend"`
	CommandWrapped          bool                `json:"commandWrapped"`
	SandboxEnvMarkers       []string            `json:"sandboxEnvMarkers,omitempty"`
	EnforcementLevel        EnforcementLevel    `json:"enforcementLevel"`
	DowngradeReason         string              `json:"downgradeReason,omitempty"`
	SupportLevel            BackendSupportLevel `json:"supportLevel"`
	RequiresPlatformSandbox bool                `json:"requiresPlatformSandbox"`
}

type SandboxManager struct {
	// contains filtered or unexported fields
}

type SandboxManagerOptions struct {
	GOOS             string
	LookupExecutable func(string) (string, error)
	Backend          Backend
}

type SandboxManagerRequest struct {
	WorkspaceRoot     string
	Command           CommandSpec
	Policy            Policy
	Scope             *Scope
	Profile           PermissionProfile
	Preference        SandboxPreference
	ValidateExecution bool
}

type SandboxPreference string

type Scope struct {
	// contains filtered or unexported fields
}

type ScopeKind string

type SideEffect string

type StoreOptions struct {
	FilePath string
	Now      func() time.Time
	Env      map[string]string
}

type WSLInfo struct {
	IsWSL  bool
	IsWSL2 bool
	Kernel string
}

type WindowsACLAction string

type WindowsACLEntry struct {
	Action      WindowsACLAction `json:"action"`
	Path        string           `json:"path"`
	Capability  string           `json:"capability"`
	Materialize bool             `json:"materialize,omitempty"`
}

type WindowsACLPlan struct {
	Entries []WindowsACLEntry `json:"entries"`
}

type WindowsCapabilitySIDs struct {
	SchemaVersion      int               `json:"schemaVersion"`
	ReadOnly           string            `json:"readOnly"`
	WorkspaceByRoot    map[string]string `json:"workspaceByRoot,omitempty"`
	WritableRootByPath map[string]string `json:"writableRootByPath,omitempty"`
	// Offline is a synthetic SID that carries NO filesystem ACL. The persistent
	// WFP outbound-block filter is scoped to it, so a command's network is gated
	// purely by whether its restricted token carries this SID: offline (deny)
	// commands include it and are blocked; online (approved) commands omit it and
	// reach the network — both still write-jailed by the capability SIDs.
	Offline string `json:"offline,omitempty"`
}

type WindowsNetworkPlan struct {
	Mode         NetworkMode            `json:"mode"`
	ProviderKey  string                 `json:"providerKey,omitempty"`
	SubLayerKey  string                 `json:"subLayerKey,omitempty"`
	IdentitySIDs []string               `json:"identitySids,omitempty"`
	Filters      []WindowsWFPFilterSpec `json:"filters,omitempty"`
}

type WindowsSandboxCommandArgsOptions struct {
	SandboxHome       string
	CommandCWD        string
	WorkspaceRoots    []string
	PermissionProfile PermissionProfile
	Env               []string
	SandboxLevel      WindowsSandboxLevel
	Command           []string
}

type WindowsSandboxCommandConfig struct {
	SandboxHome       string
	CommandCWD        string
	WorkspaceRoots    []string
	PermissionProfile PermissionProfile
	Env               map[string]string
	SandboxLevel      WindowsSandboxLevel
	Command           []string
}

type WindowsSandboxHelper struct {
	Name       string
	ArgsPrefix []string
}

type WindowsSandboxLevel string

type WindowsSandboxSetupArgsOptions struct {
	SandboxHome       string
	CommandCWD        string
	WorkspaceRoots    []string
	PermissionProfile PermissionProfile
}

type WindowsSandboxSetupConfig struct {
	SandboxHome       string
	CommandCWD        string
	WorkspaceRoots    []string
	PermissionProfile PermissionProfile
}

type WindowsSandboxSetupMarker struct {
	SchemaVersion  int    `json:"schemaVersion"`
	ACLPlanHash    string `json:"aclPlanHash"`
	ACLPlanEntries int    `json:"aclPlanEntries"`
	// NetworkInfraHash fingerprints the mode-INDEPENDENT network infrastructure
	// setup provisioned (block filters scoped to the offline-marker SID), so one
	// marker validly serves both an allow command and a deny command. It replaces
	// the old per-command NetworkPolicyHash/NetworkPlanHash, which locked the
	// marker to a single mode and bricked approved network commands.
	NetworkInfraHash string `json:"networkInfraHash"`
	OfflineFilterSID string `json:"offlineFilterSid"`
	NetworkFilters   int    `json:"networkFilters"`
}

type WindowsUnelevatedAppliedPlan struct {
	ACLPlanHash    string `json:"aclPlanHash"`
	ACLPlanEntries int    `json:"aclPlanEntries"`
}

type WindowsUnelevatedSetupMarker struct {
	SchemaVersion int                            `json:"schemaVersion"`
	AppliedPlans  []WindowsUnelevatedAppliedPlan `json:"appliedPlans,omitempty"`
}

type WindowsWFPConditionSpec struct {
	Kind  string `json:"kind"`
	Value uint16 `json:"value,omitempty"`
}

type WindowsWFPFilterSpec struct {
	Key         string                    `json:"key"`
	Name        string                    `json:"name"`
	Description string                    `json:"description,omitempty"`
	Layer       string                    `json:"layer"`
	Action      string                    `json:"action"`
	Conditions  []WindowsWFPConditionSpec `json:"conditions,omitempty"`
}

type WritableRoot struct {
	Root                   string   `json:"root"`
	ReadOnlySubpaths       []string `json:"readOnlySubpaths,omitempty"`
	ProtectedMetadataNames []string `json:"protectedMetadataNames,omitempty"`
}