doc: add contract doc for rfc 1299 - #1361
Conversation
| | Outcome | Classification | | ||
| | --- | --- | | ||
| | `authentication_failed` | HTTP 401. | | ||
| | `version_mismatch` | HTTP 404, normally an incompatible or missing endpoint. | |
There was a problem hiding this comment.
[P1] This status-only mapping is not valid for every operation listed above. Direct tools can legitimately receive 404 NotFound for a missing Memory entry or citation, while 409 and 422 are valid conflict and validation responses; classifying them as version_mismatch or invalid_response would emit a misleading diagnostic alongside the correct tool error. Please scope version_mismatch to a missing compatibility or availability endpoint (or define operation-specific domain-error precedence), preserve not_found/conflict/invalid_request for direct operations, and cover those cases in the contract tests.
| | Plugin | Channel | Component prefix | | ||
| | --- | --- | --- | | ||
| | Codex | Hook `stderr` | `powercontext.codex.recall` | | ||
| | Claude Code | Hook `stderr` | `powercontext.claude_code.recall` | |
There was a problem hiding this comment.
[P1] A successful Claude Code UserPromptSubmit hook does not render stderr to the user. The implementation in #1360 exits 0 and writes this event only to stderr, so the documented warning remains silent. Please emit the content-free event via the top-level systemMessage in the hook stdout JSON (keeping stderr only for debugging if useful), and add a host-level test that verifies the warning is actually rendered.
| captured text, recalled text, response bodies, or stack traces. | ||
|
|
||
| Repeated failures MUST have bounded presentation. Long-lived plugins SHOULD deduplicate by `outcome` for 60 seconds. | ||
| Short-lived hooks MAY deduplicate within one invocation, but MUST NOT emit an unbounded stream for one failure. The |
There was a problem hiding this comment.
[P2] Deduplicating only within one short-lived hook invocation still allows one identical warning on every prompt forever, which is exactly the unbounded behavior this requirement rules out. Codex and Claude start a fresh hook process per prompt, so invocation-local state cannot enforce a cooldown across turns. Please require a cross-invocation or host-level throttle (or another persistent bounded presentation mechanism) and test two separate hook invocations inside the documented cooldown window.
2 participants
Which issue or RFC does this PR close?
This PR does not close #1298. It documents the contract from RFC PR #1299, which tracks issue #1298.
Rationale for this change
The host-visible integration diagnostics contract needs a single documented reference so plugin implementations and reviews use the same failure classifications, output format, privacy rules, fail-open behavior, and deduplication expectations.
What changes are included in this PR?
docs/en/development/plugin-contract.mddocs/zh/development/plugin-contract.mdzensical.toml.authentication_failed,version_mismatch,server_unavailable, andinvalid_responseAre there any user-facing changes?
Documentation-only change. There are no runtime, API, persistence-format, or migration changes.
How was this change tested?
The strict documentation build completed successfully with no issues.
AI usage statement
This documentation was prepared with OpenAI Codex using the GPT-5 model. The final scope, wording, links, and documentation build were reviewed in the repository.