§12 Projections

A projection is a view of a pack on some surface. Projections MUST NOT add, remove, or alter Policy, Binding, or Principal semantics, and MUST NOT add commands the pack does not declare.

12.1 CLI#

1. A pack's CLI face SHOULD follow <bin> <space> [<sub…>] [--flags] [--json].
2. Every command SHOULD emit structured output when --json is present and MUST exit non-zero on failure.
3. Health and Binding commands (doctor, status, login, connect, whoami) SHOULD be first-class spaces, not flags on other commands.
4. Verbs SHOULD be read by default; --apply / --confirm SHOULD mark a write.
5. Selectors (--entity, --account, --pool) MUST refine within the Principal's resolved scope; they MUST NOT select tenant (§9.2).
6. A CLI face MUST NOT prompt interactively when invoked by an agent.
7. doctor and status SHOULD exit 0 when healthy, 2 on a warning, and 1 on failure.
8. A CLI with an installer SHOULD expose it as the family setup.status (read, idempotent: what is installed and linked), setup.apply (write; runs without prompts for an agent Invoker), and setup.update (write; refreshes the Skill after a pack upgrade).
9. Health commands are read and MUST NOT mint long-lived credentials.

12.2 Host tools#

A host projects packs into a tool-calling model in one of two shapes.

1. A host whose agent can run shell commands SHOULD expose a single tool, or the runtime's binary itself (hcpx in the reference), that forwards argv to a runtime (hcpx exec <pack_id> <verb_key> -- k=v …), together with a Skill that teaches it. Activating a pack MUST NOT require the host to register additional tools.
2. A host that runs an in-process tool loop MAY instead expose one tool per executable command. Such tools SHOULD be named <pack_id>__<verb_key_with_dots_as_underscores> (for example mail__mail_list).
3. A host SHOULD expose hcp__read_skill (or equivalent) returning the full Skill for a pack, so that the system prompt may carry only leads (§5.3).
4. Tool descriptions SHOULD carry operation, land, and confirm so that the model can distinguish reads from writes.
5. A host MUST route every tool call through a runtime that implements §6.3. A host MUST NOT execute wrap.bin itself.
6. A host MUST filter the projected tool set by the Principal's grants.

12.3 Generated surfaces#

Informative. The reference hcpx generate produces, from activated packs: a stable system-prompt block, a tool list per §12.2, a set of Skill copies, and each host's own configuration (an MCP server entry, a plugin file, or in-process tool definitions). hcpx adopt <host> --write writes them where that host reads its configuration.

12.4 Four faces#

The same command MUST be nameable consistently on four faces:

1. Runtimes SHOULD lint drift among these faces.
2. Renaming a command on one face without the others is a breaking change (§13).

12.5 Export to other protocols#

1. A runtime MAY export a pack's commands as MCP tools, A2UI components, OpenAPI operations, or any other surface. The reference MCP export is a single tool named hcp (§12.2.1).
2. An export MUST preserve the pack as the unit: one pack → one exported group.
3. An export MUST route invocations back through a runtime that implements §6.3; an export MUST NOT reimplement Policy or Binding.
4. An export MUST NOT be the install unit. Installing the export MUST NOT substitute for installing the pack.
5. Sense MUST NOT be exported as a tool the model can call to "poll".

12.6 What a projection may drop#

A projection MAY omit commands the Principal cannot execute and MAY omit the hcp protocol metadata. A projection MUST NOT omit confirm markers on gated writes.