docs: add ADR-014 for built-in tools and workspace sandboxing

[lorenzh]

Defines the six built-in agent tools (read, write, edit, grep, glob, bash),
workspace sandboxing model, and the separation between workspace and plugin
scoped directories.

https://claude.ai/code/session_017256wCsH6FHNJntAb8Pebr

[claude]

Code review: 4 issues found in ADR-007. Issue 1 (lines 223-225): The statement 'Built-in tools cannot access inbox/outbox/logs' is incorrect - bash is one of the six built-in tools and escapes the sandbox. Issue 2 (line 326): 'Neither can see the other' is unqualified but workspace_access:true opt-in exists. Issue 3 (lines 183-189): Symlink sandbox escape not addressed in path validation spec. Issue 4 (line 248): Plugin scoping presented as security guarantee but is trust-based convention only.

[claude]

Code review

4 issues found in ADR-007.

Issue 1 - Misleading blanket statement (lines 223-225)
The statement 'Built-in tools cannot access inbox/, outbox/, logs/' is factually incorrect: bash is one of the six built-in tools and explicitly escapes the sandbox. Fix: qualify to 'The five deterministic built-in tools (read, write, edit, grep, glob) cannot access...' and add a pointer to the Bash sandboxing section.

Issue 2 - Absolute claim contradicts opt-in mechanism (line 326)
The Consequences section states 'Neither can see the other' as an unqualified absolute. But workspace_access: true is an opt-in mechanism that grants plugins access to the workspace - directly contradicting this. Fix: 'Neither can see the other by default.'

Issue 3 - Symlink sandbox escape not addressed (lines 183-189)
Path validation rejects ../ traversal and absolute paths but says nothing about symlinks. An agent with bash enabled can run ln -s /etc/passwd link.txt, then call read(link.txt) - the path resolves within the workspace while the actual access escapes. The spec claims to prevent intentional escape and must define a symlink policy (e.g. resolve symlinks before the workspace-prefix check, or reject them outright).

Issue 4 - Plugin scoping is a convention, not enforced (line 248)
'By default, the plugin cannot see workspace/' is stated as a security property, but plugins are simply told their scope_dir via JSON. They run as ordinary Unix subprocesses with full user filesystem privileges - no chroot or namespace enforces the boundary. The document is honest about bash escaping the sandbox; plugin scoping deserves the same framing - it is a convention, not an enforced boundary.

[claude]

Code review comment - see two issues in the following link

[claude]

Code review

Two issues found.

Issue 1: Directory tree missing memory and crashes directories - see lines 210-228 of ADR-007-built-in-tools-and-workspace.md. The CLAUDE.md file documents these as canonical subdirectories but the diagram omits them.

Issue 2: Undefined plugin-to-internals access grant mechanism - see lines 222-232 of ADR-007-built-in-tools-and-workspace.md. The document mentions plugins can have explicit access grants to agent internals, but only workspace_access mechanism is defined.

[Hilo-re]

Research: External validation of the filesystem-as-runtime approach

While reviewing recent writing on agent architecture, came across a relevant post: How to build agents with filesystems and bash (Vercel, 2026-04-01).

Key findings relevant to ADR-007

Filesystem sandboxing is the critical safety primitive. The article identifies sandboxed execution as a first-class concern — isolating agent file access from production systems is what makes filesystem-native agents safe to run. ADR-007's workspace sandboxing model directly addresses this.

The /workspace separation pattern is convergent. Vercel's recommended layout mirrors the workspace vs plugin-scoped directory split in this ADR: agents get a bounded working directory, and access outside that boundary is explicitly controlled. Worth ensuring ADR-007 specifies what happens when an agent tries to escape its workspace (error vs quarantine vs audit log).

Grep/glob as first-class tools. The article argues that LLMs naturally excel at filesystem navigation because they've been trained on code. This supports the six built-in tools (read, write, edit, grep, glob, bash) being the right primitive set — not too many, not too few.

One open question this surfaces: the article mentions that sandboxed bash execution is important but doesn't specify how to enforce it. ADR-007 should be explicit about the enforcement mechanism — is it chroot, a Linux namespace, or a path-prefix allow-list? This is likely worth a sentence in the Decision section.

[Hilo-re]

There's a numbering conflict here — ADR-007 is already taken by docs/adrs/ADR-007-garbage-collection.md (accepted 2026-04-03). The next available number is ADR-014. This file should be renamed to docs/adrs/ADR-014-built-in-tools-and-workspace.md before merging.

[Hilo-re]

There's a numbering conflict here — ADR-007 is already taken by docs/adrs/ADR-007-garbage-collection.md (accepted 2026-04-03). The next available number is ADR-014. This file should be renamed to docs/adrs/ADR-014-built-in-tools-and-workspace.md before merging.