root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
f0d6d70a3292b084fc056231234fb8e19094ed73
fusion/plugins/fusion-plugin-acp-runtime/README.md
gsxdsm 489a287d6f feat(acp): bundle into CLI, on-demand install, S1 safety + evidence (U8) 
Wires the ACP runtime plugin into the published CLI (RUNTIME_PLUGIN_IDS in
tsup.config) and the on-demand BUILTIN_PLUGINS catalog (experimental), matching
the untrusted-subprocess security posture. Adds the Risk S1 default-policy
safety: an acpAllowUnrestricted acknowledgement (default false) — without it, a
blanket allow on a sensitive category is escalated to approval rather than
auto-approved under the allow-all default policy, applied in both the permission
floor and fs write gating. Adds docs/acp-contract.md (launch/readiness +
failure taxonomy), a README with the AGENTS.md-required upstream evidence
(SDK repo/docs/release/integrity), a bundle-output test for the staged plugin,
and a @runfusion/fusion minor changeset. Package green at 179 tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-03 09:25:56 -07:00

3.7 KiB
Raw Blame History

@fusion-plugin-examples/acp-runtime

A Fusion runtime plugin that drives any external Agent Client Protocol (ACP) agent over JSON-RPC/stdio. One integration unlocks every ACP-compatible agent (Gemini CLI, the Claude Code ACP adapter, and any future agent that speaks the protocol) through the standard protocol instead of a bespoke per-CLI integration.

Selected via runtimeId: "acp". Installed on demand (experimental) — see the Fusion plugin catalog (fn plugin install fusion-plugin-acp-runtime).

Security posture

The ACP agent is an untrusted subprocess that calls back into Fusion for permissions and filesystem access. This plugin enforces a defense-in-depth floor:

  • Per-category permission gating. Each session/request_permission is classified by tool kind into a Fusion action category and checked against the live permission policy — never a preset shortcut. allow_once only (never a persisted blanket grant). Unmappable kinds and missing policy default-deny.
  • Unrestricted-risk acknowledgement (acpAllowUnrestricted). Because the shipped default policy is unrestricted (allow-all), a blanket allow on a sensitive category is escalated to approval unless the user explicitly sets acpAllowUnrestricted: true. Prefer running the ACP runtime under an approval-required policy.
  • Filesystem jail. fs/read_text_file / fs/write_text_file are opt-in (acpFsRead / acpFsWrite, writes default OFF), confined to the session cwd by a real symlink-resolving jail (realpath + O_NOFOLLOW), with a deny-list for secrets (.env, *.pem, …) and git internals (.git/**). Writes are gated through the file_write_delete permission category.
  • Untrusted-input bounds. Streamed output is sanitized (ANSI/control strip) and bounded (per-turn + per-chunk caps; bounded tool-call correlation map).
  • Subprocess isolation. The agent env is built from an allow-list (acpEnvAllowList) — inherited process.env is not forwarded.

Not sandboxed in v1: the agent's own process/network syscalls run with Fusion's user privileges (OS-level sandboxing is recommended future work).

Settings

Key Default Meaning
acpBinaryPath acp-agent Agent binary to spawn
acpArgs [] Args that launch the agent in ACP/stdio mode (e.g. ["--acp"])
acpModel — Optional model identifier reported via describeModel
acpFsRead false Advertise/register fs/read_text_file
acpFsWrite false Advertise/register fs/write_text_file (gated)
acpEnvAllowList [] Env var names forwarded to the agent subprocess
acpAllowUnrestricted false Acknowledge the untrusted-agent risk under an allow-all policy

Upstream / third-party integration evidence

Per AGENTS.md (External-integration evidence):

See docs/acp-contract.md for the launch/readiness contract and failure taxonomy.

Reference in New Issue View Git Blame Copy Permalink