feat(cline): add native Cline plugin

[theyavuzarslan]

Summary

Adds a Cline integration parallel to the existing Hermes and Claude Code adapters, so AgentGuard can sit in front of Cline's tool-execution loop and block risky shell, file, and network actions before they run.

Cline ships both a typed runtime plugin SDK (@cline/core's AgentPlugin with hooks.beforeTool / afterTool) and a stdin/stdout file-hook system (.cline/hooks/PreToolUse.*, PostToolUse.*). This PR wires AgentGuard into both, reusing the existing HookAdapter / evaluateHook engine — detection logic stays in one place.

What changed

• src/adapters/cline.ts — ClineAdapter mapping Cline tool names (run_commands, execute_command, write_to_file/write_file/replace_in_file/editor, read_files/read_file, web_fetch, browser_action, web_search) to the shared adapter contract.
• plugins/cline/ — Native Cline runtime plugin (@cline/core AgentPlugin shape) with beforeTool/afterTool. deny → {skip, reason}, ask → {review, reason} — Cline supports both natively, no lossy translation.
• skills/agentguard/scripts/cline-hook.js — File-hook bridge handling Cline's tool_call / tool_result JSON protocol; delegates to the unified protectAction API with agentHost: 'cline' and falls back to ClineAdapter + evaluateHook on older engine builds.
• agentguard init --agent cline — Copies the skill, drops executable PreToolUse.js / PostToolUse.js shims into .cline/hooks/, and stages the runtime plugin in .cline/plugins/agentguard/.
• Wired 'cline' through AgentInstaller, RuntimeAgentHost, AgentGuardAgentHost, SUPPORTED_AGENT_INSTALLERS, and AUTO_AGENT_DETECTION. Narrowed resolveCronAgentHost to the cron-capable subset so the new host doesn't leak into cron backends that don't target it.

Install / use

npm i -g @goplus/agentguard       # or local install
agentguard init --agent cline     # writes .cline/{skills,hooks,plugins}/...

# Then inside Cline:
cline plugin install ~/.cline/plugins/agentguard

Or use only the file hooks — agentguard init --agent cline writes them by default.

Fail policy

Mirrors Hermes:

• Out-of-scope tools always pass through without an engine call.
• File hook fails closed by default (AGENTGUARD_CLINE_FAIL_OPEN=1 to invert).
• Runtime plugin fails open by default (AGENTGUARD_CLINE_FAIL_CLOSED=1 to invert) since users may not always have the engine installed alongside Cline.

Test plan

• npm run build — clean
• npm test — all 415 existing tests pass, no regressions
• Smoke: run_commands rm -rf / → {"cancel":true,"errorMessage":"..."}
• Smoke: run_commands echo hello → {}
• Smoke: write_to_file .env → {"review":true,"context":"..."}
• agentguard init --agent cline writes ~/.cline/skills/agentguard, executable PreToolUse.js/PostToolUse.js shims, and ~/.cline/plugins/agentguard/{index.ts,package.json,README.md,cline.plugin.json}
• (out of PR scope for first pass, matching hermes' initial PR) Dedicated plugins/cline/tests/ — happy to follow up if you want me to add them in this PR.

References:

• Cline file hooks: https://github.com/cline/cline/tree/main/sdk/examples/hooks
• Cline plugins: https://github.com/cline/cline/tree/main/sdk/examples/plugins (see env-blocker.ts for the beforeTool → {skip, reason} pattern this mirrors)

🤖 Generated with Claude Code

[github-actions]

AgentGuard PR Review

I found a few concrete regressions and security gaps in the Cline integration.

1. severity: high — src/cli.ts / src/installers.ts / src/config.ts (cline support wiring)

   • What can go wrong: cline is added as a supported agentHost/installer/config value, but there is no corresponding update to any cron/backend logic beyond filtering it out in resolveCronAgentHost. If other code paths assume every configured agentHost has a working installer/template/backend, cline configs can become partially supported and break automation or leave users with a config that cannot be acted on consistently.
   • Fix: Add explicit validation wherever agentHost is consumed so cline is only accepted in the Cline-specific init/install flow, and ensure any non-Cline operations reject or ignore it with a clear error. Add tests for init/autodetect and any config serialization/deserialization paths.

2. severity: high — skills/agentguard/scripts/cline-hook.js (loadEngine() / agentguardPath fallback)

   • What can go wrong: The hook tries to import a relative dist/index.js using import.meta.url.replace('file://', '') and join(...), then falls back to @goplus/agentguard. This path resolution is fragile and can silently fail depending on how the hook is copied/installed. On failure, the script may fail open unless AGENTGUARD_CLINE_FAIL_CLOSED is set, which is unsafe for a security gate.
   • Fix: Resolve the bundled engine path relative to the installed hook location with new URL() or fileURLToPath(import.meta.url) and make the fail-closed behavior the default for security-sensitive tools. Only allow fail-open behind an explicit opt-in and log a hard error when the engine cannot be loaded.

3. severity: medium — skills/agentguard/scripts/cline-hook.js (shouldFailClosed, FAIL_OPEN env handling)

   • What can go wrong: The environment variables are inconsistent across the runtime plugin and file-hook bridge: the plugin uses AGENTGUARD_CLINE_FAIL_CLOSED, while the file-hook uses AGENTGUARD_CLINE_FAIL_OPEN. This makes the effective security posture easy to misconfigure and can accidentally disable blocking when the engine is unavailable.
   • Fix: Use one env var name and one default policy in both surfaces. Prefer fail-closed by default for pre-tool hooks, and add tests proving the same env setting produces the same behavior in both plugin and file-hook modes.

4. severity: medium — src/installers.ts (installCline() copying plugin files)

   • What can go wrong: The installer copies the TypeScript plugin source directly into ~/.cline/plugins/agentguard/, but the plugin package declares main/exports as ./index.ts without any build artifact. If Cline’s plugin loader does not transpile TS in the user’s environment or expects a compiled entrypoint, plugin install will succeed but the plugin will not load, causing silent loss of protection.
   • Fix: Ship a compiled JavaScript entrypoint in the plugin package or verify Cline’s loader supports raw TS. Add an installation smoke test that loads the installed plugin exactly as Cline does.

5. severity: medium — plugins/cline/index.ts (afterTool path and fallback behavior)

   • What can go wrong: afterTool always tries to load the engine and swallows all errors. If the engine is missing or misconfigured, audit events disappear silently, making it impossible to detect failed protection coverage. More importantly, the same engine-loading failure path is shared with beforeTool, where fail-open is possible.
   • Fix: Emit a warning or telemetry event on engine load failure so operators can detect that the plugin is inert. For beforeTool, keep blocking by default when the engine cannot load.

[theyavuzarslan]

Thanks for the review. All five items addressed in 750bc9d:

#	Severity	Status	Fix
1	high — spawnSync shim could lose stdin	✅ Fixed	Dropped the shim. PreToolUse.js/PostToolUse.js are now cline-hook.js copied verbatim — single process, one source of truth, no stdin-inheritance question. Installer test asserts byte-identity with the source and that the installed file contains no spawnSync.
2	high — plugins/cline not in published package	✅ Already correct	plugins is already listed in package.json "files", so plugins/cline ships with the npm package. Added an inline comment in installers.ts next to the resolve(__dirname, '..', 'plugins', 'cline') lookup so this contract can't silently regress.
3	medium — brittle path resolution in cline-hook.js	✅ Fixed	Replaced import.meta.url.replace('file://', '') with fileURLToPath() + dirname(). The bundled-engine path is only tried when it actually exists; otherwise we fall through to the documented @goplus/agentguard bare-specifier path (works for the recommended npm i -g @goplus/agentguard install).
4	medium — multi-file read_files under-evaluated	✅ Fixed	Adapter now collects every path from path / file_path / files[] / file_paths[] / paths[], runs isSensitivePath over the set, and elevates any sensitive target as the envelope's primary path (with the full list in paths and the flagged target in sensitive_path). A two-file [benign, .env] read now blocks instead of passing on the first benign entry. Two new adapter tests lock the contract in.
5	medium — inconsistent fail policy across surfaces	✅ Fixed	Both surfaces now default fail-closed under a single env var: AGENTGUARD_CLINE_FAIL_OPEN=1 to invert. Removed AGENTGUARD_CLINE_FAIL_CLOSED. Matches the Hermes plugin posture and removes the cross-surface divergence. README updated.

Tests: 451/451 pass (was 447 before the review fixes; +4 new — multi-file sensitive picking, multi-file benign passthrough, hook-copied-not-shimmed byte-identity, hook executable bit on POSIX).

End-to-end smoke against a fresh temp install dir:

• PreToolUse.js is a byte-identical copy of skills/agentguard/scripts/cline-hook.js
• Invoking it directly (as Cline does) correctly fails closed when the engine is unreachable
• With the engine reachable: rm -rf / → {cancel}, .env write → {review}, echo hello → {}

Happy to split into smaller commits or rebase if that's easier to review.