§6 Execute

Normative definition of the inbound loop: the exec envelope, the fail-closed pipeline, wrap argv rendering, the result envelope, and the twin face.

Execute is the inbound loop: an Invoker runs a command.

6.1 Exec envelope

{ "pack_id": "ledger", "verb_key": "transfer", "args": { "amount": 10, "confirm": true } }

Field	Type	Req	Constraint
`pack_id`	string	MUST	Runtimes MUST accept `surface_id` as an alias
`verb_key`	string	MUST	A declared command
`args`	object	MAY	Default `{}`

Reserved args keys:

Key	Meaning
`confirm`	`true` satisfies a `confirm` gate
`apply`	Synonym of `confirm`
`mode`	`"mock"` requests explicit mock Binding

6.2 Result envelope

{ "ok": true, "pack_id": "transit", "verb_key": "plan", "result": { … } }
{ "ok": false, "pack_id": "ledger", "verb_key": "transfer", "error": "confirm required" }

Field	Type	Req
`ok`	boolean	MUST
`pack_id`	string	MUST
`verb_key`	string	MUST
`result`	any	SHOULD when `ok`. Parsed JSON stdout when parseable; else the raw string
`error`	string	MUST when `ok` is false
`stdout`, `stderr`	string	MAY (wrap)

A denial MUST be returned as a result envelope with ok: false, not raised as a transport error, so that Invokers can branch on it.

6.3 Pipeline

A runtime MUST evaluate the following in order and MUST stop at the first failure. Nothing after a failing step MAY execute.

#	Step	Failure → `error`
1	Resolve pack	`unknown pack <id>`
2	Pack activated on this session	`pack <id> not activated`
3	Resolve Policy entry	`no policy for <verb_key>`
4	Authenticate Principal; resolve tenant and, if land is `brain`, project	`denied: privacy.land brain requires project_id`
5	Assert capability (§9.4)	`denied: missing <capability> for <pack>.<verb>`
6	Enforce `confirm` (§4.5)	`confirm required`
7	Mint Binding (§8.4)	runtime-defined; MUST fail closed
8	Run Adapter in sandbox (§10)	`sandbox: bin "<bin>" not allowlisted`, or stderr / `exit <n>`
9	Return result; audit (§9.6)	none

6.4 Wrap rendering

For kind: wrap, the runtime MUST build the child argv as follows.

If the command declares cli[]: drop the first token (the bin name); for each remaining token, replace {{name}} with String(args.name) and --flag={{name}} with --flag=<value>; remove tokens that render empty.
Otherwise render wrap.argv_template, where {{verb}} expands to the command tail (verb_key after the first ., or the whole key; split on whitespace) and {{name}} as above.
Append --json.
Resolve wrap.bin: .-prefixed paths against the pack root; otherwise as given.
Spawn wrap.bin with the argv as an array. Runtimes MUST NOT construct a shell command string from untrusted values.
Set the working directory to the pack root (or the runtime's jail for that pack) and set HCP_SANDBOX to sandbox or native-local in the child environment. Merge wrap.agent_env.
Exit code 0 → ok: true. Non-zero → ok: false, error = stderr if non-empty else exit <code>. Exit 127 denotes a missing or non-allow-listed bin.

6.5 Twin face

Every command SHOULD be invokable on the CLI face (<bin> <space…> [--flags] --json) and MUST be invokable on the JSON face.
For equal arguments the two faces MUST produce the same result.
The CLI face MUST emit structured output (--json or JSON by default) and MUST exit non-zero on failure.
The CLI face MUST NOT prompt interactively on the agent Invoker path.
hcp exec <pack_id> <verb_key> [-- k=v …] is the reference CLI's envelope Invoker; k=v pairs become args.

6.6 Composite and other adapters

composite execution is in-process. The result envelope is identical.
A runtime that does not implement an adapter kind MUST return ok: false with error: "adapter <kind> not executable in <runtime>".

6.7 Prohibitions

A runtime MUST NOT execute a command lacking a Policy entry.
A runtime MUST NOT fall back to environment credentials when mint fails.
A runtime MUST NOT accept a pack-level pass-through command as a substitute for named commands beyond bootstrap.
Health commands (doctor, status) MUST NOT mint long-lived credentials as a side effect.