Skip to main content

Capability Boundary Contract

Demiurge capabilities are host-owned. Authored files request host-mediated work through ctx.* clients, host tools, MCP calls, schedules, or package-provided components; the host decides whether those effects run.

Host-Mediated Effects​

These effects must go through host-owned interfaces or explicit host capability checks:

  • filesystem reads and writes
  • terminal execution
  • network fetches
  • provider calls
  • tool execution
  • MCP tool calls
  • schedule management
  • state reads and writes
  • child agent runs and spawns
  • Git revision promotion
  • rollback
  • package repository trust
  • dependency changes

Capability Rule​

Authored code must require the capability it depends on:

ctx.capability.require("fs.read", slot_path=ctx.slot_path)

The capability must be declared in one of these places:

  • agent.yaml under capabilities.defaults
  • agent.yaml under capabilities.slots.<slot_path>
  • the component manifest's capabilities list

Prefix grants such as mcp.connect:* and mcp.call:* may grant scoped capabilities such as mcp.connect:docs and mcp.call:docs.

Approval Rule​

Approval policy can come from:

  • built-in tool metadata
  • authored tool metadata
  • MCP server metadata
  • tools.metadata
  • agent.yaml approval config
  • global fallback approval config
  • channel/runtime approval provider behavior

deny is always terminal. prompt requires an approval provider. auto can run without asking only after capability and workspace checks pass. For terminal execution, auto additionally requires an allow/low command guard decision. Global fallback policy cannot lower a prompt/high or unknown terminal decision, and hardline blocks never reach approval. Executing workspace/project code, applying an explicit environment overlay, or binding a Host secret requires explicit approval.

Workspace Rule​

File writes, patches, and terminal working directories must stay inside the resolved workspace unless the host explicitly permits another root. Built-in file reads may target host-visible paths outside the workspace, but outside-workspace and sensitive reads require approval. Authored code should not hard-code private local paths.

Secrets Rule​

Provider keys, bot tokens, webhook secrets, SMTP credentials, and MCP secrets belong in host config, environment variables, or .env. Authored slots and tools should report secret sources, not secret values.

Terminal subprocesses receive an allowlisted environment and a dedicated runtime HOME; they do not inherit Host credentials. A secret can enter a foreground terminal effect only through secret.bind:<ENV_NAME> plus one-shot approval. The binding expires no later than the command timeout, is forbidden for background execution, is audited by source/name rather than value, and is exact-value-redacted from returned stdout/stderr.

The grant must be exact; secret.bind:* is not accepted. A binding cannot target execution-control variables such as PATH, HOME, shell selectors, loader hooks, or language runtime search paths. Its earliest expiry clamps the foreground subprocess deadline.

Channel Rule​

External channels validate inbound events before creating a turn. Examples:

  • Telegram checks allowed_users and allowed_chats.
  • Webhook checks token or allow_unauthenticated.
  • Slack checks request signatures.
  • Mattermost checks webhook tokens.
  • Matrix checks homeserver credentials and optional room allowlists.
  • Email checks credentials and optional sender/recipient allowlists.

The Agent Core does not gain network authority just because a channel is enabled.

Dependency Rule​

Candidate Agent Cores and package recipes must not install Python dependencies. Record dependency needs as manual review items.

Boundary​

A capability declaration is necessary for an effect, but it is not the whole security decision. The host still applies workspace scope, command guards, approval policy, channel policy, runtime task rules, and provider/tool runtime rules.