docs: fix documentation drift — tools field marked reserved but fully functional

[Copilot]

AGENTS.md documented the tools front matter field as RESERVED: not yet implemented, but src/compile/common.rs actively reads and applies both sub-fields (tools.bash, tools.edit) during compilation.

Changes

• Front matter example: Uncomments the tools: block and removes the stale "RESERVED" annotation
• New "Tools Configuration" section: Adds a dedicated docs section (consistent with schedule, pool, engine) covering:
  • Default safe bash allow-list: cat date echo grep head ls pwd sort tail uniq wc yq
  • Unrestricted access via bash: [":*"]
  • Explicit command restriction and disabling bash entirely with bash: []
  • Disabling file writes with edit: false
• env field: Confirmed still unimplemented (FrontMatter.env is defined but never consumed during compilation) — kept as RESERVED

# Now documented as a functional optional field:
tools:
  bash: ["cat", "ls", "grep"]  # restrict to specific commands
  edit: false                   # disable file writes

# Or grant unrestricted shell access:
tools:
  bash: [":*"]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>📝 Documentation drift detected — tools field documented as not implemented but is fully functional</issue_title>
<issue_description>## Documentation Freshness Audit

The weekly documentation audit found the following inconsistency between code and documentation:

Findings

Area	Issue	File(s)
Front Matter Fields	tools field is marked as RESERVED: not yet implemented but is actively used in compilation	AGENTS.md line 123–125, src/compile/common.rs lines 277–306

Details

tools front matter field — documented as reserved, but fully implemented

AGENTS.md shows the tools field commented out with the annotation "RESERVED: tool configuration (not yet implemented)":

# tools:                       # RESERVED: tool configuration (not yet implemented)
#   bash: ["cat", "ls", "grep"]  # bash command allow-list
#   edit: true                   # enable file editing tool

However, src/compile/common.rs (lines 277–306) actively reads and applies both sub-fields:

• tools.edit — controls whether the file-writing (write) tool is exposed to the agent (defaults to true)
• tools.bash — controls which shell commands agents may invoke:
  • Omitted: defaults to a safe built-in list (cat, date, echo, grep, head, ls, pwd, sort, tail, uniq, wc, yq)
  • [":*"]: grants unrestricted bash access (shell(:*))
  • ["cmd1", "cmd2"]: restricts to exactly the listed commands

The ToolsConfig struct in src/compile/types.rs is fully defined with bash: Option(Vec<String)> and edit: Option(bool).

Suggested Fixes

• Remove the # RESERVED: not yet implemented comment from the tools field example in AGENTS.md
• Uncomment the tools example YAML block so it reads as a valid (optional) front matter field
• Add a proper documentation section for tools (similar to how schedule, pool, and engine have their own subsections) explaining:
  • Default bash command allow-list
  • How to use [":*"] for unrestricted access
  • How to restrict to specific commands
  • The edit: false option to disable file writes
• Verify whether the env field (also marked RESERVED) is similarly implemented or genuinely unused, and update accordingly

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷

Comments on the Issue (you are @copilot in this section)

• Fixes 📝 Documentation drift detected — tools field documented as not implemented but is fully functional #55

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.