Skip to content

feat(integrations): gate fork/subagent write channels at the host boundary and close the capability-matrix gap #2560

Open

Description

@AlexStocks

Start Here and Theme

When a host forks a session or delegates to a subagent, PowerContext's Hermes provider decides whether to write memory by reading agent_context inside its own initialize. That is an honour-system gate: it only works if every write channel and every in-process provider checks the flag correctly. Hermes found this the hard way — commit 16c6bbfd1c states that "most bundled providers ... ignore it" — and then found two more holes: making fork sessions inherit providers to satisfy a checkpoint gate also woke the ordinary write channels (f02ba87b8c), and the built-in MEMORY.md / USER.md store is not a provider at all, so a host-level scope gate missed it (14525b539c).

Today: the fork/suppress decision lives at integrations/hermes/plugins/powercontext/provider.py:412-415; #2438 / #2452 already added withheld-data guards and real-MemoryManager conformance tests, but those tests do not cover fork/subagent write channels or non-provider channels. After this task: the host-side boundary has one explicit admission decision for "write / recall / diagnostic output" that is separate from the minimum capability a checkpoint needs, and the capability matrix states what was actually verified.

This is a guardrail and evidence task, not a withheld-data leak fix — but it is not merely a hypothetical risk either. On the inspected baseline, _automatic_writes_suppressed is called from only two places; on_session_end and on_pre_compress have no such check. With capture_pre_compress=true (default false), a non-primary context's transcript reaches capture_content through a real, non-default-configuration path. No withheld-data leak has been demonstrated. The reachable gap is automatic write suppression on two channels, and the design must treat it at that severity.

Theme: Gate fork/subagent write and diagnostic channels at the host boundary, including non-provider channels, without waking ordinary capture just to satisfy a checkpoint — and keep the capability matrix honest about what the tests prove.

Contribution to the overall goal (2026-11-09 cross-system memory review): closes the one part of the earlier "host egress and checkpoint acceptance" item that #2438 / #2452 deliberately left open.

Observable behavior that must appear:

  • A fork/delegate turn produces no capture_content, flush, recall injection, or diagnostic artifact containing fork harness prompts or withheld sentinels.
  • The minimum capability required for a required checkpoint still works; enabling it does not re-enable ordinary writes.
  • A late task after a Scope switch stays bound to its original Scope.
  • A failed required checkpoint leaves the host's original history intact.
  • integrations/capabilities.toml only claims a capability that the conformance evidence actually establishes.

Invariants to keep:

Typical drift: adding a second agent_context check inside each adapter method instead of one host-side decision; granting full write access so a checkpoint passes; declaring pre_compaction supported because a provider method exists; using one sentinel for both "withheld" and "secret" so the secret redactor masks the projection regression; or changing Hermes host source code.

Contract version: 2026-11-09. Inspected baseline: remote master 2291237a7809410ea0dc8f19f2de149573af8378 (2026-11-09 20:13 +0800), checked 2026-11-09 20:40 +0800. Freeze this Issue body's hash at kickoff.

Background and Evidence

Verified on the baseline above:

  • integrations/hermes/plugins/powercontext/provider.py:113 defines _NON_PRIMARY_AGENT_CONTEXTS = frozenset({"cron", "flush", "subagent"}); :404-415 initialize reads agent_context and platform and sets the provider's own write posture. No _fork or display_metadata handling exists in that file.
  • Write / egress entry points in the same file: sync_turn (:917), on_session_end (:975), on_pre_compress (:1037), recall_status (:903).
  • integrations/capabilities.toml:947,961,975,989 sets [integrations.lifecycle.pre_compaction] mode = "unsupported" for several hosts; :686, :876, :1000 list pre_compaction_capture among capabilities. A provider method or a direct callback is not sufficient to change that declaration (test(hermes): guard withheld-data boundaries and qualify real-host conformance #2438 states this explicitly).
  • Conformance harness added by test(hermes): guard withheld data and qualify real-host conformance #2452: tests/integration_conformance/hermes/ — README.md, compaction.py, conftest.py, model_stub.py, run_manager.py, support.py, test_isolation.py, test_real_manager.py. Its README honestly limits the setup to "real host code + stub models, not live-model end-to-end acceptance".
  • Verified gap, not a potential risk: _automatic_writes_suppressed is defined at provider.py:911 and called only at :925 (sync_turn) and :1180 (memory mirror). on_session_end (:975) and on_pre_compress (:1037) contain no suppression check. capture_pre_compress defaults to "false" (:370-372); when enabled, on_pre_compress stores the transcript without a primary-context gate. This is a reachable path under a non-default configuration.
  • Existing fork signal: initialize already reads parent_session_id (:411) and passes it to the client (:462); the entry points at :1014, :1021, :1030 also carry it. A host-side gate must use the signals the host actually sends, not invent agent_context == "fork".
  • Harness gap: the three fork hits in the conformance directory are Skill-import patterns, not session forks. No scenario currently constructs a fork/delegate turn.
  • Earlier guards: test(hermes): guard withheld-data boundaries and qualify real-host conformance #2438 (closed) added withheld-data boundary regressions and qualified real-host conformance; test(hermes): guard withheld data and qualify real-host conformance #2452 (f5a4f30) added the real MemoryManager acceptance. Both are the baseline to extend, not to duplicate.
  • External, read-only evidence: Hermes agent/memory_manager.py:261 _fork_turn_hooks_suppressed() and the three commits named above, at 466591fe65d0....

Parent requirement: the 2026-11-09 cross-system memory review (P1). No local file or prior conversation is needed to execute this task.

Not in scope: the Receipt diagnostics work in #2436, capture coverage (#2451), source evidence declarations (#2004), and any Server-side authorization change.

Fork input contract (freeze at kickoff)

The acceptance row "Fork write channels" is under-specified unless the harness fixes its inputs. Before the first implementation slice, the coding agent and the independent verification agent must agree and record:

  • The agent_context value(s) that denote a fork / delegate turn, taken from what the Hermes host actually passes — do not invent a new token.
  • parent_session_id presence and value, and platform.
  • Which configuration switches are on (capture_pre_compress, capture_turns, flush_on_session_end, evaluation_trace, automatic writes).
  • Which entry points are exercised (sync_turn, on_session_end, on_pre_compress, memory mirror) and in what order.

A different implementation must not be able to pass the acceptance table by choosing a narrower fork definition. Record the contract and its hash with the checkpoint artifacts.

Baseline and Dependencies

Allowed

  • integrations/hermes/plugins/powercontext/provider.py and its helpers.py — introduce one explicit host-side admission decision covering write, recall, and diagnostic output, separate from the minimum checkpoint capability.
  • tests/integration_conformance/hermes/ — add fork/delegate and non-provider-channel scenarios, distinct sentinel types, Scope-switch lateness, and required-checkpoint failure cases. Reuse the existing run_manager.py / model_stub.py fixtures where possible.
  • integrations/capabilities.toml — only if the new evidence actually establishes a lifecycle capability; otherwise leave it as unsupported and say so in the report.
  • docs/en/docs/integrations/hermes.md and docs/zh/docs/integrations/hermes.md — keep the existing three-part data-direction disclosure and update the capability/limitation wording in both locales.
  • Local edits, focused verification, and reporting are authorized. Commits, pushes, PR creation, merges, and host-side comments require separate authorization.

Prohibited

  • Changing the Server, openapi/powercontext.yaml, generated clients, public DTOs, or the Receipt shape.
  • Inventing a new agent_context token for forks when the host already supplies parent_session_id, or deciding fork identity from transcript content.
  • Modifying Hermes host source code (agent/memory_manager.py, message_metadata.py, etc.) — those are read-only references.
  • Serializing whole message dicts, display_metadata, or any unknown host field into a Source, trace, or diagnostic artifact.
  • Declaring pre_compaction supported on the strength of a provider method, a direct callback, or a stub-model test alone.
  • Using one sentinel for both withheld data and secret material; the existing secret handling must keep its own contract and be asserted separately.
  • Weakening an existing assertion, replacing the real MemoryManager with a mock, silently skipping a scenario, or describing a stub-model run as live-model acceptance.
  • Duplicating the test(hermes): guard withheld-data boundaries and qualify real-host conformance #2438 / test(hermes): guard withheld data and qualify real-host conformance #2452 tests instead of extending them.

Verification and Acceptance

Scenario / risk Input and steps Expected result Environment Passing evidence
Fork write channels Run a fork/delegate turn through the real MemoryManager with a fork-harness sentinel Sentinel absent from capture_content, flush, recall injection, checkpoint, and diagnostic artifacts conformance harness test + artifact snapshot
Withheld vs secret separation Inject a non-secret withheld sentinel, an ordinary allowed user/assistant body, and a secret-handling sample Withheld sentinel absent; ordinary body still captured; secret handling unchanged; assertions do not pass because nothing was captured conformance harness test
Non-provider channel Exercise a built-in/non-provider store path during a gated fork turn Gate covers it; no user notes or profile content reaches the delegate child prompt conformance harness test
Checkpoint minimum capability Enable only the capability a required checkpoint needs Checkpoint succeeds; ordinary write/recall channels remain suppressed conformance harness test
Unknown host field Add an unknown field to the input message Not propagated to Source or trace focused test test
Persistence After an accepted capture, restart and read back the same Scope/Source ID Persisted material contains no withheld/fork sentinel and does contain the allowed body real Server HTTP/SQLite test, not FakeClient.calls alone
Scope-switch lateness Start a task, switch Scope, let the late task finish Task stays bound to its original Scope conformance harness test
Failed required checkpoint Force a required-checkpoint failure Host keeps its original history; no partial capture committed conformance harness test
Capability matrix honesty Compare capabilities.toml with the evidence No capability claimed beyond what the conformance evidence establishes; otherwise unsupported retained doc review diff + report

Necessary checks, from the repository root:

uv run --locked pytest tests/integration_conformance/hermes -q
uv run --locked pytest tests/integrations/test_hermes_provider.py -q
uv run --locked ruff check <changed paths>
uv run --locked ruff format --check <changed paths>
git diff --check
  • Bug baseline: no leak has been demonstrated, so no "failing baseline" pair is required. The guard tests must nevertheless fail if the projection is widened — demonstrate this once with a temporary, clearly marked probe and remove it from the deliverable.
  • Mock/real boundary: model_stub.py proves local handling with real host code; it does not prove a live model or an automatic/gateway lifecycle. The real Server HTTP/SQLite case proves persistence, not host behavior.
  • Missing environment: report BLOCKED with the command and output; never silently skip a required scenario.

Two-Agent Checkpoints and Delivery

One coding agent implements; one independent verification agent reads and checks in a separate context.

  • Kickoff: minimal plan, frozen contract-body hash, current SHA, actual file ownership (including fix(integrations): drop the Python adapters' trust notices from prompt context #2527), and the sentinel strategy. The verification agent confirms withheld and secret values are distinct.
  • First verifiable slice: the host-side admission decision plus one fork-channel regression; the verification agent reads the actual diff and confirms ordinary capture is not simply disabled everywhere.
  • Delivery: full scenario matrix, persistence case, capability-matrix decision, bilingual docs, and the final snapshot.

Each handoff carries the baseline SHA, diff, new-file inventory, contract-body hash, environment, commands, and raw-output locations. Direction and correctness are reported separately with CONTINUE / CORRECT / HOLD. HOLD is correct when a capability declaration would require a change to the Server, a public contract, or the Hermes host itself.

Delivery and Stop Conditions

Deliverables: the guarded provider, extended conformance scenarios, a capability-matrix decision with evidence, bilingual documentation, and a short report. Save local evidence under untracked .powercontext/task-ISSUE/checkpoints/; do not commit runtime logs or real private bodies.

Completion: every acceptance row is reported PASS / FAIL / BLOCKED / NOT_RUN against the final snapshot; the existing #2438 / #2452 assertions still pass; no capability is overstated.

Stop and report rather than concluding if:

  • Closing a fork channel would require a Server-side or public-contract change.
  • The real MemoryManager path cannot run in the available environment — report BLOCKED, do not substitute a mock and call it conformance.
  • A capability claim depends on a live model or an automatic/gateway lifecycle that this harness does not establish.

Publication of this Issue authorizes local implementation and verification only. It does not authorize an implementation PR, a commit, or a push.

Related tasks from the same review

This Issue is one of three tasks created from the 2026-11-09 cross-system memory review (Hermes 466591fe, Codex 8703d32b, PowerContext 2291237a). The other two are #2559 and #2561. They are not hard dependencies: each has its own baseline, file ownership and stop conditions, and may run in parallel where the stated start conditions allow.

Deliberately not turned into new Issues, after checking remote master and existing Issues:

Activity

  1. Oxidaner commented on Nov 9, 2026

    @Oxidaner
    Contributor

    please assign me

  2. AlexStocks commented on Nov 9, 2026

    @AlexStocks
    ContributorAuthor

    please assign me

    done

  3. tonydzi commented on Nov 12, 2026

    @tonydzi

    One data point from running a fleet of coding agents on the "honour-system gate vs host-boundary gate" question, in case it helps the design.

    We had a written rule ("never archive a session you don't own") in the always-loaded instructions. It held in most runs and failed in the others, which is the same shape as providers that "ignore" agent_context. What closed it was a PreToolUse hook that blocks the call before it reaches the tool, so the decision lives in one place and no tool has to cooperate.

    Second thing, about the capability matrix: in the same incident 29 archive calls returned "Archived session ..." while the on-disk flag stayed isArchived: false. So a tool saying "done" was not evidence of the effect. For capabilities.toml that suggests the claim should point at a check on the consumer side (what was actually written or withheld), not at the provider returning without error. Your invariant "stub-model run is never described as live acceptance" is the same idea.

    Limits: this is one fleet, and our gate covers tool calls, not the on_session_end / on_pre_compress paths you list, so I can't say how a host-level gate behaves there.

  4. Oxidaner commented on Nov 12, 2026

    @Oxidaner
    Contributor

    @tonydzi @AlexStocks The results of ordinary delegated tasks are returned to the main agent, which absorbs and summarizes them before saving, so there is no need to store the sub-agent’s execution process again.
    My recommendation:

    • Sub-agent: Disable automatic saving, retrieval, and evaluation records to avoid storing execution instructions as long-term memory.
    • Main agent: Save, retrieve, and compress normally; after receiving the sub-agent’s results, it can save the final conclusion.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions