Repository navigation
Description
Feature description
Keep host plugins thin, and make them work when the host's model traffic goes through the gateway (#2199).
A plugin does what only the host can do: handle session events, bind the workspace to a Scope, configure tools, and show diagnostics. When the host's model traffic goes through the gateway, the gateway prepares, injects, checks, and captures each turn, and the plugin leaves that work to it. Where the gateway does not carry a host's model traffic, the plugin keeps delivering prompt-time context itself. Helpers that several plugins share are generated from one source.
Problem and proposed solution
Problem
A plugin and the gateway cannot both be on the model path. Core's before_send check requires every BEGIN_POWERCONTEXT_PREPARED_CONTEXT_V1 or BEGIN_POWERCONTEXT_PREPARED_TEXT_V1 block in a request to be declared and bound. The gateway declares only the block it injects. A plugin's block is never declared, and a plugin cannot tell that the gateway owns the turn: context_owner from #2199 is not implemented, and no plugin has a setting for it.
I ran the Codex plugin against upstream/master at 9c8f061 with Codex 0.166.0-alpha.5.1, the gateway in the combined deployment (PC_GATEWAY_CORE_UDS), an enforcing Server, and a local recording upstream. Each setup sent two messages in one thread:
| Setup | Prepares per message, plugin / gateway | Result |
|---|---|---|
| Plugin, model called directly | 1 / 0 | Both turns complete. |
| Gateway, no plugin | 0 / 1 | Both turns complete. |
| Plugin and gateway, default injection | 1 / 1 | Every check returns 422, which the Server log names context-binding-required. The gateway answers 503 gate_paused, Codex sends 30 requests per message, and the turn fails. The upstream receives nothing. |
Plugin and gateway, PC_GATEWAY_INJECTION=off |
1 / 0 | The same failure: the plugin's block alone is rejected. |
- An unmodified Codex stops earlier, at 409
output_limit_required(bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420). The gateway rows addmax_output_tokenswith a pass-through shim, as the end-to-end run in fix(gateway): capture each user turn once with a normalized transcript #2423 does. Once bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420 is fixed, a Codex user with the plugin installed gets this failure on every turn through the gateway. - Codex shows only
gate rejected: HTTP 422. The cause appears only in a Server traceback. - The plugin captures the prompt before the model call, so each failed turn still stored a Source.
- Only Codex and the Responses route were run. Any integration that injects prepared context into a request the gateway forwards sends the same markers.
The gateway uses one Scope. It takes the Scope only from PC_GATEWAY_DEFAULT_SCOPE; #2199 limits the first version to a single Scope. A plugin binds each workspace to its own Scope, but the gateway prepares and captures every conversation in that one Scope.
Proposal
Each part does the work whose inputs only it has:
| Part | Owns |
|---|---|
| Host plugin | Session events: startup, resume, fork, and compaction. Resolving and binding the Scope from the workspace. Tool configuration. Diagnostics shown in the host. Bootstrap context at session start. Prompt-time context and prompt capture, only where the gateway does not carry the host's model traffic. |
| Gateway | For the traffic it carries: preparing and injecting prompt-time context, the complete-request checks, replay, and capturing turns. |
| Server | Retrieval, rendering, trust wrapping, persistence, bindings, and the check rules. |
One owner per turn. When the host's model traffic goes through the gateway, the plugin neither prepares nor injects prompt-time context, and the gateway captures the turn (PC_GATEWAY_SEDIMENT=on) instead of the plugin. A plugin setting turns prompt-time recall off. For Codex it is POWERCONTEXT_CODEX_PROMPT_RECALL=false, next to the existing POWERCONTEXT_CODEX_CAPTURE_PROMPTS. The setting lives in the plugin because only the host's configuration knows, before a turn starts, where its model request will go.
The rest of the plugin keeps working behind the gateway:
- The gateway forwards Core and
/mcproutes, so its address works as the plugin's Server URL. In the run above, binding, prepare, capture, and the Codex MCP tools all went through the gateway's port. - Core's check covers only the two prepared-context markers. The bootstrap block uses
BEGIN_POWERCONTEXT_BOOTSTRAP_CONTEXT_V1, so SessionStart bootstrap is not affected. This is from the code; the run kept bootstrap off, the plugin default. - Bootstrap, including a committed Handoff, stays in the plugin until the gateway takes it on.
Plugins keep the fallback. The gateway does not carry:
- Claude Code, which uses the Messages API. docs(rfc): define Rust PowerContext Gateway #2199 lists
/gateway/v1/messagesas a later route. - Hosts signed in with a subscription account. The gateway calls the upstream with a key from its own environment.
- Setups without the gateway, which is optional and disabled by default.
There the plugin keeps preparing, injecting, and capturing as it does today.
The Scope crosses through the Server. The plugin's half already exists. At session start, the Codex plugin writes a session binding, {"integration": "codex", "kind": "session", "external_id": <session_id>}, with PUT /v1/scope-bindings, unless an explicit Scope is configured. In every recorded session, the hook's session_id was the thread-id that Codex sends and that the gateway reads as the conversation identity (#2419). The gateway's half is the first follow-up below.
Plan
Done:
- test(integrations): check the prompt-privacy, bootstrap, and transport copies #2251 and test(integrations): characterize the Claude Code and Codex hooks #2255: tests that keep the copied helpers identical, and characterization fixtures for the Claude Code and Codex hooks.
- fix(integrations): bound the recall query in Pi, OpenCode, DSH, and Bub #2252: the recall query is bounded in Pi, OpenCode, DSH, and Bub.
- fix(claude-code): run plugin hooks on the macOS system Python 3.9 #2254 and fix(codex): run the SessionStart hook when Codex forks a session #2290: the Claude Code hooks run on the macOS system Python 3.9, and the Codex SessionStart hook runs for forked sessions.
- fix(integrations): report a coded 404 as an invalid response in WorkBuddy and OpenCode #2322: WorkBuddy and OpenCode report a coded 404 as an invalid response.
- feat(opencode): add a setting that turns prompt-time recall off #2455: OpenCode's
POWERCONTEXT_OPENCODE_PROMPT_RECALLturns prompt-time recall off. - fix(integrations): report Scope resolution failures from prompt hooks #2317: the Claude Code and Codex prompt hooks report Scope resolution failures.
- refactor(integrations): generate the shared Python plugin helpers from one source #2318:
src/powercontext_integration_lifecycle/and the command that generates the 12 shared Python helper copies from it. - fix(dsh): apply the shared prompt-privacy rule to automatic recall and capture #2625: DSH's automatic recall query and prompt capture follow the shared prompt-privacy rule (
tests/fixtures/automatic_prompt_privacy.json). - refactor(integrations): generate the TypeScript transport copies from one source #2623: the TypeScript plugins' shared helpers get one source,
integrations/lifecycle/, generated by the same command as the Python copies. It starts withtransport.ts, the one helper still identical in DSH, OpenClaw, OpenCode, and Pi.
In review:
- refactor(integrations): run the Claude Code and Codex SessionStart flow from the lifecycle package #2550: SessionStart on the shared package (step 3).
- fix(openclaw): apply the shared prompt-privacy rule to automatic recall and capture #2636: OpenClaw's automatic recall query and capture follow the same rule.
- fix(integrations): give context preparation more time in Kimi Code, DSH, and Cindy #2642: Kimi Code and DSH allow 3 seconds per prepare request, and Cindy's prompt hook gives preparation the hook budget minus a capture reserve, instead of 1 second and 0.8 seconds.
- fix(dsh): apply the shared prompt-privacy rule to explicit writes #2643: DSH's explicit writes follow the shared prompt-privacy rule instead of three substring markers.
- refactor(integrations): generate the TypeScript prompt-privacy copies from one source #2644: the prompt-privacy rule in DSH, OpenCode, and Pi is generated from
integrations/lifecycle/prompt-privacy.ts. - refactor(integrations): generate the flush acknowledgement helpers from one source #2645: the OpenClaw and Pi flush acknowledgement helpers are generated from
integrations/lifecycle/flush-progress.ts. - fix(integrations): recall with the end of a long prompt in Hermes, LangChain, LangGraph, and Pydantic AI #2647: Hermes, LangChain, LangGraph, and Pydantic AI recall with the end of a long prompt, under the bound in
tests/fixtures/recall_query_bound.json. Their prompt-privacy change follows once it merges.
Next, in order:
- Codex:
POWERCONTEXT_CODEX_PROMPT_RECALL(feat(codex): add a setting that turns prompt-time recall off #2453), defaulttrue. Withfalse, the UserPromptSubmit hook sends no prepare request and injects nothing. Run with a real Codex behind the gateway, through the pass-through shim until bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420 is fixed. - Codex through the gateway, in the Codex guide once bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420 is fixed: point Codex at
/gateway/v1; setPOWERCONTEXT_CODEX_PROMPT_RECALL=falseandPOWERCONTEXT_CODEX_CAPTURE_PROMPTS=false; turn onPC_GATEWAY_SEDIMENT; setPC_GATEWAY_DEFAULT_SCOPEto the workspace's Scope; and approveprovider-defaultcache retention on the upstream target, because Codex always sendsprompt_cache_key. - SessionStart on the shared package (refactor(integrations): run the Claude Code and Codex SessionStart flow from the lifecycle package #2550): the Claude Code and Codex plugins ship the package, and the diagnostic throttle, bootstrap receipts, bounded HTTP, and the SessionStart flow move into it.
- UserPromptSubmit on the shared package: Claude Code and Codex keep this flow as the fallback, so the Scope client and the prompt flow, including the new setting, move into the package.
- Other plugins whose hosts can send model traffic to the gateway get the same setting when their gateway setup is documented.
Adapter-side trust notices, independent of the steps above: one PR per adapter, except that the five Python adapters share one PR. Trust wrapping belongs to the Server, which already puts TRUST_POLICY (src/powercontext/builtin/runtime/prepared_text.py, since #28) ahead of the historical items in every prepared context; code excerpts carry their own untrusted-data line. Each adapter drops the trust sentence it adds on top, and keeps any marker it uses to recognize its own injections. Each PR checks whether the adapter's wording says something TRUST_POLICY does not, and states how that is handled.
- Kimi Code (fix(kimi-code): drop the adapter trust notice from prompt context #2476): plain text in the UserPromptSubmit hook, no marker.
- Bub (fix(integrations): drop the Python adapters' trust notices from prompt context #2527): keeps
CONTEXT_MARKER, which_contains_context_markermatches. - DSH (fix(dsh): drop the adapter trust notice from prompt context #2507): keeps "superseding earlier PowerContext context snapshots", which is functional.
- Hermes (fix(integrations): drop the Python adapters' trust notices from prompt context #2527): keeps the
## PowerContext recalled contextheading. - LangChain (fix(integrations): drop the Python adapters' trust notices from prompt context #2527): keeps
_CONTEXT_MARKER. - LangGraph (fix(integrations): drop the Python adapters' trust notices from prompt context #2527): keeps
CONTEXT_MARKER. - OpenClaw (fix(openclaw): drop the adapter trust notice from prompt context #2508).
- OpenCode (fix(opencode): drop the adapter trust notice from prompt context #2509), after feat(opencode): add a setting that turns prompt-time recall off #2455, which changes the same plugin: keeps the
CONTEXT_PREFIXmatch that finds earlier synthetic parts. - Pi (fix(pi): drop the adapter trust notice from prompt context #2510).
- Pydantic AI (fix(integrations): drop the Python adapters' trust notices from prompt context #2527): keeps
CONTEXT_MARKERfor detection;CONTEXT_PREFIXkeeps its name and now equals the marker. - ZCode (fix(zcode): drop the adapter trust notice from prompt context #2511): keeps the
PowerContext context for this request.label, which the guide and the acceptance tests match.
Shared TypeScript helpers follow the Python ones: one source in integrations/lifecycle/, with a generated copy at each plugin's current path, so bundles and published packages stay as they are (#2623). Helpers whose copies have diverged move one at a time, each after a host parameter or a separate behavior PR settles the difference. The Kimi Code and ZCode .mjs hooks join with the first helper they share with the TypeScript plugins.
Not planned: moving each host's full lifecycle into a shared module (Hermes included).
Compatibility
- Without the new setting, every plugin behaves as it does today.
- With
POWERCONTEXT_CODEX_PROMPT_RECALL=false, the Codex plugin sends no prepare request and injects no block. Bootstrap, bindings, tools, prompt capture, and diagnostics keep their own settings. - Settings, local state, and workspace keys keep their names, paths, and derivation.
- No Server API changes.
Verification
- The characterization fixtures from test(integrations): characterize the Claude Code and Codex hooks #2255 stay unchanged with the default setting. New fixtures cover
false. - A real Codex with the plugin, the gateway, and the setting completes each turn, with one gateway prepare per message and one block in the upstream request.
- Each PR says which hosts were actually run, and whether its payloads were recorded or synthetic.
Non-goals
- Changes under
gateway/. The follow-ups below are for its owners. - A universal cross-host hook API, or a runtime dependency between installed packages.
- Changing how workspace keys are derived.
Gateway follow-ups
Observations from the run. The plugin work does not depend on them.
- Scope per conversation. The gateway could resolve the Scope with
POST /v1/scope-bindings/resolveand the session binding above, falling back toPC_GATEWAY_DEFAULT_SCOPE. No new endpoint is needed. - The error for an undeclared block. The gateway turns Core's 422 into 503
gate_pausedand logs nothing about it. Codex retries the 503 30 times per message and shows onlygate rejected: HTTP 422. A response that names the cause would point users at the fix.
Alternatives considered
- One module per language for every host's full lifecycle. Each plugin would keep carrying the prompt-time work that the gateway takes over for the hosts it serves.
- Disable the plugin's UserPromptSubmit hook in Codex's
/hooks. It needs no code, but it depends on each Codex build's hook controls, which this repository does not test. - A Server-wide
context_ownerthat plugins read. It would also silence hosts the gateway does not carry, such as Claude Code. - The gateway drops blocks it did not inject. Plugins would still prepare and capture every turn, and the gateway would silently edit client input.
- The gateway infers the owner from blocks already in the request. docs(rfc): define Rust PowerContext Gateway #2199 rules this out: a matching prompt tag does not prove host ownership. The check would also still reject the plugin's block, as the run with
PC_GATEWAY_INJECTION=offshows. - Remove prompt-time context from plugins. Hosts the gateway does not carry would lose recall.
Additional context
- Code facts are from
upstream/masterat 9c8f061: the check markers insrc/powercontext/builtin/runtime/context_check.py; the Scope, routes, and upstream key ingateway/crates/pc-gateway-app/src/ingress.rsandmain.rs; the session binding inintegrations/codex/plugins/powercontext/hooks/session_binding.pyandscripts/scope_binding.py. - The run used real Codex, Server, and gateway processes, with a recording upstream and a recording proxy in front of the gateway. I can share the scripts and recordings.
Are you willing to contribute to this feature?
- Yes, I am willing to contribute code, docs, or design feedback.
I'll do the plugin side, starting with the Codex setting. Please comment here before starting on any item, so the work isn't duplicated.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsTodo
Activity
Fengzdadi commentedon Oct 26, 2026
@PsiACE, here is the location question from the issue in concrete form, so it can be answered with a yes or no.
I'd like to start step 3 with this layout:
packages, next tosrc/powercontext_service_bootstrap. It stays out ofpowercontext.client, so it is not SDK API, is not in the Python API reference, and needs noclientextra.OK to go ahead with this layout? If you'd rather have it under
src/powercontext/client/lifecycle/, I'll use that path; the prototype already works there.Fengzdadi commentedon Oct 27, 2026
Two other directions are worth settling before step 3, together with where the Python module lives.
One language for every plugin. Nine of the 14 hosts on the automatic path run the adapter inside the host process, so the host fixes the language: Hermes, Bub, LangChain, LangGraph, and Pydantic AI are Python; Pi, OpenCode, OpenClaw, and DSH are TypeScript. Only the five command-hook hosts can choose. Claude Code, Codex, and WorkBuddy run Python hooks, and Kimi Code and ZCode run
.mjshooks. Both implementations therefore stay, and moving a command-hook host to the other language would not remove either of them. Which language each command-hook host uses can be decided per host later, by which runtime that host can rely on. The fixtures in #2255 record only what crosses the process boundary, so they could check such a port as they are.A fat client. If every plugin called one local client, there would be one implementation, and each plugin would only forward events. The costs:
The fat client and this plan don't exclude each other. Once each language has one module, a command hook could call an installed hook command that wraps that module, if setup can guarantee the command exists. I'd treat that as a possible later step, not as an alternative to this plan.
Where the Python module lives. The module is the single source of the host-side lifecycle code. In step 3 it reaches users only as copies inside plugins, and framework adapters may import it later. So it has to import with the standard library alone, run on Python 3.9 (the Claude Code copy often runs on the macOS system Python), and stay out of the SDK's public API.
src/powercontext/client/lifecycle/misses these. Importing it runspowercontext/client/__init__.py, which importshttpx. It would also be published in the Python API reference, and itsnormalize_server_urlbehaves differently from the SDK function of the same name.src/powercontext_integration_lifecycle/, meets all of them, following the precedent ofsrc/powercontext_service_bootstrap.integrations/would also meet them, but adapters could not import it from the installed package.One caveat:
powercontext-langchain,powercontext-langgraph,powercontext-pydantic-ai, andpowercontext-bubare released separately and depend onpowercontext[client]without pinning a version (Pydantic AI requires only>=0.0.3). Once an adapter imports the module, the module becomes an interface between separately released packages, aspowercontext.client.transport_policyis today. The first step-3 PR has no such consumer, so importing versus copying can be decided when an adapter moves.@PsiACE, unless you'd rather have it under
powercontext.client, or someone wants an RFC first, I'll open the first step-3 PR with the top-level package after #2255 merges: the module, the generate/check command, and the 12 generated copies. Moving it later is a path change.Fengzdadi commentedon Oct 31, 2026
Progress update.
Merged
Waiting for review
scope_not_foundis reported as an invalid response instead of a version mismatch.src/powercontext_integration_lifecycle/and the generate/check command, which writes the 12 existing helper copies. No plugin code moves.Their failing checks also fail on master 0c1dfc2, apart from a ZCode e2e case on #2317 and a Windows managed-resource smoke timeout on #2318. Neither looks related to these changes.
Ready after #2318 and #2317 merge
The rest of the Python pilot moves Claude Code and Codex onto the module in two PRs:
powercontext_lifecycle/package. The diagnostic throttle, bootstrap receipts, bounded HTTP, and the SessionStart flow move into it, and the SessionStart hooks keep only a host shell.Both leave the characterization fixtures unchanged and add shell tests built from recorded native payloads. The prompt-hook PR changes one behavior: Codex no longer skips prompt capture when recall raises an error the flow does not classify. Claude Code already captures in that case, and both integration guides say recall and capture fail independently.
With #2318 and #2317 underneath, both PRs ran on real hosts against a local Server: Claude Code 2.1.277, with its hooks on Python 3.9, and Codex 0.166.0-alpha.5.1. In Claude Code, startup, resume, fork, and compact injected the bootstrap package; in Codex, startup, resume, and fork did. Prompt recall returned a Memory that only recall could reach, and prompts were captured. With a missing Scope, both hosts showed the new
scope_resolvediagnostic and sent no prepare or capture request. With the Server stopped, the first prompt showedserver_unavailable.Not started
Reviews of #2317 and #2318 would unblock the two step-3 PRs.
[-]feat(integrations): give the automatic integration lifecycle one implementation per language[/-][+]feat(integrations): keep host plugins thin and make them work behind the gateway[/+]Fengzdadi commentedon Nov 3, 2026
I've re-scoped this issue around the gateway (#2199). On master, a host plugin and the gateway cannot both be on the model path: with the Codex plugin behind the gateway, every turn failed, and turning gateway injection off didn't help. The table is in the body.
The issue now covers three things: plugins leave prompt-time context and capture to the gateway when the host's model traffic goes through it, starting with a Codex setting; plugins keep prompt-time context as the fallback where the gateway does not carry the traffic; and the parts that plugins share are generated from one source. Moving every host's full lifecycle into a shared module is no longer planned. #2317, #2318, and #2322 are unchanged, and the Codex setting is the next PR.
@hidb4ai @jasper-yl, for awareness: the body lists two gateway-side follow-ups from the run. The plugin work doesn't depend on them.
feat(codex): add a setting that turns prompt-time recall off
feat(opencode): add a setting that turns prompt-time recall off (#2455)
feat(codex): add a setting that turns prompt-time recall off (#2453)