Extension Permissions

An extension declares one list: the Host API methods it calls. CompozyOS 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", "skills/list"},
	},
	Subprocess: compozysdk.DescribeSubprocess{Command: "./bin"},
})

compozy extension build writes that list into the generated manifest:

[permissions]
  requires = ["sessions/list", "skills/list"]

Closed setCopy Anchor Link

permissions.requires is validated against the closed Host API method set 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.

The retired memory/* methods, together with the memory.read and memory.write entries, are the one exception: a manifest that still requires them keeps loading with those entries dropped. See Retired manifest entries.

Derived consent areasCopy Anchor Link

CompozyOS 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 package validation
===========================
Status:   valid
Issues:   0
Consent:  sessions:read, skills:read

The same summary is available structurally:

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

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

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

A subprocess bound to a workspace and named profile retains both owners for domain Host API calls. For example, tasks/create can omit the workspace and scope: the daemon binds them to the process's workspace and stamps the task with its profile. Explicit global or foreign workspace requests are refused. Resource methods retain the complete workspace_profile scope for kernel authorization; approving a palette command does not expand the extension's scope.

Permission catalogCopy Anchor Link

Twenty-four consent areas cover the cataloged 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) return bounded envelopes with page metadata — read the collection field and its page metadata together, never as a bare array.

Source ceilingsCopy Anchor Link

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

The published ceiling is logs.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.

EnforcementCopy Anchor Link

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.

RelatedCopy Anchor Link

• 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.