@passioncode-ai/fabric-agent-adapter 0.34.1 → 0.35.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.35.1 - 2026-10-17
+
+### Added
+
+- **`creating-fabric-agents` → `references/resilience-and-autonomy.md`**: the rules that kept about twenty production
+  agents working through limits, model errors and restarts, from their retrospectives of 2026-10-17 — limits as
+  pauses and resume-first workers, an acceptance parser per model call, cross-vendor fallbacks and checkers, spend as
+  a persisted ledger with idempotency keys, decisions recorded instead of asked, tests watched failing, run ownership,
+  owner-tagged resources and secrets kept out of every child's environment. The skill reads it before the first
+  stage that calls a model or spends money and reports its checklist.
+
+### Fixed
+
+- **The Hermes native adapter dropped a helper's answer** (FAA-51): a helper that exits without reading its input broke
+  the pipe while the payload was written, and the broken pipe discarded the helper's output. It no longer does.
+- **`test/validate.py` validated other checkouts as this tree** (FAA-50): its walks entered `.worktrees/` (git
+  worktrees of this repository, git-ignored), so the main checkout failed the pin check — 442 errors — whenever a
+  worktree of another branch sat beside it. Every walk now skips `.git` and `.worktrees`.
+- **The tests left directories behind** (FAA-50): the Node tests made their temporary directories with `mkdtempSync`
+  and removed none, and five Python tests used `mkdtemp` without a cleanup, so every run left about 40 directories in
+  the system's temp folder. The Node tests take theirs from `test/temp-dir.mjs`, removed when the process exits; the
+  Python tests register `addCleanup`. A full run now leaves none.
+- **The session hooks' spool grew without bound** (FAA-50): a session folder was removed only when its worker delivered
+  the session's end, so a failed delivery or a session that ended without SessionEnd left its folder forever. The next
+  spooling hook now removes folders untouched for 7 days, never its own.
+- **`install-host-hooks --host codex --remove`** names the SessionStart hook groups after ours that it moves: Codex
+  keys a hook's trust by its position, and asks the person to approve those again in `/hooks` (FAA-49).
+
+## 0.35.0 - 2026-10-16
+
+### Fixed
+
+- Codex SessionStart emits explicit JSON. Its preamble began with `[fabric-agent-adapter]`, which Codex treats as JSON-looking output and rejected with `hook returned invalid session start JSON output`.
+- The Codex hook installer updates a stale owned command while preserving its matcher, timeout and unrelated hooks; ambiguous duplicate entries are refused.
+
+### Added
+
+- Native bounded context adapters for Hermes prompt sections, OpenCode system transforms, OpenClaw `before_prompt_build`, and Pi `before_agent_start`; no model calls or lifecycle enrollment from these hooks.
+- Dry-run native installers with source preflight, config hash fences, managed-file checks and preservation of unrelated settings and explicit OpenClaw denials. Hermes opt-in uses its own CLI.
+- Optional native loader probes, negative permission and timeout tests, and a sourced capability survey of all 30 Switchboard hosts plus Tabby. Native context loading is separate from live Fabric admission.
+
 ## 0.34.1 - 2026-10-15
 
 A review of 0.33.0 and 0.34.0 found the profile and route rules disagreeing with the contract on JSON they never met in

package/README.md

@@ -40,7 +40,10 @@ and the board's unread count; UserPromptSubmit adds one line only when that coun
 session left claimed. Stop, UserPromptSubmit and SessionEnd act only when the running Fabric advertises
 `session-hooks/1`. All are silent in a session Fabric launched, never block the session, read no token and always
 exit 0. `fabric_session.py watch-mail` waits for board mail under a background watcher, and `install-host-hooks
---host codex|kimi` adds the session-start preamble to Codex or Kimi Code (a dry run unless `--apply`). The
+--host codex|kimi|hermes|opencode|openclaw|pi` installs each host's native context bridge (dry run unless `--apply`).
+Codex receives structured SessionStart JSON; Hermes, OpenCode, OpenClaw and Pi use native plugin APIs.
+See the [native host matrix](plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md)
+for activation, reload and verification limits. The
 [hooks reference](plugins/fabric-agent-adapter/skills/working-with-fabric/references/session-hooks.md) lists what
 they need from Fabric; the [board reference](plugins/fabric-agent-adapter/skills/working-with-fabric/references/project-board.md)
 is the board-first workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.34.1",
+  "version": "0.35.1",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.34.1",
+  "version": "0.35.1",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.34.1"
+  version: "0.35.1"
   contract-version: "0.1.0"
   contract-commit: "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"
 ---

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -18,7 +18,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.34.1"
+  version: "0.35.1"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.34.1"
+  version: "0.35.1"
   contract-version: "0.1.0"
   contract-commit: "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"
 ---
@@ -201,6 +201,15 @@ the pinned `schemas/operator-channel-status.schema.json`; the channel's runtime
 probe rule here yet, so report them `NOT_RUN`. An agent with neither stops nor notify
 events skips this step.
 
+## Resilience and autonomy
+
+Before the first stage that calls a model or spends money, read
+[resilience and autonomy](references/resilience-and-autonomy.md) and design its answers in:
+a limit pauses and resumes, every model answer passes the call site's own acceptance, fallbacks
+and checkers cross vendors, spend is a persisted ledger with idempotency keys, open questions
+become recorded decisions, and every fix has a test seen failing. Report its checklist with a
+file and a test per line, or `NOT_RUN` where the agent has no such stage.
+
 ## Completion format
 
 Report: capability, consumer, profile with the step-0 grill answers; the knowledge pack

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/resilience-and-autonomy.md

@@ -0,0 +1,207 @@
+# Resilience and autonomy — what kept agents working
+
+Read when designing an agent's loop, its model calls, its spend and its stops — before the first
+stage that calls a model or spends money. These rules come from a retrospective of about twenty
+production agents (2026-10-17): each rule names the failure that taught it, generalized, and the
+mechanism that held after the fix. Every rule is cheaper to build in than to retrofit.
+
+## Contents
+
+- Limits are pauses
+- Model answers are untrusted until accepted
+- Money is a ledger
+- Autonomy: decide, record, continue
+- Verification you can believe
+- Operations that survive restarts
+- Secrets and confinement
+- Checklist
+
+## Limits are pauses
+
+1. **A provider or subscription limit pauses the job; it never fails it.** Store a typed pause
+   (`quota_exhausted`, `retryable: true`, the reset time when known) and resume from the same
+   stage. Failing it cost callers whole jobs and resubmits.
+2. **Resume first.** Every worker reads its own state — checkpoint, worktree, branches, open
+   pull requests, notes — before it acts, and continues from there. Relaunching from scratch
+   after a limit recreated work over committed work and re-issued credentials already held.
+3. **A silent worker is a limit until proven otherwise.** A watcher that sees no progress for N
+   minutes, or limit text in the last output, resumes the run with the *same* run id.
+4. **Keep prompt cache keys stable across a resume.** One changed argument that every prompt
+   carries (today's date) re-keyed a finished stage and paid for it again.
+5. **Count only the job's own failures toward its retry limit.** A lost lease, a busy lock or a
+   provider outage is bounded by a time budget instead; five infrastructure stops a day ended a
+   healthy phase as FAILED.
+6. **Match concurrency to the account's rate, and cool down after a 429** per provider door: ten
+   parallel workers met a 429 about hourly and each lost a whole batch; three to five heavy ones,
+   resumed in batches, did not. A "busy" or "still starting" dependency is retried a bounded number
+   of times with spacing (a handful, seconds apart, only on refusals classified as transient) —
+   never once, never forever.
+7. **Inside a fallback chain, do not retry a provider that answered 429 or timed out** — move to
+   the next one. Retries there stalled a waiting user. Stagger many resumes; bound each worker's
+   working set (a narrow time window, a prefix), so one stop does not become a burst.
+
+## Model answers are untrusted until accepted
+
+1. **"Answered" is not "usable".** Each call site has its own `accept(text)` — the parser the
+   result must pass. Empty content, a refusal, a truncation (`finish_reason: length`) or an
+   unparseable answer is a failure, and only an accepted answer may be cached. A cached
+   unreadable answer once served "0 labelled" for hours.
+2. **Fallbacks cross vendors.** A chain is an ordered list of models from different vendors; a
+   same-vendor fallback refuses the same inputs. Build the chain where a test can refuse a lane
+   with no other-vendor route, and act on a new fallback only after measuring it.
+3. **The checker is never the drafter's vendor.** Choose it per turn from the model that
+   *actually* drafted (a fallback may have), in the router, not in configuration. No checker
+   left, or a checker outage, means hold or stay silent — never ship unchecked.
+4. **Size the output budget for the answer, not the input.** Reasoning tokens eat `max_tokens`:
+   a judge capped at 800 tokens returned no JSON in 8 of 14 calls. Give judges room or turn
+   reasoning off for that route; on `length`, retry once with a larger cap.
+5. **Run code checks before model checks**, and degrade to a fixed safe reply with a reason code.
+6. **A model's word verifies nothing.** A fact is verified by stored source text (or two truly
+   independent sources); an effect by the system of record it lands in — never by the page, a
+   flag the model set, or its "done".
+7. **A coding agent runs only on a model it knows.** One CLI agent on an unfamiliar vendor's model
+   read its instructions and ended its turn with nothing written; measure each (agent, model)
+   pair live before making it a default.
+8. **Pin what the agent says about itself.** A short block of true facts (what it can see, its
+   pipeline, its limits) lives in code; a test fails when a fact drifts. Forbid promises the
+   pipeline cannot keep.
+
+## Money is a ledger
+
+1. **Unknown is unknown, never zero** — in cost, in verdicts, in health — and nothing acts on it.
+   A missing price is a high estimate, a missing field is `NOT_RUN`, never a pass; a probe that
+   timed out is "unreadable", not "credential rejected"; a cooldown that could not be read is not
+   "never sent". An owner's refusal inside a successful response (`ok: false` over a 200) is a
+   refusal, never an empty result.
+2. **Persist the attempt before dispatch** — its route and a hash of its prompt — and finalize it
+   in `finally`; spend is Σ actual + Σ estimate for attempts without an actual. In-memory counters
+   reset on every resume. A call that broke before the provider answered is reconciled against
+   the provider's own history by that route and hash, never guessed; one provider request id
+   belongs to exactly one ledger row.
+3. **Check the cap before every HTTP attempt, retries included**, with one stop rule; record the
+   provider's own reported cost per call; count reserved or held tokens as spent.
+4. **A resend of an unknown outcome reuses its idempotency key — or does not happen.** Derive
+   keys from the intent (action and entity, or run and step), never from a clock or a random
+   value, and make them unique in storage: time-and-random keys let redelivered requests charge
+   again. A write whose effect is uncertain stops as `outcome_unknown`; a new key there pays twice.
+5. **A client error at submit is a rejection, not a lost task.** Settle it with known usage (zero
+   if none), release the reserved money in the same transaction, and never resend the identical
+   request; a 4xx while polling is still a lost task.
+6. **A failed outer job cancels the paid work it started**, and a cancel is a row the worker reads
+   at every claim and checkpoint — never an in-memory flag that a restart forgets.
+7. **Reuse what was paid for.** A restarted stage looks up the job's successful call with the
+   same route, prompt version and inputs before calling again (one restart made 117 paid calls
+   where 49 sufficed). Cache keys are content plus definition, never an identity alone.
+8. **Deny spending tools by enumerated name, and test the list** — a provider's newer tools were
+   missing from a deny list while older ones were denied.
+
+## Autonomy: decide, record, continue
+
+1. **An open question is a decision to make.** Decide from the recorded decisions, then the
+   goal, then the safest reversible option; write the decision and its source where the work
+   lives; batch the questions only a person can answer (sign-in, consent, payment, a typed
+   secret) and keep working around them.
+2. **Nothing in a user's path waits for a human approval.** Send now or not at all; when unsure,
+   say so, open a recorded question, and answer again automatically when the knowledge changes.
+   Drafts awaiting approval waited for days.
+3. **Every wait lives in durable storage**, rebuilt on start from a "debt" query — timers in
+   process memory died with every restart. A wait that must outlive a session (a credential that
+   has not landed yet) is an operating-system job, not a session's background task.
+4. **Stop at the third round.** Tuning wording or patching one heuristic a third time means
+   splitting the change or replacing the mechanism with one invariant and a property test.
+   Write a review's exit criterion before its rounds start, and block only on what breaks a
+   documented promise; the rest becomes a board row with its evidence.
+5. **Find the real cause before telling a person what to do** — a full disk once read as "the
+   service stopped" while the service was healthy; check free space and the service's own health
+   first.
+6. **Background chores never hold a finished command open**, unattended runs skip them, and an
+   unattended `--yes` never reverses a "no" a person saved.
+
+## Verification you can believe
+
+1. **A test counts once it was watched failing against a planted defect**; a mutation battery
+   asserts its own reach ("no tests ran" is not "all plants survived"). Exercise every guard
+   with a must-catch and a must-pass case.
+2. **Write expectations out; never compute them from the code under test**, and run a reference
+   function and its schema on the same inputs in one test — the most common defect a first reading
+   found was a function returning what its own schema refuses. A wall-clock bound sits far above a
+   loaded machine and far below the defect it guards.
+3. **Test against the real deployed instance behind its platform**, not a sample the same run
+   wrote: a probe passed the shipped sample and failed the first real service behind a router.
+4. **After each wave, three blind readings** — the changed units, everything that reaches them,
+   and the documented behaviour — then one fix round. Green suites hid six to ten real breaks.
+5. **Read a gate's exit code directly**, never through a pipe in the same command (`| tail` hid a
+   failed gate as success): write the output to a file, take the status, then read the file.
+6. **"Could not measure" is its own outcome.** An overloaded machine makes a gate refuse, and a
+   timeout under load is unmeasured, not failed or passed.
+7. **Measure noise before calling a regression**; release a retrieval change only with zero new
+   confident wrong answers against the previous version.
+8. **Compute a status from the whole group**, never incrementally; verify a release by the
+   commit it serves, from a fresh checkout of that commit.
+9. **Probe live after every deploy on every consumer channel**, not the default one; read the
+   nightly full-suite result first when resuming work, and release from a full local run, not a
+   selected subset.
+10. **Read an external contract from its raw documentation or a recorded live snapshot**, never
+   from a summarising fetch; fail closed on a field nobody documented.
+
+## Operations that survive restarts
+
+1. **One owner per run, named.** Only the holder of the run's lock changes its lifecycle, and each
+   concurrent worker has its own identity; a refused claim names the run that holds the task, never
+   a guessed race against a lease that lapsed long ago; a copy that a
+   supervisor started backs off on a held lock instead of exiting into a respawn loop. A failed
+   lease renewal is not a lost lease — stop only when the remaining margin runs out.
+2. **Health treats "never finished" as a fault.** Age each phase from its last completion; a
+   phase that only ever yielded looked healthy for fifteen days.
+3. **Everything a run creates carries its owner** (run id, pid); the next start sweeps what a dead
+   owner left — markers, test databases, temp roots, container volumes. Nothing a long job needs
+   lives in a temp directory; a cleaner removed a test database mid-deploy.
+4. **Check disk and load before heavy work**, and serialize heavy suites behind a lock held for
+   the whole run. A disk cleanup never deletes files version control tracks.
+5. **State that must survive a restart or a second instance lives in the shared store**, never in
+   process memory or on one instance's disk; a per-process cache is a cache with a TTL.
+6. **Every scheduled job leaves a trace when it dies, stalls or never starts**: a heartbeat at the
+   start of each tick, a queryable error row, re-arming in `finally`, an alert when quiet for two
+   intervals. Serialize every use of a connection threads share, reads included.
+7. **Bound every wait on a shared lock and survive a lost connection.** A lock timeout (a few
+   seconds) answers a retryable "busy", never a crash or a deadlock; every pooled connection has
+   an error listener, and readiness reports the store while liveness reports the process, so a
+   database blip takes the instance out of traffic instead of restarting it.
+8. **Every accumulating output has a cap in the code that writes it** — logs, receipts, caches —
+   with both bounds tested.
+9. **Name the account and context on every cloud CLI call** and verify the account before a write;
+   a saved default context once pointed a correct token at another team.
+10. **Log by error name and code**, never a driver's raw message, which can carry connection
+   details. A failed command logs its cause — deadline, signal, exit code, missing program — never a
+   bare "command failed"; a watched dependency logs once when it fails and once when it recovers,
+   never on every poll.
+11. **Admit work only when the machine can carry it** — free disk, swap, a cap on concurrent
+   sessions — and say why when you defer.
+
+## Secrets and confinement
+
+1. **A secret never enters an environment, argv, URL or log a child can read.** Hand it over a
+   pipe or file descriptor, or through a vault runner per command; never print a configuration
+   dump, and never filter one yourself.
+2. **Confine what an agent runs by the operating system**, per run (filesystem, network, ports),
+   and treat prompt rules and command guards as tripwires, not boundaries.
+3. **Fail closed.** When a reduced view or a scope cannot be built, answer an error, never the
+   wider view; a new matching rule fires only when every neighbouring input is on its allow-list.
+4. **Run the private-name gate chained before every public push** (`<gate> && git push`), not only
+   before merge: a `;` once let a private path reach a public branch.
+5. **Freeze every input at acceptance**, nested references included: copy it by hash and work on
+   the copy, so a file swapped between acceptance and use is never read.
+6. **Treat what a run wrote as untrusted** before the service copies, reads or renders it: a
+   regular file whose real path is inside the run's own tree.
+7. **An artefact missing a secret refuses to start**, never runs unauthenticated: validation rejects
+   placeholder-shaped values, and a test renders the configuration without the value and expects
+   an error.
+8. **Widen an access configuration first, code second**, so nothing is over-scoped even briefly.
+
+## Checklist
+
+Before the first release, answer each with a file and a test: where a limit pauses and resumes;
+what `accept` each model call has; which vendors its fallback and checker use; where the attempt
+ledger and idempotency keys live; what happens to an unknown outcome; which waits are durable;
+who owns the run lock; what the next start sweeps; how a cancel reaches paid inner work; which
+outputs are capped; how a secret reaches a child; which test was seen failing for each fix.

package/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -16,10 +16,10 @@ compatibility: >-
   Needs the Fabric desktop app (0.4.0 or later for fabric-mcp and the fabric_work tools) and an MCP client.
   The status script needs Python 3.9+ (3.11+ to edit Kimi Code's config.toml). Starting Fabric needs the
   local-lifecycle MCP server; without it the person opens Fabric. The full session hooks run in Claude Code from
-  this plugin; Codex and Kimi Code get the session-start preamble hook on the person's consent.
+  this plugin; Codex/Kimi use command hooks; Hermes/OpenCode/OpenClaw/Pi use native context plugins after opt-in.
 metadata:
   author: PassionCode.ai
-  version: "0.34.1"
+  version: "0.35.1"
 ---
 
 # Working with Fabric
@@ -202,17 +202,19 @@ Never tell the person a call failed or succeeded when its outcome is unknown.
 ## Codex, Kimi Code and other agents
 
 Register with the agent's own CLI (Step 2). They cannot rejoin their Fabric session from a hook yet, so they get one
-hook only: the session-start preamble, which the person adds on consent. Show the edit first, then apply it when the
-person agrees:
+context bridge only. Inspect its dry run, then apply within the person's existing authorization:
 
 ```bash
-python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host codex   # or kimi; a dry run, writes nothing
+python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host codex   # kimi, hermes, opencode, openclaw or pi; dry run
 python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host codex --apply --expect-sha256 <digest>
 ```
 
 It edits `~/.codex/hooks.json` (`hooks.SessionStart`) or appends one `[[hooks]]` table to `~/.kimi-code/config.toml`,
 backs the file up first, refuses a file of another shape or one that changed since the dry run, and `--remove` takes
-it out again. Never edit those files by hand for the person. Without the hook, put the preamble into the first prompt
+it out again. Hermes/OpenCode/OpenClaw/Pi use their native plugin loaders, not Claude hook JSON.
+Hermes also needs `hermes plugins enable fabric-agent-adapter`; removal uses `hermes plugins disable fabric-agent-adapter`.
+Read [native host hooks](references/native-host-hooks.md) for exact paths, permission behavior and verification.
+Registration and a loaded hook do not prove live Fabric admission. Never edit those files by hand for the person. Without the hook, put the preamble into the first prompt
 yourself: "Call `fabric_whoami` first; `com.status` and `com.list`; `fabric_work_list`, then `fabric_work_claim`,
 before you start; `fabric_work_release` when you stop." Without an MCP client at all there is no way in: say so,
 and do the work without claiming Fabric saw it.

package/plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md

@@ -0,0 +1,53 @@
+# Native host context hooks (FAA-48)
+
+Use this when installing, upgrading or diagnosing startup context outside Claude Code. Hook delivery and Fabric admission are separate: the agent still calls `fabric_whoami` and reads its actual answer. No adapter here enrolls a session, starts Fabric or calls a model.
+
+## Supported adapters
+
+| Host | Native integration | Output consumed by host | Activation |
+|---|---|---|---|
+| Claude Code | Plugin `hooks/hooks.json` | SessionStart `hookSpecificOutput.additionalContext` JSON | Enable the Claude plugin; reload the session |
+| Codex | `hooks.SessionStart` in `$CODEX_HOME/hooks.json` | SessionStart JSON, including the event name | Install command hook; inspect `/hooks` if its exact definition needs trust |
+| Kimi Code | `[[hooks]]` in `~/.kimi-code/config.toml` | Plain stdout; existing adapter retained | Install command hook; start a new session; current native consumption is not covered by the six-host fixture |
+| Hermes | Native plugin prompt section `fabric.context` | Session-frozen section, maximum 4000 characters | Install files, then `hermes plugins enable fabric-agent-adapter` |
+| OpenCode | Native `experimental.chat.system.transform` | Appends one unique system string | Install `.js` loader; start a new instance |
+| OpenClaw | Plugin `before_prompt_build` | `{prependContext}` | Install native plugin path/config; host runtime must be installed; reload through its owner |
+| Pi | Extension `before_agent_start` | Structured section, or preserved forced/legacy system prompt | Install `.js` loader; use the host's extension reload or a new instance |
+
+These adapters were checked against Codex 0.162.1, Hermes 0.21.4 (2026.9.21), OpenCode 1.19.0, OpenClaw 2026.10.4 and Pi 1.1.0. Claude Code 2.1.299 also executed SessionStart through an isolated SDK initialization, without a user turn. A parser/loader fixture does not establish a model run or live Fabric connection.
+
+Codex accepts plain text only when it does not look like JSON. The old `[fabric-agent-adapter]` prefix begins with `[`, so Codex tries JSON parsing and reports `hook returned invalid session start JSON output`. Structured JSON removes that ambiguity.
+
+## Install, update and remove
+
+```sh
+python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host opencode
+python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host opencode --apply --expect-sha256 <printed-digest>
+python3 <skill-dir>/scripts/fabric_session.py install-host-hooks --host opencode --remove
+```
+
+Use `codex`, `kimi`, `hermes`, `opencode`, `openclaw` or `pi`. Default is a dry run. `--config` overrides the native destination, `--script` selects an absolute `fabric_session.py` in a **complete installed skill**. Keep that path stable; a versioned plugin cache disappears on updates. Reapply after moving the skill. The native installer checks the helper and every required host module before writing a loader.
+
+| Host | Default destination |
+|---|---|
+| Hermes | `$HERMES_HOME/plugins/fabric-agent-adapter/`, default `~/.hermes/plugins/` |
+| OpenCode | `$XDG_CONFIG_HOME/opencode/plugins/fabric-agent-adapter.js`, default `~/.config/` |
+| OpenClaw | `$OPENCLAW_CONFIG_PATH`, otherwise `$OPENCLAW_STATE_DIR/openclaw.json`, default `~/.openclaw/` |
+| Pi | `$PI_CODING_AGENT_DIR/extensions/fabric-agent-adapter.js`, default `~/.pi/agent/` |
+
+Hermes activation remains its own explicit CLI step. Remove its activation with `hermes plugins disable fabric-agent-adapter`, then remove the loader. The installer does not parse or rewrite arbitrary Hermes YAML.
+
+OpenClaw uses strict JSON. For a JSON5 configuration, use OpenClaw's own config commands; this installer refuses it without guessing. An existing master/entry disable, deny list or denied hook permission is preserved and reported. This adapter needs both `allowConversationAccess` and `allowPromptInjection`; it does not read messages. Removing it drops its recognized load path and owned entry; customized entries are disabled. An existing allow-list entry is retained to avoid changing broader discovery policy. Removal is ownership-limited, not an exact rollback of the whole config.
+
+OpenCode and Pi loader files carry a managed marker. A foreign file at the same destination is refused, not overwritten. Existing unrelated extensions/settings remain. Config replacement uses a backup and a stale-plan hash check; Hermes's multi-file loader is preflighted before writes, but the operation is not a filesystem-wide transaction.
+
+## Runtime and failure boundaries
+
+- Native bridges give the Python helper only a working directory and, when observed, a boolean Fabric registration. Hermes uses its native read-only config, OpenCode its resolved enabled MCP entry, OpenClaw its resolved MCP servers and Pi an exact callable `fabric_whoami` tool name. Config registration is not admission.
+- Missing helper/Python, malformed values, excessive output or a four-second deadline produce no context. Existing host errors and permission failures are not silenced globally.
+- Fabric-launched sessions are silent. Other native events are not advertised: turn observations, unread counts and rejoin-only release remain Claude-specific and feature-gated.
+- A host in Switchboard's catalog may support MCP, proxy or launch while exposing no startup context hook. Never copy this configuration to another host solely because it can launch an agent.
+
+## Verification
+
+The repository has focused tests in `test/test_fabric_session.py`, `test/test_native_hook_install.py`, `test/test_hermes_host.py`, `test/host-hooks-opencode-pi.test.mjs` and `test/openclaw-hooks.test.mjs`. Optional native probes use isolated configuration and neutral fixtures, without paid inference. The task's evidence and full 31-host survey live in the owning repository under `docs/evidence/specs/host-hooks-2026-10-16/`; these repository paths are not required to run the installed skill.

package/plugins/fabric-agent-adapter/skills/working-with-fabric/references/session-hooks.md

@@ -32,7 +32,8 @@ zero; a `degraded` board that still gives the count is read.
 
 ## Codex and Kimi Code
 
-`fabric_session.py hook session-start --host codex|kimi` prints the preamble as plain text when the host has `fabric`
+`fabric_session.py hook session-start --host codex|kimi` emits structured SessionStart JSON for Codex and plain text
+for Kimi when the host has `fabric`
 registered (`[mcp_servers.fabric]` in `$CODEX_HOME/config.toml`; `mcpServers.fabric` in `~/.kimi-code/mcp.json`),
 plus the service line. Nothing else: no turn observation and no unread line, because a rejoin needs the runtime
 session id Fabric keeps with the enrollment, which only Claude Code supplies today (D1).
@@ -42,10 +43,15 @@ would add — never a value already in the file — and the `--apply --expect-sh
 backs the file up (`<file>.<UTC stamp>.bak`, never overwriting an earlier backup), keeps the file's mode, refuses a
 file whose shape is not `{"hooks": {"<Event>": [{"hooks": [...]}]}}` (Codex) or an array of `[[hooks]]` tables
 (Kimi Code, read back with `tomllib`: Python 3.11+), and refuses one that changed since the dry run. `--remove` takes
-the entry out again. Codex may ask the person to trust a new hook (`/hooks`) before it runs. The hook runs the
+the entry out again. Codex may ask the person to trust a new hook (`/hooks`) before it runs. Codex keys that trust by event, group and index, so
+`--remove` names the SessionStart groups after the removed one that it moves, which Codex asks the person to approve
+again. The hook runs the
 `fabric_session.py` of the skills install (`~/.agents/skills/working-with-fabric/`) when there is one, else this
 script's own path; a plugin cache path changes with each update, so pass `--script <a stable path>` there.
 
+Native Hermes, OpenCode, OpenClaw and Pi bridges are described in [native host hooks](native-host-hooks.md).
+They consume the same context through their own APIs. They never use the Claude-only rejoin/turn lifecycle.
+
 ## `watch-mail`
 
 `fabric_session.py watch-mail [--interval 60]` is for an idle Claude Code session waiting on the board; the agent
@@ -89,7 +95,9 @@ only variable names are looked at, never a value (two of them carry the session'
 One line per event that did something, never content: `~/Library/Caches/ai.passioncode.fabric-agent-adapter/hooks.log`
 (macOS), `$XDG_CACHE_HOME/fabric-agent-adapter/hooks.log` (Linux, default `~/.cache`),
 `%LOCALAPPDATA%\fabric-agent-adapter\hooks.log` (Windows). Mode 0600, rotated at 1 MB to `hooks.log.1`. The
-per-session spool is `sessions/<session id>/` beside it (turn entries capped at 50, `board.json`, `board.shown`),
+per-session spool is `sessions/<session id>/` beside it (turn entries capped at 50, `board.json`, `board.shown`; a
+folder untouched for 7 days, whose worker failed or whose session ended without SessionEnd, is removed by the next
+spooling hook),
 removed at the session's end.
 
 Turn them off with Claude Code's own switch (`/hooks`, or `"disableAllHooks": true` in settings), or remove the

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py

@@ -3,11 +3,11 @@
 COM-04; FAA-12a).
 
   fabric_session.py status [--json] [--cwd DIR]          # Fabric, fabric-mcp, the registrations; ONE next action
-  fabric_session.py hook session-start [--host H]         # H: claude (default), codex, kimi — the preamble
+  fabric_session.py hook session-start [--host H]         # H: claude, codex, kimi, hermes, opencode, openclaw, pi
   fabric_session.py hook stop|session-end|user-prompt-submit   # Claude Code only: hook JSON on stdin, always exit 0
   fabric_session.py deliver SESSION_DIR                  # the detached worker the stop and session-end hooks start
   fabric_session.py watch-mail [--interval 60]           # Claude Code: one line each time the unread count rises
-  fabric_session.py install-host-hooks --host codex|kimi [--apply | --remove]   # dry run unless --apply/--remove
+  fabric_session.py install-host-hooks --host HOST [--apply | --remove]   # dry run unless --apply/--remove
 
 Standard library only. Nothing here reads a token or a credential: Fabric's door token and enrollment credentials
 stay with `fabric-mcp`. Nothing secret goes into argv or the log. A turn observation is facts only: the HEAD commit,
@@ -53,6 +53,9 @@ PS_TIMEOUT_S = 0.5
 LOG_CAP_BYTES = 1_000_000
 SPOOL_CAP = 50
 LOCK_STALE_S = 30.0
+#: A session folder untouched this long belongs to a session that will not spool again: its worker failed, or the
+#: session ended without SessionEnd. Nothing retries it, so the next spooling hook removes it (FAA-50).
+SESSION_STALE_S = 7 * 86400
 READ_CAP = 64 * 1024
 CONFIG_CAP = 32 * 1024 * 1024
 WATCH_MIN_INTERVAL_S = 10
@@ -60,8 +63,10 @@ WATCH_MAX_BACKOFF_S = 900
 SESSION_ID = re.compile(r"[A-Za-z0-9._:-]{1,128}")
 LOOPBACK_ORIGIN = re.compile(r"http://127\.0\.0\.1:(\d{1,5})")
 LOCAL_ORIGIN = re.compile(r'"origin": "http://(?:127\.0\.0\.1|localhost)')
-VERSION = "0.34.1"
-HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code"}
+VERSION = "0.35.1"
+HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code",
+         "hermes": "Hermes", "opencode": "OpenCode", "openclaw": "OpenClaw", "pi": "Pi"}
+NATIVE_PLUGIN_HOSTS = frozenset(("hermes", "opencode", "openclaw", "pi"))
 # A session Fabric launched. FABRIC_LAUNCHED_SESSION=1 is the marker Fabric is asked to set (need D6); the others are
 # what Fabric already gives a launched session (fabric sessionBundle.ts): only their NAMES are looked at, never a value
 # — two of them carry the session's credential.
@@ -69,7 +74,8 @@ LAUNCH_MARKER = "FABRIC_LAUNCHED_SESSION"
 LAUNCH_SIGNALS = ("FABRIC_ACP_SESSION", "FABRIC_BRIDGE_URL", "KILO_CONFIG_CONTENT")
 
 PREAMBLE = (
-    "[fabric-agent-adapter] Fabric is running and this {host} has its MCP server `fabric`. "
+    "[fabric-agent-adapter] Fabric is running and this {host} has its MCP server `fabric` registered. "
+    "Registration is not proof of connection or admission. "
     "Call `fabric_whoami` first. Then read the project board: `com.status` (is it ready, how many unread), "
     "`com.list` for the messages, and `com.read_ack` only for what you actually read. "
     "Before you start work, call `fabric_work_list` (who is working on what here) and "
@@ -410,6 +416,30 @@ def spool(directory: Path, entry: Dict[str, Any]) -> Path:
     return path
 
 
+def prune_stale_sessions(env: Optional[Dict[str, str]] = None, now: Optional[float] = None,
+                         keep: Optional[str] = None) -> int:
+    """Remove session folders whose newest file is older than SESSION_STALE_S (a running worker's lock is a fresh file,
+    so its folder is never stale); never the folder of the session `keep`. Returns how many were removed. Never
+    raises."""
+    now = time.time() if now is None else now
+    removed = 0
+    try:
+        folders = list((state_root(env=env) / "sessions").iterdir())
+    except OSError:
+        return 0
+    for folder in folders:
+        try:
+            if folder.name == keep or not SESSION_ID.fullmatch(folder.name) or not folder.is_dir():
+                continue
+            newest = max([folder.stat().st_mtime] + [f.stat().st_mtime for f in folder.iterdir()])
+            if now - newest > SESSION_STALE_S:
+                _remove_tree(folder)
+                removed += 1
+        except OSError:
+            continue
+    return removed
+
+
 def lock_held(directory: Path) -> bool:
     lock = directory / "worker.lock"
     try:
@@ -443,14 +473,17 @@ def read_hook_input() -> Dict[str, Any]:
 
 def hook_session_start(payload: Dict[str, Any], env: Optional[Dict[str, str]] = None,
                        host: str = "claude") -> Optional[str]:
-    """What to print, or None: Claude Code's hook JSON, or plain text for Codex and Kimi Code. The preamble when the
+    """What to print, or None: Claude/Codex hook JSON, plain context for native plugins and Kimi. The preamble when the
     host has `fabric` registered (one line pointing at the broker when Fabric is down), and the machine's
     descriptor-count line when it has Fabric services. Silent in a session Fabric launched."""
     if host not in HOSTS or fabric_launched(env):
         return None
     cwd = Path(payload.get("cwd") or os.getcwd())
     parts: List[str] = []
-    if host_registered(host, cwd, env):
+    registered = host_registered(host, cwd, env)
+    if host in NATIVE_PLUGIN_HOSTS and payload.get("fabric_registered") is True:
+        registered = True  # Native bridge's boolean observation, never enrollment or authorization.
+    if registered:
         hub = locate_hub(fabric_root(env=env))
         if hub["state"] == "running":
             parts.append(PREAMBLE.format(host=HOSTS[host]))
@@ -462,7 +495,7 @@ def hook_session_start(payload: Dict[str, Any], env: Optional[Dict[str, str]] =
     if not parts or launched_by_ancestor(env):
         return None
     context = "\n".join(parts)
-    if host != "claude":
+    if host not in ("claude", "codex"):
         return context
     return json.dumps({"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": context}})
 
@@ -522,6 +555,7 @@ def hook_spool(payload: Dict[str, Any], event: str, env: Optional[Dict[str, str]
         return "skipped: launched by Fabric"
     entry = {"event": event, "runtimeSessionId": session_id, "cwd": str(cwd),
              "observedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
+    prune_stale_sessions(env, keep=session_id)
     if event == "end" and isinstance(payload.get("reason"), str):
         entry["reason"] = payload["reason"][:64]
     spool(directory, entry)
@@ -1083,8 +1117,14 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
         args = parser.parse_args(list(argv))
     except SystemExit as exc:
         return int(exc.code or 2)
+    if args.host in NATIVE_PLUGIN_HOSTS:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("_fabric_native_installer", Path(__file__).with_name("host_hooks.py"))
+        installer = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(installer)
+        return installer.main(list(argv), env=env, out=out, err=err)
     if args.host not in ("codex", "kimi"):
-        err("install-host-hooks: --host must be codex or kimi (Claude Code gets its hooks from the plugin)")
+        err("install-host-hooks: --host must be codex, kimi, hermes, opencode, openclaw or pi (Claude uses its plugin)")
         return 2
     if args.config:
         path = Path(args.config).expanduser()
@@ -1093,6 +1133,7 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
     else:
         path = _home(env) / ".kimi-code" / "config.toml"
     command = hook_command(str(args.script or default_hook_script(env)), args.host)
+    shifted = 0  # Codex hook groups after ours, whose position a removal moves
     try:
         data = _read_bytes(path)
         digest = _digest(data)
@@ -1106,19 +1147,30 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
                 if not present:
                     out("install-host-hooks: no Fabric preamble hook in %s; nothing to change" % path)
                     return 0
-                groups = []
-                for group in doc["hooks"]["SessionStart"]:
+                groups, dropped = [], None
+                for index, group in enumerate(doc["hooks"]["SessionStart"]):
                     kept = [h for h in group.get("hooks", []) if not _is_ours(h.get("command"), args.host)]
                     if kept or not group.get("hooks"):
                         groups.append(dict(group, hooks=kept) if kept != group.get("hooks") else group)
+                    elif dropped is None:
+                        dropped = index  # a group that held only our hook goes; the groups after it move up
+                if dropped is not None:
+                    shifted = len(doc["hooks"]["SessionStart"]) - dropped - 1
                 if groups:
                     doc["hooks"]["SessionStart"] = groups
                 else:
                     del doc["hooks"]["SessionStart"]
                 new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
             elif present:
-                out("install-host-hooks: the Fabric preamble hook is already in %s; nothing to change" % path)
-                return 0
+                owned = [h for g in doc["hooks"]["SessionStart"] for h in g.get("hooks", [])
+                         if _is_ours(h.get("command"), args.host)]
+                if len(owned) != 1:
+                    raise Refused("multiple Fabric hooks are configured; preserve their matchers and resolve duplicates before updating")
+                if owned[0]["command"] == command:
+                    out("install-host-hooks: the Fabric preamble hook is already in %s; nothing to change" % path)
+                    return 0
+                owned[0]["command"] = command
+                new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
             else:
                 doc.setdefault("hooks", {}).setdefault("SessionStart", []).append(entry)
                 new = (json.dumps(doc, indent=2) + "\n").encode("utf-8")
@@ -1168,6 +1220,11 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
                                               else "added the Fabric preamble hook to", path,
                                               "(backup: %s)" % backup if backup else "(new file)"))
         out("Undo: fabric_session.py install-host-hooks --host %s %s" % (args.host, "--apply" if args.remove else "--remove"))
+        if shifted:
+            # Codex keys a hook's trust by its event, group and index: the groups after ours moved up one, so Codex asks
+            # the person to trust them again in /hooks before they run.
+            out("Codex trusts a hook by its position: %d SessionStart hook group(s) after the removed one moved, and "
+                "Codex will ask you to approve them again in /hooks." % shifted)
         return 0
     except Refused as exc:
         err("install-host-hooks: refused — %s" % exc)

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/host_hooks.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+# #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
+"""Install bounded native context bridges. Dry-run by default; no model/service calls.
+
+OpenCode/Pi load a managed shim. Hermes loads a managed plugin wrapper and needs
+its native `hermes plugins enable fabric-agent-adapter` opt-in separately.
+OpenClaw loads the bundled plugin through its native configuration. Removal
+keeps unrelated settings and disables only this entry; existing allow/deny policy
+is never loosened. JSON5 configuration is refused, not rewritten as guessed JSON.
+"""
+import argparse
+import hashlib
+import importlib.util
+import json
+import os
+from pathlib import Path
+
+BASE = Path(__file__).resolve().parent
+spec = importlib.util.spec_from_file_location('_fabric_hook_install_common', BASE / 'fabric_session.py')
+fs = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(fs)
+MARKER = 'fabric-agent-adapter managed host hook v1'
+IDENTITY = 'fabric-agent-adapter'
+
+
+def destination(host, env):
+    home = fs._home(env)
+    if host == 'opencode':
+        return Path(env.get('XDG_CONFIG_HOME') or home / '.config') / 'opencode/plugins/fabric-agent-adapter.js'
+    if host == 'pi':
+        return Path(env.get('PI_CODING_AGENT_DIR') or home / '.pi/agent') / 'extensions/fabric-agent-adapter.js'
+    if host == 'hermes':
+        return Path(env.get('HERMES_HOME') or home / '.hermes') / 'plugins/fabric-agent-adapter'
+    return Path(env.get('OPENCLAW_CONFIG_PATH') or Path(env.get('OPENCLAW_STATE_DIR') or home / '.openclaw') / 'openclaw.json')
+
+
+def _object(parent, key):
+    if key not in parent: parent[key] = {}
+    if not isinstance(parent[key], dict): raise fs.Refused('unexpected object shape at ' + key)
+    return parent[key]
+
+
+def _list(parent, key):
+    if key not in parent: parent[key] = []
+    if not isinstance(parent[key], list) or not all(isinstance(x, str) for x in parent[key]):
+        raise fs.Refused('unexpected string-list shape at ' + key)
+    return parent[key]
+
+
+def openclaw_edit(data, script, remove):
+    try:
+        doc = json.loads(data.decode('utf-8')) if data else {}
+    except (ValueError, UnicodeError):
+        raise fs.Refused('OpenClaw config is not strict JSON; use the native config CLI for JSON5')
+    if not isinstance(doc, dict): raise fs.Refused('OpenClaw config must be an object')
+    target = str(script.parent / 'hosts/openclaw')
+    def ours(value):
+        if value == target:
+            return True
+        if not value.replace('\\', '/').endswith('/working-with-fabric/scripts/hosts/openclaw'):
+            return False
+        try:
+            manifest = fs.read_small(Path(value) / 'openclaw.plugin.json')
+            return isinstance(manifest, str) and json.loads(manifest).get('id') == IDENTITY
+        except (ValueError, AttributeError):
+            return False
+    if remove:
+        existing = doc.get('plugins', {})
+        if isinstance(existing, dict):
+            existing_entries = existing.get('entries', {})
+            existing_load = existing.get('load', {})
+            existing_paths = existing_load.get('paths', []) if isinstance(existing_load, dict) else []
+            has_entry = isinstance(existing_entries, dict) and IDENTITY in existing_entries
+            has_path = isinstance(existing_paths, list) and any(isinstance(p, str) and ours(p) for p in existing_paths)
+            if not has_entry and not has_path:
+                return data
+    plugins = _object(doc, 'plugins')
+    if not remove and (plugins.get('enabled') is False or IDENTITY in _list(plugins, 'deny')):
+        raise fs.Refused('existing OpenClaw plugin policy disables this adapter; policy was preserved')
+    entries = _object(plugins, 'entries')
+    entry = _object(entries, IDENTITY)
+    hooks = _object(entry, 'hooks')
+    if not remove and (entry.get('enabled') is False or any(hooks.get(k) is False for k in ('allowConversationAccess','allowPromptInjection'))):
+        raise fs.Refused('existing OpenClaw entry denies this hook; policy was preserved')
+    load = _object(plugins, 'load')
+    paths = _list(load, 'paths')
+    kept = [p for p in paths if not ours(p)]
+    load['paths'] = kept if remove else kept + [target]
+    entry['enabled'] = not remove
+    if remove and set(entry) <= {'enabled','hooks'} and hooks == {'allowConversationAccess':True,'allowPromptInjection':True}:
+        del entries[IDENTITY]
+    if not remove:
+        hooks.update(allowConversationAccess=True, allowPromptInjection=True)
+        if 'allow' in plugins:
+            allow = _list(plugins, 'allow')
+            if IDENTITY not in allow: allow.append(IDENTITY)
+    return (json.dumps(doc, indent=2) + '\n').encode()
+
+
+def plan(host, path, script, remove):
+    """Return [(path, expected bytes, desired bytes|None)] before any mutation."""
+    if host == 'openclaw':
+        old = fs._read_bytes(path)
+        if remove and old is None: return []
+        return [(path, old, openclaw_edit(old, script, remove))]
+    if host == 'hermes':
+        if path.is_symlink(): raise fs.Refused('plugin directory is a symlink; nothing was changed')
+        module = str(script.parent / 'hosts/hermes/__init__.py')
+        loader = ('# ' + MARKER + '\nimport importlib.util\n'
+                  '_spec = importlib.util.spec_from_file_location("_fabric_native_hermes", ' + repr(module) + ')\n'
+                  '_module = importlib.util.module_from_spec(_spec)\n_spec.loader.exec_module(_module)\nregister = _module.register\n')
+        manifest = '# ' + MARKER + '\n' + (script.parent / 'hosts/hermes/plugin.yaml').read_text()
+        desired = {path/'__init__.py':loader, path/'plugin.yaml':manifest}
+    else:
+        module = (script.parent / ('hosts/' + host + '/fabric.mjs')).as_uri()
+        desired = {path: '// ' + MARKER + '\nexport { default } from ' + json.dumps(module) + ';\n'}
+    changes = []
+    for target, text in desired.items():
+        old = fs._read_bytes(target)
+        if old is not None and MARKER.encode() not in old.split(b'\n', 1)[0]:
+            raise fs.Refused('destination is not an adapter-managed file: ' + str(target))
+        changes.append((target, old, None if remove else text.encode()))
+    return changes
+
+
+def plan_digest(changes):
+    return hashlib.sha256(json.dumps([(str(p),fs._digest(old)) for p,old,_ in changes]).encode()).hexdigest()
+
+
+def main(argv=None, env=None, out=print, err=print):
+    env = os.environ if env is None else env
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--host', choices=['hermes','opencode','openclaw','pi'], required=True)
+    mode=parser.add_mutually_exclusive_group()
+    mode.add_argument('--apply',action='store_true');mode.add_argument('--remove',action='store_true');mode.add_argument('--dry-run',action='store_true')
+    parser.add_argument('--config');parser.add_argument('--script');parser.add_argument('--expect-sha256')
+    args=parser.parse_args(argv)
+    try:
+        script=Path(args.script).expanduser().absolute() if args.script else BASE/'fabric_session.py'
+        if not script.is_file(): raise fs.Refused('shared helper is missing')
+        if not args.remove:
+            required = {'hermes':['hosts/hermes/__init__.py','hosts/hermes/plugin.yaml'],
+                        'opencode':['hosts/context.mjs','hosts/opencode/fabric.mjs'],
+                        'pi':['hosts/context.mjs','hosts/pi/fabric.mjs'],
+                        'openclaw':['hosts/context.mjs','hosts/openclaw/index.mjs','hosts/openclaw/package.json','hosts/openclaw/openclaw.plugin.json']}[args.host]
+            if any(not (script.parent/p).is_file() for p in required):
+                raise fs.Refused('native adapter source is missing; update the complete skill before installing hooks')
+        path=Path(args.config).expanduser().absolute() if args.config else destination(args.host,env)
+        changes=plan(args.host,path,script,args.remove)
+        digest=plan_digest(changes)
+        if args.expect_sha256 and digest != args.expect_sha256: raise fs.Refused('configuration changed since the plan')
+        out('host=%s sha256=%s action=%s' % (args.host,digest,'remove' if args.remove else 'install'))
+        for p,old,new in changes: out('%s %s' % ('unchanged' if old==new else 'would change',p))
+        if args.apply or args.remove:
+            # Preflight every destination before changing even the first one.
+            if any(fs._read_bytes(p) != old for p,old,_ in changes): raise fs.Refused('destination changed during planning')
+            for p,old,new in changes:
+                if old==new: continue
+                if new is None:
+                    if fs._read_bytes(p) != old: raise fs.Refused('destination changed during removal')
+                    if old is not None: p.unlink()
+                else: fs._replace_file(p,new,old)
+            if args.host=='hermes' and args.remove:
+                # A foreign addition in this directory is preserved.
+                try:path.rmdir()
+                except OSError:pass
+            out('native loader files updated; existing sessions must reload to use them')
+        else: out('dry run; no files changed. Apply with --apply --expect-sha256 ' + digest)
+        if args.host=='hermes':
+            out('native activation: hermes plugins %s fabric-agent-adapter' % ('disable' if args.remove else 'enable'))
+        return 0
+    except (fs.Refused,OSError,ValueError) as exc:
+        # Refused has only our shape diagnostics; parser failures never echo config bytes.
+        err('host-hooks: refused: ' + (str(exc) if isinstance(exc,fs.Refused) else type(exc).__name__))
+        return 1
+
+if __name__=='__main__':raise SystemExit(main())
+# #endregion native-host-context

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/context.mjs

@@ -0,0 +1,33 @@
+// #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
+// Shared, non-resident bridge. A context hook never enrolls or calls a model.
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const scriptPath = fileURLToPath(new URL('../fabric_session.py', import.meta.url));
+const hosts = new Set(['opencode', 'pi', 'openclaw']);
+const cap = 64 * 1024;
+
+export async function readContext(host, cwd, options = {}) {
+  if (!hosts.has(host) || typeof cwd !== 'string' || !cwd || cwd.includes('\0')) return '';
+  const payload = {cwd};
+  if (options.fabricRegistered === true) payload.fabric_registered = true;
+  const input = JSON.stringify(payload);
+  if (Buffer.byteLength(input) > cap) return '';
+  const timeout = Number.isFinite(options.timeoutMs)
+    ? Math.max(1, Math.min(4000, options.timeoutMs)) : 4000;
+  return new Promise(resolve => {
+    try {
+      const child = execFile(options.python || 'python3',
+        ['-S', options.script || scriptPath, 'hook', 'session-start', '--host', host],
+        {timeout, killSignal:'SIGKILL', maxBuffer:cap, encoding:'utf8', windowsHide:true},
+        (error, stdout) => {
+          if (error || typeof stdout !== 'string' || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(stdout)) return resolve('');
+          resolve(stdout.trim());
+        });
+      // A missing executable or early exit may close stdin before it is written.
+      child.stdin?.on('error', () => {});
+      child.stdin?.end(input);
+    } catch { resolve(''); }
+  });
+}
+// #endregion native-host-context

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/hermes/__init__.py

@@ -0,0 +1,141 @@
+# #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
+"""Hermes native, session-frozen Fabric context; no model or lifecycle worker."""
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import signal
+import threading
+import time
+from collections.abc import Mapping
+
+MAX_CONTEXT_CHARS = 4000
+TIMEOUT_SECONDS = 4
+MAX_OUTPUT_BYTES = 16000
+MAX_INPUT_BYTES = 4096
+
+
+def _kill_owned(process):
+    try:
+        if os.name == "posix":
+            os.killpg(process.pid, signal.SIGKILL)
+        else:
+            process.kill()
+    except (OSError, ProcessLookupError):
+        pass
+
+
+def _capture(command, payload):
+    """Bound output while reading, not after buffering a noisy helper's entire stdout."""
+    if len(payload) > MAX_INPUT_BYTES:
+        return None
+    process = subprocess.Popen(command, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                               stderr=subprocess.DEVNULL, start_new_session=os.name == "posix")
+    output = bytearray()
+    invalid = threading.Event()
+    deadline = time.monotonic() + TIMEOUT_SECONDS
+
+    def read_output():
+        try:
+            while True:
+                chunk = process.stdout.read(min(1024, MAX_OUTPUT_BYTES + 1 - len(output)))
+                if not chunk:
+                    return
+                output.extend(chunk)
+                if len(output) > MAX_OUTPUT_BYTES:
+                    invalid.set()
+                    _kill_owned(process)
+                    return
+        except (OSError, ValueError):
+            invalid.set()
+
+    reader = threading.Thread(target=read_output, daemon=True)
+    reader.start()
+    try:
+        try:
+            process.stdin.write(payload)
+            process.stdin.close()
+        except BrokenPipeError:
+            pass  # FAA-51: a helper may exit without reading its input; its output still counts
+        process.wait(timeout=max(0.001, deadline - time.monotonic()))
+        reader.join(timeout=max(0, deadline - time.monotonic()))
+        if reader.is_alive() or invalid.is_set() or process.returncode != 0:
+            return None
+        return bytes(output)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    finally:
+        # Own process group only: also close a pipe inherited by an owned child.
+        _kill_owned(process)
+        process.wait()
+        reader.join(timeout=0.2)
+        if not reader.is_alive():
+            process.stdout.close()
+        try:
+            process.stdin.close()
+        except BrokenPipeError:
+            pass
+
+
+def fabric_registered(config=None):
+    """Read only the native registration flag; never forward server config or credentials."""
+    try:
+        if config is None:
+            from hermes_cli.config import load_config_readonly
+            config = load_config_readonly()
+        servers = config.get("mcp_servers") if isinstance(config, Mapping) else None
+        server = servers.get("fabric") if isinstance(servers, Mapping) else None
+        if not isinstance(server, Mapping):
+            return False
+        enabled = server.get("enabled", True)
+        return enabled is True or isinstance(enabled, str) and enabled.lower().strip() in ("true", "1", "yes", "on")
+    except (ImportError, OSError, TypeError, ValueError):
+        return False
+
+
+def context_for_session(session_info, session_script=None):
+    """Read the shared preamble through its bounded plain-text host protocol."""
+    if not isinstance(session_info, Mapping):
+        return ""
+    cwd = session_info.get("cwd", "")
+    if not isinstance(cwd, str) or len(cwd) > MAX_INPUT_BYTES // 2 or "\x00" in cwd:
+        return ""
+    try:
+        if session_script is None:
+            script = Path(__file__).resolve().parents[2] / "fabric_session.py"
+        elif isinstance(session_script, str) and Path(session_script).is_absolute():
+            script = Path(session_script)
+        else:
+            return ""
+        if not script.is_file():
+            return ""
+        result = _capture(
+            [sys.executable, "-S", str(script), "hook", "session-start", "--host", "hermes"],
+            json.dumps({"cwd": cwd or os.getcwd(), "fabric_registered": fabric_registered()},
+                       ensure_ascii=False).encode("utf-8"),
+        )
+        if result is None:
+            return ""
+        text = result.decode("utf-8").strip()
+        if len(text) > MAX_CONTEXT_CHARS or any(ord(char) < 32 and char not in "\n\r\t" for char in text):
+            return ""
+        return text
+    except (OSError, ValueError, subprocess.TimeoutExpired):
+        # Context is best effort; never leak configuration, diagnostics or hook input.
+        return ""
+
+
+def register(ctx):
+    """Use Hermes' cache-safe prompt section API, not observer hook returns."""
+    if not callable(getattr(ctx, "register_system_prompt_section", None)):
+        return
+    try:
+        script = ctx.get_config("session_script", None)
+    except (AttributeError, OSError, TypeError, ValueError):
+        return
+    ctx.register_system_prompt_section(
+        "fabric.context", lambda info: context_for_session(info, script),
+        position="after_memory", max_chars=MAX_CONTEXT_CHARS,
+    )
+# #endregion native-host-context

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/hermes/plugin.yaml

@@ -0,0 +1,5 @@
+name: fabric-agent-adapter
+description: Bounded Fabric context frozen into the Hermes session prompt.
+kind: standalone
+requires_hermes: '>=0.21.4'
+license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/openclaw/index.mjs

@@ -0,0 +1,45 @@
+// #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
+// Native OpenClaw prompt hook. Never observes conversation content or sends messages.
+import { readContext } from '../context.mjs';
+
+function fabricRegistered(config) {
+  const servers = config?.mcp?.servers;
+  if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return false;
+  return ['fabric', 'fabric-mcp'].some(name => {
+    const entry = Object.hasOwn(servers, name) ? servers[name] : undefined;
+    return entry && typeof entry === 'object' && !Array.isArray(entry)
+      && entry.enabled !== false
+      && [entry.command, entry.url].some(value => typeof value === 'string' && value.trim());
+  });
+}
+
+export function createPlugin(contextReader = readContext) {
+  return {
+    id: 'fabric-agent-adapter',
+    name: 'Fabric Agent Adapter',
+    description: 'Adds bounded Fabric context through the native prompt hook.',
+    register(api) {
+      api.on('before_prompt_build', async (_event, ctx) => {
+        // workspaceDir is optional in the host contract. Do not substitute the
+        // Gateway process directory, which can belong to a different project.
+        if (typeof ctx?.workspaceDir !== 'string' || !ctx.workspaceDir.trim()) return;
+        try {
+          // Configured is not connected/admitted. Forward only the boolean,
+          // never server configuration, headers, environment or credentials.
+          const options = fabricRegistered(api.config) ? { fabricRegistered: true } : {};
+          const context = await contextReader('openclaw', ctx.workspaceDir, options);
+          ctx.hookInvocation?.assertActive();
+          if (typeof context !== 'string' || !context.trim()) return;
+          return { prependContext: context };
+        } catch {
+          // Missing dependencies, unavailable context and expired invocations
+          // must not stop an unrelated turn or leak diagnostics into its prompt.
+          return;
+        }
+      });
+    },
+  };
+}
+
+export default createPlugin();
+// #endregion native-host-context

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/openclaw/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "fabric-agent-adapter",
+  "name": "Fabric Agent Adapter",
+  "description": "Bounded Fabric context using the native OpenClaw prompt hook.",
+  "activation": { "onStartup": true },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/openclaw/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@passioncode-ai/fabric-agent-adapter-openclaw",
+  "private": true,
+  "type": "module",
+  "license": "AGPL-3.0-only OR LicenseRef-PassionCode-Commercial",
+  "openclaw": {
+    "extensions": ["./index.mjs"],
+    "compat": { "pluginApi": ">=2026.10.4" }
+  }
+}

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/opencode/fabric.mjs

@@ -0,0 +1,24 @@
+// #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
+import { readContext } from '../context.mjs';
+
+const marker = '[fabric-agent-adapter]';
+
+// OpenCode's legacy loader treats every export as a plugin factory.
+export default async function fabricPlugin({directory} = {}) {
+  let fabricRegistered = false;
+  return {
+    config: async config => {
+      const entry = config?.mcp?.fabric;
+      // Observe the host's resolved configuration; never read or forward secrets.
+      fabricRegistered = !!entry && typeof entry === 'object' && entry.enabled !== false &&
+        ((entry.type === 'local' && Array.isArray(entry.command) && entry.command.length > 0) ||
+         (entry.type === 'remote' && typeof entry.url === 'string' && entry.url.length > 0));
+    },
+    'experimental.chat.system.transform': async (_input, output) => {
+      if (!Array.isArray(output?.system) || output.system.some(part => typeof part === 'string' && part.includes(marker))) return;
+      const context = await readContext('opencode', directory, {fabricRegistered});
+      if (context && !output.system.includes(context)) output.system.push(context);
+    },
+  };
+}
+// #endregion native-host-context

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/hosts/pi/fabric.mjs

@@ -0,0 +1,36 @@
+// #region native-host-context — docs: plugins/fabric-agent-adapter/skills/working-with-fabric/references/native-host-hooks.md
+import { readContext } from '../context.mjs';
+
+const marker = '[fabric-agent-adapter]';
+
+export default function fabricExtension(pi) {
+  pi.on('before_agent_start', async (event, ctx) => {
+    if (!event || !ctx) return;
+    const options = event.systemPromptOptions;
+    if (typeof options?.forceSystemPrompt === 'string' && options.forceSystemPrompt.includes(marker)) return;
+    if (!options && typeof event.systemPrompt === 'string' && event.systemPrompt.includes(marker)) return;
+    if (options?.sections?.fabric_agent_adapter) return;
+    let fabricRegistered = false;
+    try {
+      const tools = pi.getAllTools?.();
+      fabricRegistered = Array.isArray(tools) && tools.some(tool =>
+        tool?.exposure !== 'hidden' &&
+        (tool?.name === 'fabric_whoami' || tool?.name === 'mcp__fabric__fabric_whoami'));
+    } catch { /* Early startup or a disabled tool registry is not registration. */ }
+    const context = await readContext('pi', ctx.cwd, {fabricRegistered});
+    if (!context) return;
+    if (typeof options?.forceSystemPrompt === 'string') {
+      if (options.forceSystemPrompt.includes(context)) return;
+      options.forceSystemPrompt += '\n\n' + context;
+    } else if (options && typeof options === 'object') {
+      options.sections ??= {};
+      if (typeof options.sections !== 'object' || Array.isArray(options.sections)) return;
+      options.sections.fabric_agent_adapter = context;
+    } else if (typeof event.systemPrompt === 'string') {
+      if (event.systemPrompt.includes(context)) return;
+      // Older Pi versions expose only the replacement-prompt return contract.
+      return {systemPrompt:event.systemPrompt + '\n\n' + context};
+    }
+  });
+}
+// #endregion native-host-context