feat(goose): MCP advisory integration + upstream hard-gate proposal

Goose has no out-of-process plugin API — the only true Allow/Deny/
RequireApproval surface is the in-process Rust ToolInspector trait
(crates/goose/src/tool_inspection.rs), which is compile-time. This PR
ships the two integrations that ARE possible today and clearly
distinguishes their security guarantees.

Surface 1 — MCP extension (advisory, ships today)
=================================================
`agentguard init --agent goose` writes/merges an `agentguard` entry under
`extensions:` in `~/.config/goose/config.yaml` (or `%APPDATA%/Block/goose/
config/config.yaml` on Windows, or `$GOOSE_CONFIG_DIR/config.yaml` if set):

  extensions:
    agentguard:
      type: stdio
      command: agentguard-mcp
      args: []
      timeout: 300
      enabled: true
      description: GoPlus AgentGuard MCP — security scanner + action evaluator

The model can now call AgentGuard's scanner/action-evaluator MCP tools.
This is **advisory only**: the agent can skip calling AgentGuard and go
straight to `developer__shell`, and AgentGuard never sees it.
plugins/goose/README.md states this in plain language so no user is
under the impression they have a hard gate.

Surface 2 — upstream hard-gate proposal (draft, no PR yet)
=========================================================
plugins/goose/UPSTREAM_PROPOSAL.md drafts a SECURITY_INSPECTOR_ENDPOINT
webhook ToolInspector for block/goose, mirroring their existing
SECURITY_PROMPT_CLASSIFIER_ENDPOINT pattern. That would let AgentGuard
(or any other vendor) become a real out-of-process pre-execution gate
with Allow/Deny/RequireApproval semantics. Includes JSON schema, fail
policy, and open questions to confirm with maintainers before opening
the PR.

Wiring
======
- 'goose' added to AgentInstaller, RuntimeAgentHost, AgentGuardAgentHost,
  SUPPORTED_AGENT_INSTALLERS, normalizeAgentHost. Intentionally NOT in
  AUTO_AGENT_DETECTION since Goose config lives at ~/.config/goose/
  (outside cwd) and an advisory install shouldn't be auto-applied.
- resolveCronAgentHost narrowed to the cron-capable subset (matches the
  pattern used when wiring other non-cron hosts).
- YAML merge: hand-rolled (no js-yaml dep). Handles three cases —
  (a) no config.yaml at all → create with extensions: block,
  (b) extensions: exists → insert agentguard: as a sibling child,
  (c) agentguard: already present → no-op (idempotent).
  Force mode strips the prior block and re-emits in canonical form.

Tests: 419/419 pass (was 415; +4 — fresh install, merge into existing
extensions preserving other entries and top-level keys, idempotency
under repeated runs, and a docs check that the README states the
"advisory, not a security boundary" framing.)

Author: theyavuzarslan

plugins/goose/README.md

@@ -0,0 +1,82 @@
+# GoPlus AgentGuard — Goose integration (advisory, MCP-based)
+
+Goose ([block/goose](https://github.com/block/goose)) is **not** integrated
+the same way as Cline, Hermes, or Continue. This README explains the
+limitation honestly and documents the install paths that ship today.
+
+## TL;DR
+
+```bash
+npm i -g @goplus/agentguard
+agentguard init --agent goose
+```
+
+That writes `agentguard` as an MCP extension in `~/.config/goose/config.yaml`:
+
+```yaml
+extensions:
+  agentguard:
+    type: stdio
+    command: agentguard-mcp
+    args: []
+    timeout: 300
+    enabled: true
+    description: GoPlus AgentGuard MCP — security scanner + action evaluator
+```
+
+Restart Goose. AgentGuard's scanner and action evaluator are now MCP-callable.
+
+## Important: this is advisory, not a hard gate
+
+Goose currently has **no out-of-process plugin API** for intercepting tool
+calls. The only true `Allow / Deny / RequireApproval` surface is the in-process
+Rust `ToolInspector` trait (`crates/goose/src/tool_inspection.rs`), which is
+compile-time — there is no dynamic loader for it.
+
+What an MCP extension can do:
+
+- **Provide tools the model may choose to call** (`scan_skill`, `evaluate_action`, etc.)
+- **Refuse to return data** when called
+
+What an MCP extension **cannot** do:
+
+- Sit on the execution path of every Goose tool call
+- Block a `developer__shell` call the model never routed through AgentGuard
+
+In other words, if the agent decides to call `shell` with `rm -rf /` and
+never asks AgentGuard's MCP tools first, AgentGuard never gets a chance to
+veto it. The model is free to skip you. **Treat this as defense-in-depth,
+not a security boundary.**
+
+For a real hard gate, see [UPSTREAM_PROPOSAL.md](./UPSTREAM_PROPOSAL.md) — a
+draft proposal to add a `SECURITY_INSPECTOR_ENDPOINT` webhook to Goose,
+mirroring its existing `SECURITY_PROMPT_CLASSIFIER_ENDPOINT`. That would
+turn AgentGuard into a genuine pre-execution inspector with `block` /
+`require_approval` returns.
+
+## What the MCP integration is useful for
+
+- **Pre-commit / pre-PR scanning** of skills the agent wants to install
+- **Action evaluation** when the agent explicitly asks "is this dangerous?"
+- **Audit logging** of evaluations the model did make through AgentGuard
+
+These are real value-adds even without a hard gate, but be clear with users
+about the boundary.
+
+## Manual install
+
+If you'd rather not run `agentguard init --agent goose`, copy the snippet
+above into your existing `~/.config/goose/config.yaml` under `extensions:`
+(or create the file if it doesn't exist). On Windows the path is
+`%APPDATA%\Block\goose\config\config.yaml`.
+
+The installer preserves any prior `extensions:` entries and is idempotent —
+re-running won't duplicate the block.
+
+## Reference
+
+- Goose extensions / MCP: https://block.github.io/goose/docs/getting-started/installation
+- ToolInspector trait (compile-time): `crates/goose/src/tool_inspection.rs`
+- Existing classifier endpoint (the model we're proposing to copy):
+  `crates/goose/src/security/classification_client.rs` +
+  `SECURITY_PROMPT_CLASSIFIER_ENDPOINT`

plugins/goose/UPSTREAM_PROPOSAL.md

@@ -0,0 +1,118 @@
+# Goose upstream proposal — generic security webhook inspector
+
+This document drafts a proposal to file against [block/goose](https://github.com/block/goose)
+that would give third-party security tools (AgentGuard, but also others) a
+real out-of-process hard gate on tool execution.
+
+This is **not** a PR yet — it's the design that should accompany one.
+
+## Problem
+
+Goose currently has two ways to wire in security policy on tool calls:
+
+1. **`ToolInspector` trait** (Rust, in-process, compile-time). The real
+   `Allow / Deny / RequireApproval` decision surface, but there is no
+   dynamic loader for it — third parties cannot ship one without forking
+   and rebuilding Goose.
+2. **MCP extensions**. Model-callable. The agent can skip your tools, so
+   this is advisory only — it is not a security boundary.
+
+This means there is no supported way today for an external security service
+(static analyzer, runtime engine, anomaly detector) to gate Goose's tool
+execution without forking the binary.
+
+## Prior art inside Goose
+
+Goose already accepts an external HTTP endpoint for one specific
+classification job. From `crates/goose/src/security/classification_client.rs`
+and the config:
+
+```
+SECURITY_PROMPT_CLASSIFIER_ENDPOINT
+SECURITY_PROMPT_ENABLED
+```
+
+The classifier endpoint receives JSON, returns a classification, and Goose
+honors the result. This is the pattern we're asking to generalize.
+
+## Proposal
+
+Add a new `WebhookToolInspector` that registers automatically when a
+configured endpoint is set:
+
+```yaml
+# ~/.config/goose/config.yaml
+SECURITY_INSPECTOR_ENABLED: true
+SECURITY_INSPECTOR_ENDPOINT: "http://127.0.0.1:7777/inspect"
+SECURITY_INSPECTOR_TIMEOUT_MS: 1500
+SECURITY_INSPECTOR_FAIL_OPEN: false       # default: fail-closed
+SECURITY_INSPECTOR_AUTH_HEADER: "X-Token: …"
+```
+
+At startup, `ToolInspectionManager::add_inspector` registers a built-in
+`WebhookToolInspector` if `SECURITY_INSPECTOR_ENABLED == true`. It calls the
+endpoint for every `ToolRequest`, with a JSON body like:
+
+```json
+{
+  "session_id": "sess_…",
+  "tool_requests": [
+    { "tool": "developer__shell", "input": { "command": "rm -rf /" }, "call_id": "…" }
+  ],
+  "messages": [ /* optional, truncated */ ],
+  "goose_mode": "auto"
+}
+```
+
+And expects back:
+
+```json
+{
+  "results": [
+    { "call_id": "…",
+      "action": "Deny",
+      "reason": "destructive command",
+      "policy_version": "…" }
+  ]
+}
+```
+
+`action` is one of `Allow`, `Deny`, `RequireApproval`. The webhook's response
+maps 1:1 to `InspectionAction` — no impedance mismatch with the existing
+trait.
+
+## Why this is a small change
+
+- It doesn't change the `ToolInspector` trait. The new inspector is just
+  another implementer.
+- It mirrors a pattern Goose already accepts (the classifier endpoint), so
+  it should pass the "is this in scope for this project?" smell test.
+- Fail-open vs fail-closed is configurable, with a security-safe default
+  (fail-closed).
+- No new permissions to plumb through the trust system; existing
+  `ToolInspectionManager` handles aggregation.
+
+## What we'd ship in the PR
+
+1. `crates/goose/src/security/webhook_inspector.rs` — `WebhookToolInspector` impl
+2. Config keys + parsing in `crates/goose/src/config/`
+3. Registration in `crates/goose/src/agents/` startup
+4. Tests (mocking the endpoint with `wiremock` or similar)
+5. A docs page in `docs/security/` covering trade-offs and recommended deploys
+
+## Open questions to confirm with maintainers before opening the PR
+
+- Naming: `SECURITY_INSPECTOR_*` vs `TOOL_INSPECTOR_*` vs scoped to a single
+  vendor key. We'd prefer the generic name so other security vendors can use
+  the same surface.
+- Should the webhook also see `PostToolUse` events for audit-only logging,
+  or is pre-execution enough? (Our preference: pre-only, keep the surface
+  minimal; audit lives elsewhere.)
+- Should responses be allowed to mutate the tool input (`overrideInput`),
+  as Cline and Continue hooks do? Probably no for v1 — keeps the threat
+  model simple.
+
+---
+
+**Status:** draft. We (GoPlus) intend to file an issue first to gauge
+maintainer interest before opening a PR. Anyone in this repo can take it on.

src/cli.ts

@@ -40,15 +40,18 @@ import {
   type CronBackend,
   type ThreatFeedCronRemovalResult,
   type OpenClawGatewayOptions,
+  type CronAgentHost,
 } from './feed/cron.js';
 
-const SUPPORTED_AGENT_INSTALLERS: AgentInstaller[] = ['claude-code', 'codex', 'openclaw', 'hermes', 'qclaw'];
+const SUPPORTED_AGENT_INSTALLERS: AgentInstaller[] = ['claude-code', 'codex', 'openclaw', 'hermes', 'qclaw', 'goose'];
 const AUTO_AGENT_DETECTION: Array<{ agent: AgentInstaller; dir: string }> = [
   { agent: 'claude-code', dir: '.claude' },
   { agent: 'openclaw', dir: '.openclaw' },
   { agent: 'hermes', dir: '.hermes' },
   { agent: 'qclaw', dir: '.qclaw' },
   { agent: 'codex', dir: '.codex' },
+  // 'goose' is intentionally NOT in auto-detection: config lives at
+  // ~/.config/goose/ (outside cwd), and an MCP install is advisory-only.
 ];
 const REQUIRED_INIT_COMMAND = 'agentguard init --agent auto';
 
@@ -64,7 +67,7 @@ async function main() {
     .command('init')
     .description('Create ~/.agentguard/config.json and local runtime paths')
     .option('--level <level>', 'Protection level: strict | balanced | permissive')
-    .option('--agent <agent>', 'Install hook/template for claude-code, codex, openclaw, hermes, or qclaw')
+    .option('--agent <agent>', 'Install hook/template for claude-code, codex, openclaw, hermes, qclaw, or goose (MCP advisory)')
     .option('--cloud <url>', 'AgentGuard Cloud URL to store in local config')
     .option('--shell-hooks', 'For Hermes: install legacy shell hooks instead of the native plugin')
     .option('--force', 'Overwrite existing hook/template files')
@@ -106,7 +109,7 @@ async function main() {
           return;
         }
         if (!SUPPORTED_AGENT_INSTALLERS.includes(normalizedAgent as AgentInstaller)) {
-          throw new Error('Invalid agent. Use auto, claude-code, codex, openclaw, hermes, or qclaw.');
+          throw new Error('Invalid agent. Use auto, claude-code, codex, openclaw, hermes, qclaw, or goose.');
         }
         const agent = normalizedAgent as AgentInstaller;
         config.agentHost = agent;
@@ -1062,8 +1065,12 @@ function printCronRemovalSummary(results: ThreatFeedCronRemovalResult[]): void {
   console.log('No AgentGuard subscribe cron job was found.');
 }
 
-function resolveCronAgentHost(config: AgentGuardConfig): AgentGuardAgentHost | undefined {
-  return config.agentHost ?? config.agentHosts?.[0];
+function resolveCronAgentHost(config: AgentGuardConfig): CronAgentHost | undefined {
+  const host = config.agentHost ?? config.agentHosts?.[0];
+  if (host === 'claude-code' || host === 'codex' || host === 'openclaw' || host === 'hermes' || host === 'qclaw') {
+    return host;
+  }
+  return undefined;
 }
 
 function readStdinIfAvailable(): string {

src/config.ts

@@ -2,7 +2,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync }
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
-export type AgentGuardAgentHost = 'claude-code' | 'codex' | 'openclaw' | 'hermes' | 'qclaw';
+export type AgentGuardAgentHost = 'claude-code' | 'codex' | 'openclaw' | 'hermes' | 'qclaw' | 'goose';
 
 export interface AgentGuardConfig {
   version: 1;
@@ -226,7 +226,7 @@ function normalizeLevel(value: unknown): AgentGuardConfig['level'] | null {
 }
 
 function normalizeAgentHost(value: unknown): AgentGuardAgentHost | undefined {
-  return value === 'claude-code' || value === 'codex' || value === 'openclaw' || value === 'hermes' || value === 'qclaw'
+  return value === 'claude-code' || value === 'codex' || value === 'openclaw' || value === 'hermes' || value === 'qclaw' || value === 'goose'
     ? value
     : undefined;
 }