Proposal: Structured Tool Permissions

[darth-kcaj]

Summary The current agents.md spec relies on natural language to define boundaries (e.g., "Do not delete files"), which is non-deterministic and hard for tooling to enforce. I propose adding a structured configuration section (likely in YAML frontmatter) to explicitly define tool permissions.

Proposed Implementation Introduce a permissions block in the YAML frontmatter of AGENTS.md files. This allows agent runners to programmatically enforce safeguards before the LLM even attempts an action.

Example AGENTS.md

---
version: 1.0
permissions:
  files:
    read: allow
    edit: ask  # Requires user confirmation
    delete: deny
  shell:
    # Allow specific safe commands, deny others
    allow: ["ls", "npm test"]
    default: deny
  browser:
    allow: ["https://docs.python.org/*"]
---

# Agent Instructions
(Normal natural language context goes here...)

Open for discussion - thoughts?

[qchantel]

Agree. Also we could add a required "description" field, it would allow models to parse the top part of the file instead of reading the whole thing each time. In the case of multiple agents.md it would save a lot of context window.