---
title: "§6 Execute"
description: "Normative definition of the inbound loop: the exec envelope, the fail-closed pipeline, wrap argv rendering, the result envelope, and the twin face."
canonical: https://harnesscontextprotocol.io/docs/specification/execute
---

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

```json
{ "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

```json
{ "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.

1. 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.
2. 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.
3. Append `--json`.
4. Resolve `wrap.bin`: `.`-prefixed paths against the pack root; otherwise as
   given.
5. Spawn `wrap.bin` with the argv as an array. Runtimes MUST NOT construct a
   shell command string from untrusted values.
6. Set the working directory per §10.6 (`wrap.workspace.mode`: pack root,
   ephemeral jail, or local-land jail). Set `HCP_SANDBOX` to `sandbox` or
   `native-local` in the child environment. Merge `wrap.agent_env`. When the
   workspace mode is `workspace`, set `home_env` (default `HOME`) to that jail.
7. Rewrite `workspace:` file tokens and `file_flags` values into the jail.
   Host-absolute paths under `/etc`, `/home`, `/root`, and `/Users` MUST fail
   with `sandbox: host path not allowed`.
8. 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

1. Every command SHOULD be invokable on the CLI face
   (`<bin> <space…> [--flags] --json`) and MUST be invokable on the JSON face.
2. For equal arguments the two faces MUST produce the same `result`.
3. The CLI face MUST emit structured output (`--json` or JSON by default) and
   MUST exit non-zero on failure.
4. The CLI face MUST NOT prompt interactively on the agent Invoker path.
5. `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

1. `composite` execution is in-process. The result envelope is identical.
2. 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.

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)