# Tool Execution Request Schema (Normative)

A **Tool Execution Request** is a human-approved artifact placed into TOOL-EXEC.
CORE may draft it, but the operator must approve and promote it.

Requests must be deterministic, auditable, and minimally privileged.

---

## File Naming

Recommended:
- `TR-YYYYMMDD-HHMMSSZ-<slug>.md`

---

## Required Front Matter

```yaml
---
request_type: tool_request
schema_version: 1
request_id: "TR-20260209-160501Z-python-stats"
created_utc: "2026-02-09T16:05:01Z"
requested_by: "human|core_draft"
approved_by: "human_name_or_id"
approved_utc: "2026-02-09T16:12:00Z"
purpose: "One sentence describing why execution is needed."
language: "python|node|ts|go|ruby|shell_forbidden"
network: "none|allowlist"         # default none
network_allowlist: []             # only if network=allowlist
cpu_limit: "2"                    # cores
memory_limit_mb: 1024
time_limit_sec: 120
inputs:
  - name: "input.csv"
    sha256: "hex..."
outputs_expected:
  - path: "output.json"
    description: "..."
constraints:
  - "No network unless allowlisted"
  - "No writes outside /out"
  - "No persistence"
---
````

---

## Required Sections (in this order)

1. `## Command`
2. `## Input Files`
3. `## Output Expectations`
4. `## Risk Assessment`

### 1) Command

Must be a single command line in plain text (no code fences), e.g.:

`python -u script.py --in /in/input.csv --out /out/output.json`

Notes:

* TOOL-EXEC implementation may wrap this into ERA invocation.
* Requests containing multiple commands, shell chaining (`;`, `&&`, `|`), or heredocs MUST be rejected.

### 2) Input Files

List each input file and expected location (`/in/...`), matching `inputs` hashes.

### 3) Output Expectations

List each output path restricted to `/out/...`.

### 4) Risk Assessment

Must include:

* `Risk level: low|medium|high`
* `Justification:` short text
* `Data sensitivity:` public|internal|confidential
* `Network rationale:` why network is needed (if any)

---

## Forbidden Content (Validation Failures)

Requests MUST be rejected if they include:

* shell as language
* command chaining, pipelines, redirection
* instructions to install packages
* attempts to access host paths
* attempts to use privileged devices
* embedded secrets

---

## Approval Gate

A request is only valid if:

* `approved_by` and `approved_utc` are present and non-empty
* `requested_by` is present
* hashes are present for all declared inputs