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

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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.0",
   "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.0",
   "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.0"
   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.0"
   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.0"
   contract-version: "0.1.0"
   contract-commit: "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"
 ---

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.0"
 ---
 
 # 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).
@@ -46,6 +47,9 @@ the entry out again. Codex may ask the person to trust a new hook (`/hooks`) bef
 `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

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,
@@ -60,8 +60,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.0"
+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 +71,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 "
@@ -443,14 +446,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 +468,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}})
 
@@ -1083,8 +1089,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()
@@ -1117,8 +1129,15 @@ def install_host_hooks_cli(argv: Sequence[str], env: Optional[Dict[str, str]] =
                     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")

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,135 @@
+# #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:
+        process.stdin.write(payload)
+        process.stdin.close()
+        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()
+        process.stdin.close()
+
+
+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