sandbox

type Availability struct {
	// CanEnforce is false when the backend cannot enforce at all (binary
	// missing, wrong OS, kernel too old, version below the pin). The daemon
	// must fail closed in that case.
	CanEnforce bool
	// Degraded is true when enforcement works but some controls are missing
	// (e.g. Landlock present but no network-filtering ABI). Filesystem
	// confinement still holds; the daemon runs but should surface the state.
	Degraded bool
	// Detail is a human-readable explanation for logs / doctor / errors.
	Detail string
}

type Backend interface {
	// Name is the config value that selects this backend.
	Name() string
	// Availability reports whether this backend can enforce on this host now,
	// given the controls the policy requires. command overrides the backend
	// binary; empty uses the backend default.
	Availability(command string, req Requirements) Availability
	// Wrap returns the command and args to exec so the child runs sandboxed.
	Wrap(command string, args []string, opts WrapOpts) (string, []string, error)
}

type NetworkPolicy struct {
	// Block denies all outbound network (nono network.block = true).
	Block bool
	// AllowDomains is the L7 proxy allowlist (nono network.allow_domain).
	AllowDomains []string
}

type Requirements struct {
	// Network is true when a network policy is requested. On Linux this
	// requires Landlock ABI v4; a host that only supports filesystem
	// enforcement must fail closed rather than pretend to block egress.
	Network bool
}

type WhyQuery struct {
	// Path + Op form a filesystem query.
	Path string
	Op   string // "read", "write", or "readwrite"

	// Host + Port form a network query.
	Host string
	Port int
}

type WhyResult struct {
	Status       string `json:"status"`
	Reason       string `json:"reason,omitempty"`
	Details      string `json:"details,omitempty"`
	Access       string `json:"access,omitempty"`
	GrantedPath  string `json:"granted_path,omitempty"`
	Source       string `json:"source,omitempty"`
	PolicySource string `json:"policy_source,omitempty"`
	SuggestFlag  string `json:"suggested_flag,omitempty"`
}

type WrapOpts struct {
	// Backend selects the sandbox backend. Empty is invalid at the daemon
	// layer (backend must be chosen explicitly); Wrap defaults it to safehouse
	// for backward compatibility of the low-level helper.
	Backend string

	WorktreeDir string
	ReadDirs    []string
	WriteDirs   []string
	// ReadFiles / WriteFiles grant single files rather than whole directories,
	// for paths that can't be a directory grant without over-sharing (notably
	// single files directly in $HOME, e.g. an agent's ~/.claude.json). Paths are
	// already ~/glob-expanded and absolute. ReadFiles is read-only (nono
	// filesystem.read_file); WriteFiles is read+write (nono filesystem.allow_file,
	// like WriteDirs → allow, not the write-only filesystem.write). The safehouse
	// backend folds them into its read-only / read-write dir lists.
	ReadFiles  []string
	WriteFiles []string
	Features   []string
	EnvKeys    []string

	// SignalMode maps to nono's security.signal_mode ("isolated",
	// "allow_same_sandbox", "allow_all"). Empty inherits nono's default. The
	// safehouse backend ignores it.
	SignalMode string

	// Network is the optional egress policy. Nil means no network restriction
	// (nono is allow-by-default). When set, the nono backend emits a
	// network.block / network.allow_domain section; the safehouse backend has
	// no network primitive and warns that it cannot enforce it.
	Network *NetworkPolicy

	// BackendCommand overrides the backend binary name/path. Empty means the
	// backend's own default ("safehouse" / "nono"). Formerly SafehouseCommand.
	BackendCommand string

	// ProfilePath, for the nono backend, is where the generated per-session
	// profile is written. The daemon points it under RuntimeDir so it is
	// readable inside the sandbox and survives for the process lifetime and
	// resume. Empty means the backend writes to an os.CreateTemp file.
	ProfilePath string
}