Files
marqdo-cli/docs/adr/0013-generic-cli-tool-protocol.md
cflmy 25a1faa6ef feat(m0.6-r3): generic external CLI Tool Protocol v1
- 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
2026-11-20 11:44:20 +08:00

76 lines
3.3 KiB
Markdown

# 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/remove` plus fallback for unknown top-level commands;
* `tool.json` (schema `marqdo.cli-tool`, schema_version 1) declares
`name`, `version`, `command`, `entrypoint` and 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 `OsString` arguments (no shell), inherits
stdin/stdout/stderr and cwd, sets `MARQDO_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
1. Add a `clap` variant per known tool. Rejected by the audit (E01/E12).
2. Auto-discover `marqdo-*` from PATH (Cargo-style). Rejected: implicit
execution and PATH hijacking; M0.6 requires explicit installation.
3. Use the C ABI plugin registry. Rejected: different lifecycle, protocol and
security boundary.
4. 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.