- add tool install/list/remove and unknown-command dispatch without hardcoded tool names or clap variants - validate and copy local tool packages atomically, reject entrypoint escapes and symlinks, record and re-verify SHA-256 - forward OsString args, stdio, cwd and exit status without a shell; never execute PATH programs implicitly - add black-box tests for arbitrary names, Unicode args, built-in conflicts, traversal, version mismatch, tampering and PATH hijacking - add ADR-0013 and mark R3 complete
3.3 KiB
ADR-0013: Generic external CLI Tool Protocol v1
Status: Accepted Date: 2026-11-20
Context
M0.6 must let external tools (view, knowledge, prove, or arbitrary
third-party programs) become marqdo <command> entries without changing the
core source or command enum. The CLI currently has a closed clap enum and no
generic distribution path. C ABI plugins and foreign kernels are unrelated
trust models: a Tool is a user-invoked native process.
Decision
spec/tool-v1.md is implemented as follows:
- new top-level commands are limited to
tool install/list/removeplus fallback for unknown top-level commands; tool.json(schemamarqdo.cli-tool, schema_version 1) declaresname,version,command,entrypointand optional compatibility; the core does not contain any tool name, download URL or business argument;- install requires a local manifest, validates the command (lowercase ASCII,
no built-in conflict), rejects absolute/
../symlink-escaping entrypoints, copies the package without following symlinks into a user-controlled tool home, re-verifies the executable SHA-256, writes a registry record, and publishes atomically via rename; - dispatch checks the registry record, re-verifies the executable hash, starts
the entrypoint directly with
OsStringarguments (no shell), inherits stdin/stdout/stderr and cwd, setsMARQDO_BIN/MARQDO_TOOL_PROTOCOL=1, and propagates the exit code; - a missing registration is an unknown command; a
marqdo-<name>on PATH is never executed implicitly; - uninstall removes only the exact controlled installation directory.
The tool home defaults to the platform config directory and can be redirected
with MARQDO_TOOL_HOME for tests/enterprise deployment.
Alternatives
- Add a
clapvariant per known tool. Rejected by the audit (E01/E12). - Auto-discover
marqdo-*from PATH (Cargo-style). Rejected: implicit execution and PATH hijacking; M0.6 requires explicit installation. - Use the C ABI plugin registry. Rejected: different lifecycle, protocol and security boundary.
- Implement a remote registry first. Rejected: local manifest installation is the required closed loop; name-based installs are a future optional index.
Compatibility
This adds one new top-level command (tool) and an unknown-command fallback.
Built-in commands always win. Future core commands that collide with an
installed tool are a breaking change and need an ADR/migration policy. The
manifest is versioned; unknown optional fields are ignored in v1 but never
imply authorization.
Security
A Tool is a normal process run as the user, not inside the .mq.md sandbox.
It does not automatically receive Marqdo capabilities, secrets or plugin
handles. Install never runs the tool. The executable hash detects post-install
tampering, not a malicious publisher; local source selection is the trust
decision. Symlinks are rejected during package copy.
Testing
crates/cli/tests/tool_protocol.rs covers arbitrary command names,
install/list/remove, argument/exit-code forwarding, Unicode args, built-in
conflict, traversal, version mismatch, binary tampering and PATH hijacking.
spec/tool-v1.md lists the full black-box matrix.
Migration & rollout
R3 adds the command surface. R4 can expose Analysis/Trace compatibility through the manifest's optional fields; no tool business logic enters the core.