sheena: Instructions file for Codex

AGENTS.md

Guidance for AI agents and human contributors working in this repository. These rules are mandatory for every change. (A Claude-specific superset lives in CLAUDE.md; this file is the tool-neutral version.)

What Sheena is

A lightweight, in-process sandbox for safely executing the tool calls an AI agent requests, on the same host as the agent. See README.md for the API and DESIGN.md for the full design.

Go version & idioms

• Target Go 1.25.0. Any feature up to and including Go 1.25 may be used (generics, os.Root, io/fs.ReadLinkFS, range-over-func, etc.).
• Prefer modern idioms. Use any, never interface{}. Use generics where they remove duplication or improve type safety.
• Keep go.mod's go 1.25.0 directive and the golangci-lint config in sync.

Testing & coverage

• Every package MUST maintain ≥90% statement coverage. Add tests until the bar is met; never lower it.
• make test (go test -race ./..., with the wasm interpreters run separately without -race) and make cover (per-package ≥90% gate) MUST pass.
• Access-control behavior is documented and asserted with example tests (Example… + // Output:) — path traversal blocked, network denied by default, overlay never writes to the host.
• Keep the dedicated suites: security/threat-model (security_test.go), escape attempts (traversal, symlink escape, SSRF, redirect, output/command/memory caps, timeout), and the differential golden tests that check commands against real coreutils (internal/difftest).

Benchmarks

Sheena claims to be lightweight; that claim stays measured. Keep Benchmark… for sandbox construction/mass startup (report allocs/op and B/op), per-call ExecBash overhead, and parallel throughput (b.RunParallel). Run with make bench; compare with benchstat when touching hot paths and do not regress startup or allocations without a stated reason.

Linting

golangci-lint MUST pass with zero issues (make lint). Fix the underlying issue rather than disabling a linter or adding a nolint directive; if a suppression is truly warranted, justify it in the diff.