P121 — AIEP — Piea Computer Use and Execution Surface Standard
Publication Date: 2026-03-08 Status: Open Source Prior Art Disclosure Licence: Apache License 2.0 Author / Organisation: Phatfella Ltd Schema: AIEP_OS_SPEC_TEMPLATE v1.0.1 — https://aiep.dev/schemas/aiep-os-spec-template/v1.0.1 Related Filings: GB2519711.2 (Core Protocol) · GB2519826.8 (Hardware Layer) Related Specs: P14 P26 P63 P75 P118 P119 P120
Framework Context
[0001] This disclosure operates within an Architected Instruction and Evidence Protocol (AIEP) environment as defined in United Kingdom patent application number GB2519711.2, filed 20 November 2025, the entire contents of which are incorporated herein by reference.
[0002] This disclosure extends the Piea agent identity standard (P118), the governed file output standard (P120), and the environmental feedback actuation receipt standard (P75) to define the governed execution surface — the pathway by which Piea runs code, executes shell commands, manages a file system, and interacts with a sandboxed computing environment as a governed series of actuation events with cryptographic receipts.
Background
[0003] An AI agent that can only read web pages and produce text answers is not useful for tasks that require computation: running tests, building files, parsing large datasets, executing system operations, or interacting with APIs through scripted workflows. The difference between an agent that reads and reasons versus one that reads, reasons, and acts is the execution surface.
[0004] The execution surface is also the highest-risk surface in a governed AI agent. An agent that can execute arbitrary code can produce side effects in the user’s environment that are difficult to reverse, impossible to verify after the fact if not recorded, and dangerous if misaligned with user intent. A governed execution surface must be as auditable as the evidence ingestion surface — every command recorded, every output hashed, every side effect declared.
[0005] Existing AI systems with computer use capabilities (code execution, shell access, file system operations) do not:
(a) commit an ExecutionRecord to an append-only ledger for every command executed; (b) compute a ContentHash of every command output before it enters the agent’s reasoning substrate; (c) issue a P75 ActuationReceiptRecord for every execution act, binding the command, its parameters, and its outcome; (d) distinguish between read-only execution (observe without side effect) and write execution (produce side effect) at the governance layer; (e) apply the R5 fail-closed gate to execution requests — requiring explicit admissibility assessment before execution proceeds; or (f) commit a NegativeProofRecord when an execution is suppressed, proving that the suppression occurred.
[0006] There exists a need for an execution surface standard that brings the same evidentiary governance to computation acts that P118 brings to web retrieval acts.
Summary of the Disclosure
[0007] This disclosure defines the Piea Computer Use and Execution Surface Standard: a governed pathway for code execution, shell operations, and file system interactions as ledger-recorded, hash-bound, actuation-receipted events within the AIEP substrate.
[0008] The standard defines: execution modes, ExecutionRecord construction, the distinction between read-only and write execution, the execution admissibility gate, command output as governed evidence, the file system state model, and the execution surface in the P118 interface.
Part I — Execution Modes
[0009] Piea operates in two execution modes:
Mode E1 — Read-only execution. Commands that observe the environment without modifying it. Examples: running unit tests, parsing files, analysing data, executing a computation from a formula, reading a file’s contents, listing directory contents. No persistent side effects. The environment is unchanged after the execution.
Mode E2 — Write execution. Commands that modify the environment. Examples: creating a file, installing a package, writing to a database, running a build, modifying a configuration, sending an API request. Produces persistent side effects. The environment is changed after the execution.
[0010] Mode classification is deterministic and declared before execution proceeds. Piea does not begin execution without classifying the mode. Mode E2 execution requires explicit user authorisation before the execution gate opens.
[0011] Mode classification is conservative: if a command’s mode is ambiguous, it is classified as E2. The E2 classification cannot be downgraded by the language model — only by an explicit user declaration.
Part II — ExecutionRecord
[0012] Every command Piea executes — in either mode — commits an ExecutionRecord to the Evidence Ledger before execution begins (reservation) and updates it after execution completes (outcome):
{
"record_type": "execution_record",
"execution_id": "<uuid>",
"execution_mode": "E1",
"command": {
"type": "bash",
"instruction": "python3 analyse_data.py --input data.csv --output summary.json",
"working_directory": "/home/piea/workspace",
"environment_variables_declared": ["PYTHONPATH"]
},
"command_hash": "sha256:<hash(canonical(command))>",
"user_authorisation": {
"required": false,
"authorised_at": null,
"authorisation_hash": null
},
"reserved_at": "ISO8601",
"executed_at": "ISO8601",
"outcome": {
"status": "SUCCESS",
"exit_code": 0,
"stdout_hash": "sha256:<hash>",
"stderr_hash": "sha256:<hash>",
"stdout_truncated": false,
"side_effects": []
},
"output_artefact_refs": ["<output_artefact_id_if_any>"],
"actuation_receipt_hash": "sha256:<hash>"
}
[0013] command_hash is computed before execution. It binds the exact command as declared. If the command changes between declaration and execution, the hashes will not match — tampering is detectable.
[0014] stdout_hash and stderr_hash are computed over the raw bytes of the standard output and standard error streams respectively. They are computed immediately on execution completion, before the output enters Piea’s reasoning context. This is the same property as ContentHash for web artefacts: what Piea reasons from is what the execution produced, proven by hash.
Part III — Execution Admissibility Gate
[0015] The R5 fail-closed gate applies to execution requests. Before any command executes, an ExecutionAdmissibilityAssessment is performed:
(a) Is the command within the declared capability envelope for the current session? (b) For E2 commands: has the user granted explicit authorisation? (c) Does the command target a protected path or resource (user’s private files, system directories, network interfaces not in the declared tool suite)? (d) Does the command’s declared side effects comply with the user’s session policy?
[0016] A CLOSED assessment suppresses execution and commits a NegativeProofRecord:
{
"record_type": "negative_proof",
"input_type": "execution_request",
"command_hash": "sha256:<hash>",
"attempted_at": "ISO8601",
"reason": "e2_authorisation_not_granted",
"detail": "Write execution requires explicit user authorisation. User has not authorised this command.",
"proof_hash": "sha256:<hash>"
}
[0017] Piea does not execute suppressed commands silently. She commits the NegativeProofRecord and tells the user what was suppressed and why.
Part IV — Command Output as Governed Evidence
[0018] The stdout and stderr of every executed command are treated as governed evidence inputs on admission to Piea’s reasoning context. They follow the same pathway as tool outputs under P26 IntegrationHooks:
execute(command)
→ capture(stdout, stderr)
→ computeHash(stdout) // stdout_hash — binds the output
→ computeHash(stderr)
→ buildExecutionOutputArtefact()
→ gate(admissibilityCheck) // R5 — could a malicious command inject false evidence?
→ commit(EvidenceLedger)
→ admitToReasoningContext()
[0019] The admissibility gate on command output guards against command injection attacks where a malicious script produces output designed to manipulate Piea’s reasoning. The gate evaluates: does this output conform to the declared output schema for this command type? If not, the output is CLOSED and a NegativeProofRecord is committed.
[0020] Output that passes the gate enters Piea’s reasoning context as a hash-bound ExecutionOutputArtefact. Claims derived from command output are traceable to the specific stdout_hash of the specific execution that produced them.
Part V — File System State Model
[0021] Piea maintains a FileSystemStateRecord tracking the files she has created, modified, or deleted in the current session. The record is append-only:
{
"record_type": "filesystem_state",
"session_id": "<uuid>",
"entries": [
{
"event": "created",
"path": "/home/piea/workspace/summary.json",
"file_hash": "sha256:<hash>",
"timestamp": "ISO8601",
"execution_id": "<uuid>"
},
{
"event": "modified",
"path": "/home/piea/workspace/summary.json",
"file_hash_before": "sha256:<hash>",
"file_hash_after": "sha256:<hash>",
"timestamp": "ISO8601",
"execution_id": "<uuid>"
}
]
}
[0022] The FileSystemStateRecord gives Piea — and the user — a complete audit trail of every file change in the session. The file_hash at each state transition proves what the file contained at that moment.
[0023] When Piea delivers a file to the user (via P120 OutputArtefactRecord), the output_hash in the OutputArtefactRecord is the final file_hash_after in the FileSystemStateRecord for that path. The chain is complete: execution → file system change → output artefact → delivery.
Part VI — Sandboxed Execution Environment
[0024] Piea’s execution surface operates within a sandboxed environment. The sandbox is declared in the session policy and constrains:
(a) permitted paths: directories Piea may read and write; (b) permitted executables: binary allowlist for E2 commands; (c) network access: whether outbound requests are permitted, and to which destinations; (d) resource limits: CPU time, memory, and file size limits per command.
[0025] The sandbox policy is a signed, versioned document committed to the Evidence Ledger at session start. Every ExecutionRecord references the sandbox_policy_hash under which it was executed. This enables auditors to determine exactly what permissions Piea had at the time of each execution.
[0026] The sandbox cannot be expanded during a session without user authorisation. An expansion request produces an AuthorisationRequest committed to the ledger, user authorisation produces an AuthorisationRecord, and the expanded sandbox policy is committed as a new version with the old version’s hash in its previous_policy_hash field.
Part VII — Execution Surface in the P118 Interface
[0027] Executed commands appear in the Evidence Rail as execution entries, distinguished by a terminal indicator >_:
┌─────────────────────────────────────────┐
│ >_ python3 analyse_data.py 14:46 │
│ sha256: 4a1f7c3d… E1 · exit:0 │
│ stdout 2,847 bytes · 0.3s │
└─────────────────────────────────────────┘
[0028] E2 (write) executions display an amber border until user authorisation is granted, then transition to teal on execution:
┌─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
│ >_ pip install pandas pending │ ← amber dashed border
│ E2 write execution · awaiting auth │
│ [Authorise] [Decline] │
└─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
[0029] Suppressed commands (CLOSED by admissibility gate) appear with a red ✗ indicator:
┌─────────────────────────────────────────┐
│ ✗ rm -rf /home/user/documents 14:47 │
│ sha256: 8b2e5a7c… SUPPRESSED │
│ reason: protected_path │
└─────────────────────────────────────────┘
[0030] The full execution history is always visible in the Rail. The user always knows what Piea has executed, what mode it was in, whether it succeeded, and what it produced. Nothing executes without appearing in the Rail.
Part VIII — Relationship to Existing Specs
[0031] The execution surface completes the AIEP actuation model alongside P75 (Environmental Feedback Actuation Receipt System). P75 defines the actuation receipt mechanism generically. P121 applies it specifically to code execution and file system operations with the additional properties required for a governed AI agent: execution mode classification, output hashing, command injection defence, and sandbox policy binding.
[0032] The execution surface complements P120 (Governed File Output). Files generated by the execution surface are covered under P120’s OutputArtefactRecord mechanism. The output_artefact_refs field in the ExecutionRecord links the execution to the files it produced.
[0033] The execution surface complements P119 (Multimodal Document Ingestion). Files read from the file system during execution are treated as governed evidence inputs if they inform Piea’s reasoning output — they are processed through the P119 ingestion pathway before admission to the reasoning context.
Claims
-
A computer use and execution surface standard for a governed AI agent comprising: (a) execution mode classification into read-only (E1) and write (E2) modes, where E2 requires explicit user authorisation before the execution gate opens; (b) an ExecutionRecord committed to the Evidence Ledger before and after every command execution, comprising command_hash, execution mode, stdout_hash, stderr_hash, and ActuationReceiptRecord reference; (c) an R5 fail-closed admissibility gate applied to execution requests, with NegativeProofRecord commitment on CLOSED result; (d) command output treated as governed evidence: stdout and stderr are hashed on capture, gated for admissibility, and committed as ExecutionOutputArtefacts before admission to the reasoning context; (e) a FileSystemStateRecord tracking file creation, modification, and deletion events with file_hash at each state transition; and (f) a signed, versioned sandbox policy declared at session start and referenced by hash in every ExecutionRecord.
-
The standard of Claim 1 wherein the stdout_hash provides the same property for execution outputs as ContentHash provides for web-fetched artefacts: what Piea reasons from is exactly what the execution produced, proven by hash, before any possibility of manipulation.
-
The standard of Claim 1 wherein the Evidence Rail displays all execution entries — active, suppressed, and pending authorisation — with mode indicator, hash, exit code, and output size, ensuring no execution is hidden from the user.
-
The standard of Claim 1 wherein the FileSystemStateRecord’s file_hash chain links execution events to P120 OutputArtefactRecord delivery: the output_hash in the OutputArtefactRecord equals the final file_hash_after for that path in the FileSystemStateRecord.
-
A computing system implementing the governed execution surface of Claims 1 to 4.
-
A non-transitory computer-readable medium storing instructions which, when executed, implement a governed execution surface conforming to the standard of Claims 1 to 4.
Abstract
P121 defines the Piea Computer Use and Execution Surface Standard: a governed pathway for code execution, shell operations, and file system interactions as ledger-recorded, hash-bound, actuation-receipted events. Execution mode classification distinguishes read-only (E1) from write (E2) operations; E2 requires explicit user authorisation. An ExecutionRecord is committed before and after every command, carrying command_hash, stdout_hash, stderr_hash, and ActuationReceiptRecord reference. The R5 fail-closed gate applies to execution requests. Command output is treated as governed evidence: stdout and stderr are hashed on capture, gated for admissibility, and committed as ExecutionOutputArtefacts before admission to Piea’s reasoning context — defending against command injection attacks. A FileSystemStateRecord tracks all file state transitions with file_hash at each event. A signed, versioned sandbox policy constrains permitted paths, executables, and network access, referenced by hash in every ExecutionRecord. The Evidence Rail displays all execution events — active, pending authorisation, and suppressed — with full hash visibility.
P121 — AIEP — Piea Computer Use and Execution Surface Standard Phatfella Limited · United Kingdom · aiep.dev · Apache License 2.0 · 2026