Extension Permissions

An extension declares one list: the Host API methods it calls. Compozy derives everything else — the consent summary an operator sees, the enforcement set, and the ceiling that applies to the install source.

compozysdk.NewExtension(compozysdk.ExtensionDefinition{
	Name:    "release-notes",
	Version: "0.1.0",
	Permissions: compozysdk.PermissionsConfig{
		Requires: []compozysdk.HostAPIMethod{"sessions/list", "memory/recall", "memory/store"},
	},
	Subprocess: compozysdk.DescribeSubprocess{Command: "./bin"},
})

compozy extension build writes that list into the generated manifest:

[permissions]
  requires = ["memory/recall", "memory/store", "sessions/list"]

Closed set

permissions.requires is validated against a closed set of 87 Host API methods at build, validate, install, and daemon load. An unknown value is a hard error, never a silent no-op:

ERROR permissions.requires[0]  unknown Host API permission

Both SDKs export the method names as typed constants, so a typo fails before the daemon sees it.

Derived consent areas

Compozy maps every method to one area:access pair and shows the deduplicated set wherever consent is presented. compozy extension validate prints exactly what an operator will be asked to accept:

compozy extension validate ./dist/gen-<hash>

Extension bundle validation
===========================
Status:   valid
Issues:   0
Consent:  memory:read, memory:write, sessions:read

The same summary is available structurally:

compozy extension validate ./dist/gen-<hash> -o json

{
  "manifest": {
    "name": "hello",
    "provides": ["tool.provider"],
    "permissions": ["memory/recall", "memory/store", "sessions/list"]
  },
  "issues": [],
  "consent_areas": [
    { "area": "memory", "access": "read" },
    { "area": "memory", "access": "write" },
    { "area": "sessions", "access": "read" }
  ]
}

Consent areas are a display and policy projection. Enforcement always runs against the declared method list, per call.

Permission catalog

Twenty-six consent areas cover the 87 methods.

Read and write are separate areas everywhere, so a read-only reviewer extension never requests a mutation grant. Paged collection methods (tasks, tasks/inbox, automation/jobs, automation/triggers, and the network/* collections) return bounded envelopes with page metadata — read the collection field and its page metadata together, never as a bare array.

Source ceilings

The install source decides how much of the declared list can be granted.

The published ceiling is logs.read, memory.read, observe.read, session.read, skills.read, and tool.read. A published extension that declares sessions/prompt, models/refresh, or tasks/create still installs, but those methods are not granted, and the trust report names each dropped request. Read the outcome with:

compozy extension provenance <name> -o json

Design for it: keep the published surface read-oriented, and ship anything that must mutate runtime state as a local or workspace-linked extension.

Enforcement

Every Host API call is checked against the extension's effective grant at call time. A denied call returns the protocol capability_denied error with the method name; it does not fall back to a partial result. The grant is computed once per session scope from three inputs — the declared list, the source ceiling, and the operator resource policy under [extensions.resources] — and never widens at runtime.

Resource publication (resources/snapshot) carries a second axis: the manifest declares the resource families and scope ceiling it requests under [resources.publish], and the effective grant is the narrowest of manifest request, source tier, operator policy, and session scope.

Related

• Develop Extensions — where permissions fit in the authoring loop.
• Extension Manifest — the generated [permissions] block.
• Install Extensions — trust, consent, and provenance at install time.
• compozy extension validate — generated CLI reference.