run_shell: the
shell section of settings.yaml (was shell_policy.yaml) master flag (off by
default, so the tool is never registered until you opt in), host mode versus
Docker sandbox mode and its launcher template, the cross-platform bash
interpreter that tokenizes pipes and heredocs identically on Windows and POSIX,
optional persistent per-thread bash sessions that keep cd and environment
changes across calls, the non-removable denylist and optional confine cwd
containment, the timeout with process-tree kill, environment scrubbing via
env_passthrough, and the audit log written to data/audit/shell-audit.jsonl.
For the filesystem tools: the read-only fs namespace (read_file, grep,
glob_files) and the separately namespaced fs_write (write_file,
edit_file), path confinement to the project root, the tmp:// scratchpad,
gitignore honouring, and the fs section’s deny_paths list that hard-refuses
secrets, policy files, and git internals for both reads and writes.
The shipped fs deny_paths are a non-removable security floor: an agent’s
own deny_paths, and the layer-root security.fs_deny_paths list, only ever
add to the shipped secret denials, so a project can tighten what is refused
but never open a hole in it.
Two garbage-collection knobs that used to live on the agent are now host
resources in a layer-root settings.yaml, because they bound the machine rather
than a persona: scratchpad GC and quota (resources.scratch, with ttl_days,
clear_on_resume, max_scratch_bytes) and durable background-shell GC
(resources.background_shells, with ttl_hours, persist_default). Where a
knob is unset there it falls back to the agent’s fs / shell section.
This page is in progress. The shipped
shell and fs sections are fully
commented and are the best reference until it lands. Legacy split
shell_policy.yaml and fs_policy.yaml files still resolve at each layer.run_shell, Configuration for a real fs section
including deny_paths, and Tools for how deferred tools are
discovered and activated.