Sandbox: workspace scope allows toolchain temp/cache dirs (GOCACHE, TMPDIR)

[dennisonbertram]

Closes #1399

Summary

Under permissions.sandbox: "workspace", bash writes are now also permitted to a small, fixed set of per-user temp and cache directories a language toolchain needs — os.TempDir(), os.UserCacheDir(), ~/.cache, the Go build/module caches ($GOCACHE, $GOMODCACHE/$GOPATH/pkg/~/go/pkg), ~/.npm, ~/.cargo/registry, ~/.cargo/git — in addition to the workspace root itself. Externally, this means go build ./..., go test ./..., and mktemp -d now succeed under workspace scope with no env var overrides, instead of failing with "operation not permitted" and forcing the model to relocate caches into the project tree (the symptom reported in #1399). The bash tool result and the model's permissions notice both now say so explicitly.

Scope and issue reconciliation

Implemented exactly the 2026-09-06 coordinator design-decision comment on #1399:

1. toolchainWritableDirs() (internal/harness/tools/toolchain_dirs.go) — canonicalized (EvalSymlinks), computed fresh per call, only existing dirs except the Go module cache and ~/.cache (created if missing), no blanket $HOME. ✅
2. darwin seatbeltProfile emits (allow file-write* (subpath ...)) per dir for workspace scope only; Linux buildSandboxedCommand --binds each dir read-write after the read-only root bind and before the workspace bind; /tmp is no longer explicitly --ro-binded (it's frequently exactly os.TempDir(), and a ro-bind of the same path would shadow the later rw bind). ✅
3. checkWorkspaceScopeCommand accepts an absolute token under the workspace or any writable dir; still rejects /etc/passwd, /usr/local/bin/x, ~/.ssh/... (the last required adding ~/-token expansion, since the heuristic previously silently skipped tilde-prefixed tokens entirely — filepath.IsAbs doesn't recognize ~ as absolute). ✅
4. SandboxExecResult.WritableDirs → bash tool result sandbox_writable_dirs; permissions notice gains "For this run, temp and per-user cache directories are writable." for sandbox=workspace only. ✅
5. Tests red-first (see Test-first evidence), including a real-toolchain integration test with no env overrides and a mktemp -d test — both run for real on this macOS host. ✅
6. Docs: website/docs/concepts/tools-and-permissions.md, website/docs/reference/glossary.md; engineering-log entry in docs/logs/engineering-log.md. ✅

Out of scope per the design decision, and not touched: local/unrestricted scopes (already unconfined for writes), network policy (#1397, done), a harness-owned cache directory (explicitly rejected by the coordinator — would hide the user's existing caches and need per-toolchain env plumbing).

Two pre-existing tests needed adjustment because the change legitimately widens what "outside the workspace" means: TestSandboxWorkspaceScopeBlocksWriteOutsideWorkspaceAtOSLevel and TestSandboxWorkspaceScopeEnforcesFilePaths both used to prove an escape by writing under os.TempDir() or a sibling of the workspace's t.TempDir() parent — both are now legitimately writable by design, so both were repointed at /var/tmp (never a toolchain writable dir) to keep proving a real boundary exists. TestCheckSandboxCommandWorkspaceScope's "ls /tmp" case was replaced with "ls /usr/local/bin/x" since it would flip from rejected to accepted on any host where TMPDIR is unset (os.TempDir() then equals literal /tmp), making the old assertion host-dependent rather than a real regression check.

Impact analysis reconciliation

• internal/harness/tools/sandbox.go — checkWorkspaceScopeCommand (heuristic layer), SandboxExecResult (new WritableDirs field). Only caller of CheckSandboxCommand is bash_manager.go; no other package calls it.
• internal/harness/tools/sandbox_darwin.go, sandbox_linux.go — buildSandboxedCommand/seatbeltProfile. Only callers are bash_manager.go (runForeground/runBackground) and this package's own tests. sandbox_other.go (non-darwin/non-linux) is unaffected — it never had OS-level confinement and this change doesn't touch it.
• internal/harness/tools/bash_manager.go — adds result["sandbox_writable_dirs"] alongside the existing sandbox_mechanism/sandbox_warning/sandbox_network keys populated the same way (only when non-empty); does not change any existing key's shape.
• internal/harness/runner.go — permissionsNoticeLines, used for both the first-turn notice (always present) and the continuation notice (present only when permissions changed); both call sites are unchanged, only the returned lines gain a conditional entry.
• No config, schema, persistence, or public-route changes. internal/harness/tools/core/deferred (the actual tool catalog) are unaffected — this is infrastructure bash_manager.go already consumed before this change.

Architecture and duplication check

• Reused, rather than duplicated: canonicalizePathAllowingMissing and pathWithinRoot (internal/harness/tools/common_paths.go, already used by ConfineWorkspacePath for the write/glob tool family) instead of re-deriving symlink-safe path containment in sandbox.go.
• toolchainWritableDirs() is a single new function in internal/harness/tools (the existing home for sandbox/policy infrastructure per this repo's tool-catalog convention) called from three places (seatbeltProfile, sandbox_linux.go's buildSandboxedCommand, checkWorkspaceScopeCommand) rather than three separate directory-discovery implementations.
• No new abstraction layer, interface, or config surface was introduced for a single implementation — directly extends the existing SandboxExecResult/seatbeltProfile/buildSandboxedCommand shapes PR Make bash sandbox network policy configurable (issue #1397) #1398 already established for the network-policy axis.

Test-first evidence

Red command: go test ./internal/harness/tools/ -run TestToolchainWritableDirs -v (plus the new sandbox/darwin/runner tests), before any implementation.

Observed failure (representative excerpt; full output is in the red commit message, edea8780):

--- FAIL: TestSeatbeltProfileIncludesToolchainWritableDirs
    sandbox_darwin_test.go:95: test precondition failed: toolchainWritableDirs() returned no directories on this host
--- FAIL: TestSandboxWorkspaceScopeToolchainCanBuildAndTest
    sandbox_test.go:588: expected go build/test to succeed under workspace sandbox with no env overrides, got exit_code=1 output="/Users/dennison/Library/Caches/go-build\ngo: creating work dir: mkdir /var/folders/.../go-build2654872007: operation not permitted"
--- FAIL: TestSandboxWorkspaceScopeAllowsMktempDir
    sandbox_test.go:615: expected "mktemp -d" to succeed under workspace sandbox, got exit_code=1 output="mktemp: mkdtemp failed on /var/folders/.../tmp.cM682JLsU3: Operation not permitted"
--- FAIL: TestRunnerFirstTurnPermissionsNoticeIncludesWritableCacheDirsForWorkspace
    runner_writable_dirs_notice_test.go:35: expected first-turn messages to mention writable temp/cache dirs for workspace scope, got [... "Permissions for this run: sandbox=workspace, approval=none, network=allow."]
FAIL

Why the failure proved the missing/incorrect behavior: toolchainWritableDirs() was a stub returning nil, so every profile/heuristic/result-map assertion failed on absence, not a compile error; the two integration tests reproduced the exact "operation not permitted" symptom from the issue's live-build report, proving the pre-fix code actually fails the way #1399 describes.

Green command: go test ./internal/harness/tools/... ./internal/harness/... -count=1 -v

ok  	go-agent-harness/internal/harness	4.137s
ok  	go-agent-harness/internal/harness/tools	17.324s
ok  	go-agent-harness/internal/harness/tools/core	1.582s
ok  	go-agent-harness/internal/harness/tools/deferred	9.909s
ok  	go-agent-harness/internal/harness/tools/descriptions	1.083s
ok  	go-agent-harness/internal/harness/tools/recipe	0.987s
ok  	go-agent-harness/internal/harness/tools/script	2.608s

All 10 TestToolchainWritableDirs* subtests, TestSeatbeltProfileIncludesToolchainWritableDirs, TestBuildSandboxedCommandDarwinReportsWritableDirs, TestCheckWorkspaceScopeCommandToolchainWritableDirs, TestSandboxWorkspaceScopeToolchainCanBuildAndTest, TestSandboxWorkspaceScopeAllowsMktempDir, TestJobManagerRunForegroundReportsSandboxWritableDirsInResult, and TestRunnerFirstTurnPermissionsNoticeIncludesWritableCacheDirsForWorkspace pass.

Refactor/characterization evidence: N/A — no behavior-preserving refactor step in this change; red → green → regression only.

Verification evidence

Targeted (this feature): go test ./internal/harness/tools/... ./internal/harness/... -count=1 -v → all green (see above).

Full regression, this package tree: go test ./internal/harness/... -race -count=1

ok  	go-agent-harness/internal/harness	7.214s
ok  	go-agent-harness/internal/harness/tools	19.086s
ok  	go-agent-harness/internal/harness/tools/core	2.225s
ok  	go-agent-harness/internal/harness/tools/deferred	11.093s
ok  	go-agent-harness/internal/harness/tools/descriptions	1.589s
ok  	go-agent-harness/internal/harness/tools/recipe	1.969s
ok  	go-agent-harness/internal/harness/tools/script	3.849s

Static checks: go vet ./internal/harness/... clean; GOOS=linux go vet ./internal/harness/tools/... clean (the Linux bwrap bind test, TestBuildSandboxedCommandLinuxIncludesToolchainWritableDirs, is build-tagged linux and cannot execute a real bwrap process on this darwin worktree — vet only confirms it type-checks; it needs a Linux CI run to prove behavior, which is a known limitation of this PR).

Full repo regression: go build ./internal/... ./cmd/... clean; go test ./internal/... -count=1 — every package passes except internal/acceptance/ptyrunner (4 PTY tests fail with "PTY did not create completed run for prompt"). Verified this failure is pre-existing and unrelated: reproduced the identical failure on a clean origin/main checkout (commit 986cf722, this branch's base) via a throwaway git worktree add ... origin/main, before any of this PR's changes existed. Not caused by, and not fixed by, this PR.

Real user-path/integration proof (the two tests the issue's "Regression test first" and "Definition of done" sections specifically call for): TestSandboxWorkspaceScopeToolchainCanBuildAndTest creates a throwaway Go module inside the workspace and runs go env GOCACHE && go build ./... && go test ./... through the real darwin seatbelt sandbox with no env var overrides — passes. TestSandboxWorkspaceScopeAllowsMktempDir runs real mktemp -d the same way — passes. TestSandboxWorkspaceScopeGOCACHEOverrideIsWritableEndToEnd (regression commit) additionally proves a custom $GOCACHE override is writable end to end, not just the unconfigured default.

Rollout and rollback

Profile/heuristic/notice-text change only; no migration, no persisted schema, no config flag. Rollback is a plain revert of this PR (or git revert) — reopens #1399 to its prior state (workspace-scope toolchain writes fail until the model relocates caches into the project). No data repair needed: nothing durable is created or migrated by this change (the two directories it creates, ~/.cache and the Go module cache, are conventional toolchain-owned locations that pre-exist on most machines and are safe to leave in place either way).

Documentation

• website/docs/concepts/tools-and-permissions.md — the "workspace" sandbox-scope tab now describes the extra writable dirs and why (with a Source: line update).
• website/docs/reference/glossary.md — the sandbox scope glossary card's "workspace" bullet updated.
• docs/logs/engineering-log.md — full before/after/gotcha entry (2026-09-06, Issue bug(sandbox): workspace scope blocks toolchain temp and cache dirs (GOCACHE, TMPDIR); models waste steps relocating caches into the project #1399), including the /tmp ro-bind → rw-bind rationale and the two pre-existing tests that needed repointing.
• No API/CLI reference, runbook, or release-notes changes needed: no new route, flag, or environment variable was added (all inputs are the pre-existing TMPDIR/GOCACHE/GOMODCACHE/GOPATH env vars, read the same way the Go toolchain itself already reads them).

Contract checklist

• Linked issue follows the current structured contract and this PR closes it
• Issue acceptance criteria, impact map, and scope were updated when the design changed (the 2026-09-06 coordinator comment is the current acceptance contract; implemented exactly it)
• All callers, consumers, sources of truth, and similar abstractions were searched
• No unrelated cleanup, hidden scope growth, duplicated wiring, or parallel abstraction was introduced
• Tests were written first and the expected red failure was observed, or this is a strictly docs-only minor PR
• Targeted checks and the repository-required full regression are green
• Security, compatibility, lifecycle, deployment, observability, documentation, and rollback were reconciled
• Real mouse/keyboard/API/operator behavior was exercised when the change is interaction- or integration-heavy — N/A, this is a backend sandbox/tool-output change with no UI surface; the real-toolchain integration tests above are the closest equivalent and were run for real

🤖 Generated with Claude Code

https://claude.ai/code/session_01WJGxhoFhA8JjkwZFcLGdS5

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[dennisonbertram]

Live verification (coordinator): harnessd+harnesscli built from this branch, default permissions (workspace sandbox, network allow), real HOME, deepseek/deepseek-v4-flash via OpenRouter, prompt: create a Go module using modernc.org/sqlite with tests, no cache env overrides. Result: completed in 173 s, 12 steps, $0.010, 0 sandbox violations, 0 'operation not permitted' / build-cache errors, 0 GOCACHE/GOTMPDIR/GOPATH overrides in commands, no .go*/.gopath dirs in the workspace; sandbox_writable_dirs reported the temp dir, ~/Library/Caches, ~/.cache, ~/go/pkg, ~/.npm. Independent go vet + go test on the produced module: PASS.