107 lines
2.4 KiB
Markdown
107 lines
2.4 KiB
Markdown
# 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
|