Zephr Docs

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:

  1. The manifest parses and validates against the schema.
  2. The integrity sha512 pin matches the fetched artifact.
  3. The scope binding passes fleet-domain strict validation.
  4. 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 dispatch

Persistence and security

  • Integrity: every extension carries a sha512 pin verified before any code loads. A mismatch refuses install.
  • Scope enforcement: the same evaluateTierEnforcement gate 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 | community tiers 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

FailureRecovery
Integrity pin mismatchInstall refused; verify the package source
Scope validation failureInstall refused; the manifest declares a scope the org rejects
Hook handler throwsExtension marked degraded; lifecycle loop continues
Extension tool call without tier granttier_denied error; admin must grant the tier
Extension uninstalledRules 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 consumes on 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.