# 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`

---

## Front Matter (Required)

| Key | Type | Notes |
|----|-----|------|
| request_type | string | must be `tool_request` |
| schema_version | string | `1` |
| request_id | string | unique |
| created_utc | ISO-8601 | |
| requested_by | string | |
| approved_by | string | human |
| approved_utc | ISO-8601 | |
| purpose | string | |
| backend | enum | `ERA` or `monty` |
| language | string | |
| network | enum | `none`, `allowlist` |
| cpu_limit | string | |
| memory_limit_mb | int | |
| time_limit_sec | int | |

---

## Body Sections (By Backend)

### ERA
- `## Command`
- `## Input Files`
- `## Output Expectations`
- `## Risk Assessment`

### Monty
- `## Code`
- `## Inputs (JSON)` (optional)
- `## Output Expectations`
- `## Risk Assessment`

---

## Compatibility Rules

- Missing `backend` defaults to ERA
- Schema changes require version bump

### 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