Extensions
The extension platform provides a unified manifest, installed-extension registry, isolated runtime, lifecycle hooks, MCP tools, signal producers, integrity verification, scope admission, revocation, and curation state.
Status
Evolving (2026-08-17 audit, ZEP-1975). The store, install-safety, manifest validation,
and revocation ship. Extension-declared MCP tools are not wired —
registerExtensionToolNames has zero production callers; installed manifest.tools never
reach tools/list. Wave 1B will connect the registry.
Core concepts
Extension manifest (zephr.extension.json)
Every extension declares itself through a zephr.extension.json manifest at the package
root:
{
"id": "acme/zephr-ext-gh",
"displayName": "ACME GitHub Extensions",
"version": "1.0.0",
"author": "ACME",
"description": "GitHub tooling for Zephr",
"integrity": {
"algorithm": "sha512",
"digest": "<sha512-hex>"
},
"scope": {
"toolsAllow": ["ext_github_*"],
"toolsDeny": [],
"write": false,
"network": [{ "host": "api.github.com" }],
"toolBudget": 50
},
"hooks": {
"post_tool_use": { "enabled": true, "scope": "workspace" }
},
"tools": [
{
"name": "ext_github_list_prs",
"description": "List GitHub PRs",
"inputSchema": { "type": "object" },
"tier": "extension"
}
],
"signals": [
{
"signalType": "ext_github_pr_stale",
"description": "A PR went stale",
"readiness": "ready",
"metricKind": "event",
"write": false
}
],
"curation": {
"signature": "<ed25519-signature>",
"tier": "verified",
"curator": "curator-key-id",
"curatedAt": "2026-09-02T00:00:00Z"
}
}Scope binding
The extension scope maps directly onto the fleet-domain ScopeBinding wire shape:
toolsAllow, toolsDeny, write, network, toolBudget, when. It is validated by
the same strict parser used for fleet profiles (packages/fleet-domain/src/validation.ts).
An org-level merge that narrows the scope (toolsDeny union, toolBudget max) cannot be bypassed by the extension.
Lifecycle hooks
Extension hook handlers use the same required eight-method LifecycleAdapter contract as first-party adapters: session start/end, prompt submit, pre/post tool use, tool failure, pre-compact, and stop. Dispatch isolates handler failures so one extension does not terminate the lifecycle loop.
An extension's handler throwing does not take down the lifecycle loop. The existing
dispatch() try/catch catches it, the lifecycle loop continues, and the extension is
marked degraded in the extension health leaf.
Setup and configuration
Installing an extension
zephr extension install <manifest> --artifact <path-or-url>The CLI verifies:
- The manifest parses and validates against the schema.
- The integrity sha512 pin matches the fetched artifact.
- The scope binding passes fleet-domain strict validation.
- No scope widening is introduced relative to the org-level policy.
Tier grants for extension tools
Extension tools are assigned tier 'extension', which is not granted by default. An
admin must add 'extension' to a role's allowedTiers:
{
"roleId": "role-id",
"allowedTiers": ["core", "search", "docs", "extension"]
}Revoking an extension
zephr extension uninstall <extension-id>Revocation removes the extension's tools from the registry, unregisters its hooks, and
marks the extension as revoked. The manifest is retained for audit purposes.
Data flow
Extension installed
→ Manifest parsed and validated
→ Integrity pin verified (sha512)
→ Scope binding enforced (fleet-domain validation)
→ Hooks registered through ScopeBoundLifecycleAuthority
→ Tools registered in createToolRegistry (tier: 'extension')
→ Extension available for lifecycle dispatchPersistence and security
- Integrity: every extension carries a sha512 pin verified before any code loads. A mismatch refuses install.
- Scope enforcement: the same
evaluateTierEnforcementgate that gates first-party tools gates extension tools. No code path skips the check for extension-origin tools. - Failure isolation: each extension's hook handlers run in their own try/catch. A failing extension cannot take down other extensions or the lifecycle loop.
- Egress declaration: the manifest network list is validated and intersected with org policy. Host API boundaries must enforce that scope; the isolate alone is not a network sandbox.
- Curation: the
verified | communitytiers exist in the manifest schema. Verified extensions are signed with Ed25519 keys; community extensions are unsigned.
Limits
- Extension-declared signals have no complete provenance chain or signing path (designed, not shipped).
- The curation registry (review workflow, deprecation lifecycle, security review badges, signed packaging) is designed but not implemented.
- No extension may widen scope relative to the org-level policy.
Failures and recovery
| Failure | Recovery |
|---|---|
| Integrity pin mismatch | Install refused; verify the package source |
| Scope validation failure | Install refused; the manifest declares a scope the org rejects |
| Hook handler throws | Extension marked degraded; lifecycle loop continues |
| Extension tool call without tier grant | tier_denied error; admin must grant the tier |
| Extension uninstalled | Rules referencing its signals return producer_absent |
What is designed but not shipped
- Signal provenance and signing: extension signals have no provenance chain, no signing, and no audit trail distinguishing them from first-party signals.
- Hook ordering: the current spec mandates ordering but defines no ordering contract between extensions (ordinal + priority). Designed but not implemented.
- Composition: chain-ordering model, conflict-detection API, and capability-inheritance
when extensions declare
consumeson other extensions. Designed but not implemented. - Curation registry: review workflow, deprecation lifecycle (warning → removal deadline → auto-uninstall), security review badges, and signed packaging (sigstore). Designed but not implemented.
Related references
- Extensions spec — full requirements and scenarios
- Agent runtime — extension tool tier
- Surfaces — lifecycle adapter interface
- Universal integration — extension host packs