@goplus/agentguard 1.1.18 → 1.1.26

package/docs/cloud-native-api.md

@@ -25,7 +25,7 @@ X-API-Key: ag_live_xxxxx
 3. Evaluate runtime actions locally using cached policy and the bundled local engine.
 4. Write local audit JSONL before any Cloud sync.
 5. Upload redacted audit events to `POST /api/v1/events/ingest`.
-6. For `require_approval`, create `POST /api/v1/approvals` and block the action until reviewed.
+6. For `require_approval`, use the local agent host's native permission channel when supported. If the host cannot safely resume a reviewed call, block locally and ask the user to retry only after intentionally changing local policy.
 7. Use `GET /api/v1/sessions/:sessionId/timeline` for review/debug UI.
 
 If Cloud is unavailable, continue local enforcement using cached policy, then bundled default policy.
@@ -91,10 +91,24 @@ The script installs `@goplus/agentguard`, writes a safe fallback local config, t
 
 ```bash
 agentguard init --agent "$AGENTGUARD_AGENT" --cloud "$AGENTGUARD_CLOUD_URL"
+```
+
+When the effective agent host is OpenClaw, the script should connect without an
+API key:
+
+```bash
+agentguard connect --cloud "$AGENTGUARD_CLOUD_URL"
+```
+
+The CLI registers a local Agent JWT and prints an activation link. For other
+agent hosts, or when the user explicitly chooses API-key auth, the script should
+call:
+
+```bash
 agentguard connect --cloud "$AGENTGUARD_CLOUD_URL" --api-key "$AGENTGUARD_API_KEY"
 ```
 
-Native CLI implementations should support `--cloud` as an alias for the Cloud URL and `--api-key` as an alias for the API key.
+Native CLI implementations should support `--cloud` as an alias for the Cloud URL and `--api-key` as an alias for the API key. Installers that accept `agent=auto` should use the agent host persisted by `agentguard init --agent auto` when choosing between Agent JWT and API-key auth.
 
 ### Health check
 
@@ -262,126 +276,20 @@ Limits and behavior:
 - `input` should be a redacted preview, not full file content or full prompt content.
 - If upload fails, spool locally and retry later.
 
-### Create approval
+### Runtime approvals
 
-```http
-POST /api/v1/approvals
-Content-Type: application/json
-X-API-Key: ag_live_xxxxx
-```
+There is no Cloud approval inbox in the current native runtime flow. Native
+clients must not tell users to approve protected runtime actions in Cloud.
 
-Request:
+When a decision returns `require_approval`:
 
-```json
-{
-  "actionId": "act_local_123",
-  "sessionId": "sess_local_123",
-  "agentHost": "claude-code",
-  "actionType": "file_read",
-  "toolName": "Read",
-  "input": "~/.ssh/id_rsa",
-  "riskScore": 55,
-  "riskLevel": "high",
-  "reasons": [],
-  "policyVersion": "runtime-v0.1",
-  "cwd": "/workspace/app",
-  "sourceSkill": "optional-skill-id",
-  "metadata": {
-    "evaluation": "local-oss"
-  }
-}
-```
-
-Response:
-
-```json
-{
-  "success": true,
-  "data": {
-    "approvalId": "apr_abc123",
-    "actionId": "act_local_123",
-    "sessionId": "sess_local_123",
-    "status": "pending"
-  }
-}
-```
-
-Native behavior:
-
-- Create this only after local or Cloud decision returns `require_approval`.
-- Block the action while approval is pending.
-- Show the approval id to the user when available.
-
-### List approvals
-
-```http
-GET /api/v1/approvals?status=pending
-X-API-Key: ag_live_xxxxx
-```
-
-Response:
-
-```json
-{
-  "success": true,
-  "data": {
-    "approvals": [
-      {
-        "approvalId": "apr_abc123",
-        "actionId": "act_local_123",
-        "sessionId": "sess_local_123",
-        "agentHost": "claude-code",
-        "actionType": "file_read",
-        "toolName": "Read",
-        "inputPreview": "~/.ssh/id_rsa",
-        "status": "pending",
-        "riskScore": 55,
-        "riskLevel": "high",
-        "reasons": [],
-        "policyVersion": "runtime-v0.1",
-        "createdAt": "2026-05-11T00:00:00.000Z"
-      }
-    ]
-  }
-}
-```
-
-Native usage: optional inbox UI or debugging command.
-
-### Review approval
-
-```http
-PATCH /api/v1/approvals/:approvalId
-Content-Type: application/json
-X-API-Key: ag_live_xxxxx
-```
-
-Request:
-
-```json
-{
-  "status": "approved",
-  "note": "Expected deploy"
-}
-```
-
-`status` must be either `approved` or `denied`.
-
-Response:
-
-```json
-{
-  "success": true,
-  "data": {
-    "approvalId": "apr_abc123",
-    "actionId": "act_local_123",
-    "sessionId": "sess_local_123",
-    "status": "approved"
-  }
-}
-```
+- Claude Code should surface the native `PreToolUse` `ask` response.
+- Codex-style hosts should surface the local `confirm` response.
+- OpenClaw currently blocks locally because the runtime hook cannot safely pause
+  and resume the original tool call after an external review.
 
-Native usage: optional reviewer UX. Most local hooks should simply block and ask the user to review in Cloud.
+Cloud may still provide policy and session timeline visibility, but approval or
+confirmation must happen in the local agent host.
 
 ### Session timeline
 

package/docs/codex.md

@@ -35,4 +35,16 @@ Use these mappings for Codex-style hooks or skills:
 - browser/network fetches → `network`
 - MCP tool calls → `mcp_tool`
 
-When Cloud is connected, Codex events are synced as redacted previews and can participate in Cloud approvals.
+When Cloud is connected, Codex events are synced as redacted previews. Confirmation still happens through the local agent permission flow, not a Cloud approval page.
+
+If a protected action returns `confirm`, AgentGuard stores a short-lived pending
+approval and includes an approval command:
+
+```bash
+agentguard approve --action-id act_local_... --once
+```
+
+Run that command only after the user explicitly approves, then retry the
+original action once. If the action id was not visible, inspect
+`agentguard approvals list --json`; use `agentguard approve --last --once`
+only when there is exactly one relevant unexpired pending approval.

package/docs/openclaw.md

@@ -10,7 +10,7 @@ To install and enable the AgentGuard OpenClaw plugin:
 agentguard init --agent openclaw
 ```
 
-This creates a local plugin under `~/.openclaw/plugins/agentguard` and enables it in `~/.openclaw/openclaw.json`.
+This creates a local plugin under `~/.openclaw/plugins/agentguard`, installs the AgentGuard skill under `~/.openclaw/skills/agentguard`, and enables the plugin in `~/.openclaw/openclaw.json`.
 
 ```ts
 import { registerOpenClawPlugin } from '@goplus/agentguard';
@@ -23,6 +23,18 @@ export default function setup(api) {
 }
 ```
 
+## Cloud connect
+
+After OpenClaw initialization, run:
+
+```bash
+agentguard connect
+```
+
+No API key is required for the OpenClaw flow. AgentGuard registers a local Agent
+JWT, prints an activation link, and may send the link to the latest OpenClaw
+channel. Open that link to bind the local agent to your account.
+
 ## Runtime hook shape
 
 For direct hook integration, send events to:
@@ -36,6 +48,25 @@ agentguard protect
 
 AgentGuard accepts OpenClaw-style JSON with `toolName` and `params`, plus Claude-style `tool_name` and `tool_input`.
 
+OpenClaw cannot safely pause and resume a protected tool call, so AgentGuard
+blocks `require_approval` actions locally and stores a short-lived pending
+approval. The block reason includes:
+
+```bash
+agentguard approve --action-id act_local_... --once
+```
+
+Run that command only after the user explicitly approves, then retry the
+original action once. If the action id was not visible in the OpenClaw message,
+inspect pending approvals first:
+
+```bash
+agentguard approvals list --json
+```
+
+Use `agentguard approve --last --once` only when there is exactly one relevant
+unexpired pending approval; otherwise approve the specific `actionId`.
+
 ## Docker demo
 
 See `examples/openclaw-docker/` for a minimal Docker demo that installs `@goplus/agentguard`, runs `agentguard init --agent openclaw`, and provides a starter plugin.

package/docs/privacy-boundary.md

@@ -18,7 +18,6 @@ Only redacted runtime audit previews are uploaded by default:
 - `sessionId`, `agentHost`, `actionType`, `toolName`
 - Redacted `input` preview, capped at 2,000 characters
 - Decision, risk score, risk level, reasons, and policy version
-- Optional approval request metadata for `require_approval`
 
 ## Built-in redaction
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplus/agentguard",
-  "version": "1.1.18",
+  "version": "1.1.26",
   "description": "GoPlus AgentGuard — Security guard for AI agents. Blocks dangerous commands, prevents data leaks, protects secrets. 20 detection rules, runtime action evaluation, trust registry.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/agentguard/SKILL.md

@@ -71,7 +71,7 @@ required post-install steps.
 Parse `$ARGUMENTS` to determine the subcommand:
 
 - **`init [args...]`** — Run `agentguard init`, especially `agentguard init --agent <agent>` after installation
-- **`connect [args...]`** — Run `agentguard connect` to connect optional Cloud policy, audit, and approvals
+- **`connect [args...]`** — Run `agentguard connect` to connect optional Cloud policy, audit, and approvals. AgentGuard supports either API-key auth or Agent JWT auth; only one Cloud auth method is required.
 - **`scan <path>`** — Scan a skill or codebase for security risks
 - **`action <description>`** — Evaluate whether a runtime action is safe
 - **`patrol [run|setup|status]`** — Daily security patrol for OpenClaw environments
@@ -98,19 +98,29 @@ Supported CLI commands and options:
 | CLI command | Options | Notes |
 |---|---|---|
 | `agentguard init` | `--level <level>`, `--agent <agent>`, `--cloud <url>`, `--force` | Creates local config, persists the selected agent host, and optionally installs templates for `claude-code`, `codex`, `openclaw`, `hermes`, or `qclaw` |
-| `agentguard connect` | `--key <key>`, `--api-key <key>`, `--url <url>`, `--cloud <url>` | Prefer `AGENTGUARD_API_KEY` over passing secrets in flags |
-| `agentguard disconnect` | none | Removes local Cloud API key, connection timestamp, pending event spool, and cached Cloud policy; keeps Cloud URL, audit log, and installed hooks/templates |
-| `agentguard status` | none | Shows local config, Cloud URL/API key status, policy cache, audit path |
+| `agentguard connect` | `--key <key>`, `--api-key <key>`, `--url <url>`, `--cloud <url>` | API-key auth and Agent JWT auth are alternatives; configure only one. Prefer `AGENTGUARD_API_KEY` over passing secrets in flags |
+| `agentguard disconnect` | none | Removes local Cloud credentials, pending event spool, cached Cloud policy, and the managed `agentguard-threat-feed` subscribe cron job; keeps Cloud URL, audit log, and installed hooks/templates |
+| `agentguard status` | none | Shows local config, active Cloud auth method, policy cache, audit path |
 | `agentguard policy pull` | `--json` | Pulls Cloud effective runtime policy into the local cache |
 | `agentguard policy show` | `--json` | Shows the cached effective runtime policy, or the bundled default policy when no cache exists |
+| `agentguard approve` | `--action-id <id>` or `--last`, `--once`, `--json` | Approves one existing pending runtime action; never approve without explicit user confirmation |
+| `agentguard approvals list` | `--json` | Lists unexpired pending runtime approvals |
 | `agentguard doctor` | none | Checks local setup and Cloud reachability when connected |
 | `agentguard protect` | `--agent <agent>`, `--action-type <type>`, `--tool-name <name>`, `--session-id <id>`, `--decision-mode <local-first|cloud>`, `--json` | Evaluates one runtime action from stdin or hook environment |
 | `agentguard subscribe` | `--since <iso>`, `--json`, `--quiet`, `--no-report`, `--cron <expr>`, `--cron-target <auto|openclaw|qclaw|hermes|system>`, `--cron-name <name>`, `--force`, `--cron-run`, `--cron-notify-run` | Pulls Cloud threat advisories and optionally self-checks local skills |
 | `agentguard checkup` | `--json` | Runs the local agent health checkup |
 | `agentguard checkup --against-advisory <id>` | `--json` | CLI threat-feed self-check for one advisory; this is a targeted mode, not the default health-check workflow |
 
+Connect behavior:
+
+- Always execute `agentguard connect ...` directly when the user asks for it. Do not answer that an API key must be obtained before running the command.
+- `agentguard connect` with no `--key`, `--api-key`, or `AGENTGUARD_API_KEY` is valid in OpenClaw environments: the CLI uses Agent JWT registration, prints an activation link, and may notify the latest OpenClaw channel.
+- Only suggest `agentguard connect --key <key>` when the user explicitly wants API-key auth or when the CLI itself reports that Agent JWT registration is unavailable. If the CLI says OpenClaw is not initialized, suggest `agentguard init --agent openclaw` and then rerun `agentguard connect`.
+
 If the user writes `/agentguard cli <args...>`, execute `agentguard <args...>` directly.
 
+When AgentGuard returns `confirm` or a block reason that includes `Approve once: agentguard approve --action-id ... --once`, do not retry the protected action until the user explicitly approves. Treat user replies such as "yes", "approve", "approved", "confirm", "confirmed", "continue", "go ahead", "execute", "run it", "同意", "确认", "批准", "继续", or "执行" as explicit approval for the most recent protected action. After approval, run exactly the provided `agentguard approve --action-id ... --once` command, then retry the original action once. If the action id is unavailable, use `agentguard approvals list --json`; only use `agentguard approve --last --once` when there is exactly one relevant unexpired pending approval. If multiple pending approvals exist, ask the user to choose a specific action id.
+
 Do **not** route plain `/agentguard scan`, `/agentguard action`, `/agentguard patrol`, `/agentguard trust`, `/agentguard report`, `/agentguard config`, `/agentguard checkup`, `/agentguard checkup --json`, or natural-language requests like "run agentguard checkup" through the packaged CLI. Those are this skill's higher-level workflows. Only use the packaged CLI checkup path when the user includes `--against-advisory <id>` or explicitly writes `/agentguard cli checkup ...`.
 
 If the user writes `/agentguard checkup --against-advisory <id>`, use the CLI command `agentguard checkup --against-advisory <id>` instead of the comprehensive HTML health-report workflow.