Extend with hooks

Discover host capabilities, define a verifiable adapter contract, and require real-host evidence before shipping.

There is no unified HostAdapter SDK. The contract names below are a design checklist, not current classes or stable public APIs.

Start with capability discovery

Do not begin by copying the nearest integration. First record what the new host can actually expose:

• a stable prompt event and its ordering;
• turn, message, session, workspace, and project identity;
• a transient pre-dispatch injection channel;
• tool and command registration;
• permission requests, confirmation UI, and headless behavior;
• package, plugin, and bundled Skill installation;
• end, compaction, switch, shutdown, and interruption events;
• a CLI/version probe and an activation probe.

Query GET /v1/capabilities as well. It reports Server features such as memory_extraction, experience_generation, managed_skill_generation, external_skill_registry, Handoff generation, search modes, and context versions. Host capability discovery and Server capability discovery answer different questions; you need both.

If the host has no stable prompt event, no pre-dispatch injection point, or no permission surface, say so. That capability is Unsupported unless you implement another contract with equivalent guarantees. If the host appears to expose it but no real-host test proves the path, mark it Not validated.

Write the adapter contract

Use this vocabulary to force the important decisions into the open:

PromptEvent
ScopeResolver
PreparedContextProvider
TransientInjector
SourceCapture
FlushCoordinator
ToolSurface
PermissionGate
Diagnostics
Installer / Doctor

These are proposed roles. Define the input, output, failure policy, security boundary, and observable assertion for each one.

Role	Contract to settle
PromptEvent	Exact host event, prompt normalization, lifecycle ordering, and stable turn identity.
ScopeResolver	Authorized override, Git identity, project fallback, normalization, and cache lifetime.
PreparedContextProvider	/v1/context/prepare, accepted schema versions, response-size budget, and fail-open result.
TransientInjector	Where context enters, how it is labeled untrusted, and proof that it is not persisted by injection.
SourceCapture	Captured content, deterministic Source identity, metadata, secret policy, UTF-8 byte limit, and returned position.
FlushCoordinator	Pending state per Scope, boundary events, retry/deadline budget, and current_cursor >= position clearing rule.
ToolSurface	Exact operation allowlist, generated schema source, tool result shape, and unsupported operations.
PermissionGate	Read versus mutation, approval UX, denial, cancellation, and behavior when no UI exists.
Diagnostics	Activation, version, package ownership, Server state, and content-free error reporting.
Installer / Doctor	Idempotency, ownership, rollback, activation probe, and partial-failure status.

Automatic recall, capture, and optional flush may fail-open. Explicit durable writes, Review, Handoff commit, and Skill export must report failure. Do not use one policy for both groups.

Minimal usage

Start with one prompt path, one boundary path, and one explicit mutation. Keep every unsupported capability out of the first slice.

Execution flow

Keep host glue thin. It should resolve identity, call verified helpers, and translate the result into the host’s native event shape.

onPrompt(event)
→ normalize PromptEvent
→ resolve Scope
→ prepare context and capture Source independently
→ retain returned position for bounded flush
→ inject PreparedContext through the host's transient channel

onBoundary(event)
→ flush pending position for the same Scope

onMutation(call)
→ validate Scope and payload
→ request host permission
→ execute only after approval

If the host cannot implement one of these arrows, remove the claim. Do not hide the gap behind a generic adapter name.

Reuse current implementation

Reuse code only where its contract already matches the host:

• the generated HTTP client and transport models under powercontext.http;
• canonical PreparedContext and capability models;
• Python capture rendering and redaction helpers;
• shared loopback transport vectors;
• Codex and Claude Code prepared-context validation patterns;
• host-specific Scope normalization tests;
• Pi’s pending-position flusher pattern;
• DSH and other generated operation tables;
• Codex and Claude Code managed Skill projections;
• the first-class setup/doctor catalog and common Diagnostic value model.

Several helpers are repeated rather than shared today. Scope resolution, PreparedContext validation, deadline and redirect policy, secret detection, Source ID construction, and bounded flush logic still live in separate host packages. Similar file names do not make them a supported SDK.

Scope, injection, capture, and flush

A new host must define these four boundaries together.

For Scope, derive identity from stable, authorized project data. Strip credentials from Git remotes. Do not trust a model-supplied scope_id, and do not reuse session identity as repository identity unless the host contract proves they are the same.

For injection, use a native transient channel before model dispatch. Mark PreparedContext as untrusted historical evidence. A system guide that merely tells the model to search Memory is not proof that recall was injected.

For capture, state exactly which side of the turn is recorded. Filter secret-shaped content before transport and enforce limits in UTF-8 bytes. Keep recall and capture independent so one failure does not erase the other’s valid result.

For flush, retain the Source position by Scope and clear it only when current_cursor >= position. Every retry loop needs a call limit and a wall-clock budget. When the host lacks a reliable boundary event, automatic flush is Unsupported; when the event exists but has not been exercised in the real host, it is Not validated.

Permission and explicit writes

List every mutating operation. Decide whether the host can ask, deny, cancel, or pause in both interactive and headless modes. Then test the exact behavior.

A host with no permission API cannot inherit Pi’s confirmation_required contract or OpenCode’s context.ask() behavior. Either fail closed in adapter-controlled code, expose the operation as read-only, or mark durable mutation Unsupported. “The model should ask first” is not a permission boundary.

Diagnostics must omit prompt content, prepared context, Scope details that can identify a private repository, authorization values, and secret-bearing payloads.

Setup and doctor

Add the host to setup only after installation and activation have separate checks.

Setup should be idempotent, preserve foreign same-name files, record ownership for files it manages, use staging for remote refresh, and restore the previous state on failure. A multi-host setup must isolate failures and report each selected row as installed, failed, or skipped.

Doctor has three jobs:

1. find the host executable and report its version evidence;
2. verify the installed package or configuration belongs to PowerContext;
3. probe activation through the host when the host offers a safe, model-free probe.

Do not treat powercontext doctor as an integration scan. The general command checks the package and Server; host checks belong in powercontext doctor <host> and the read-only powercontext doctor integrations matrix.

Acceptance tiers

Use these tiers to describe evidence. They are a page-level classification, not names from the current test framework.

1. Contract/unit: schema, Scope, size, secret, permission, and failure-policy tests.
2. Package/load: build, install, import, manifest, command, or plugin registration.
3. Service chain: a real PowerContext Server with direct hook/module execution and Source/Memory lineage.
4. Real-host E2E: launch the actual host, send a prompt, and observe lifecycle, injection, capture, flush, and permission behavior.
5. Live provider journey: run the actual host with its provider/model and retain acceptance evidence.

Package/load and service-chain tests are useful, but they do not prove host API compatibility or event ordering. A first-class host requires real-host E2E for every capability you label Supported. Provider behavior needs the fifth tier when it affects the claim.

Negative matrix

At minimum, test these cases:

Area	Experiment	Required observation
Availability	Server down or request timeout	Automatic path is bounded and fail-open.
Authentication	Wrong token	No credential, prompt, context, or private Scope leaks.
Transport	Redirect or plaintext non-loopback endpoint	Redirect is not followed; unsafe transport is rejected.
Schema	Unknown or incomplete PreparedContext	Nothing is injected.
Size	Oversized response or prompt	Work stops at the configured byte budget.
Identity	Missing, stale, or caller-supplied Scope/turn ID	No cross-project or stale-turn injection.
Capture	Disabled, secret-shaped, or failed request	Recall remains independent; no forbidden Source is sent.
Flush	Cursor lag, transient failure, or timeout	Pending position survives; retries end within budget.
Permission	Deny, cancel, or no UI	Mutation does not run unless the declared host contract permits it.
Capability	memory_extraction=false	Capture remains Source evidence; unsupported flush/extraction is not claimed.
Lifecycle	Compact, switch, shutdown, interruption	Only the matching Scope and turn state are used.
Setup	Foreign file, failed refresh, or failed activation	Existing state survives and partial failure is reported.

Add host-specific privacy cases such as private versus group sessions when the host has those concepts.

Managed Skill export

Managed Skill export currently supports only Codex and Claude Code. A bundled project-context Skill installed with another plugin does not change that matrix.

To add a new export target, implement a projection contract, target enum and OpenAPI surface, ownership rules, validation, rollback, and drift tests. Until that work exists, managed export for the host is Unsupported. If implementation exists but no real install/refresh test has run, use Not validated instead.

Unsupported vs Not validated

State	Use it when	Example
Unsupported	Code rejects, omits, or cannot safely implement the capability.	No host permission API and no adapter-controlled fail-closed mutation path.
Not validated	The path may work, but current evidence stops below the claimed host/provider boundary.	A hook passes unit and service-chain tests but no test launches the real host.

Do not merge these labels into “limited support.” One is a product boundary; the other is an evidence gap.

Completion checklist

Treat the integration as complete only when these results are observable:

• Host and Server capability discovery are recorded separately.
• Every proposed contract role has inputs, outputs, failure policy, and observable assertions.
• Host version gate or compatibility evidence and an activation probe exist.
• Scope comes from stable authorized identity and strips credentials.
• PreparedContext is validated, transient, and labeled untrusted.
• Capture defines content, Source identity, UTF-8 size limit, and secret policy.
• Flush retains position by Scope and clears only at current_cursor >= position.
• Explicit writes have tested allow, deny, cancel, and no-UI behavior.
• Diagnostics expose no content or credentials.
• Setup preserves foreign config and reports rollback or partial failure.
• Managed Skill export is Unsupported unless a complete projection target exists.
• Real-host E2E covers every Supported lifecycle and permission claim.
• Unsupported and Not validated remain separate in docs, tests, and release notes.

Only then add the host to the first-class catalog.