@goplus/agentguard 1.1.20 → 1.1.27

package/docs/cloud-connect.md

@@ -1,6 +1,6 @@
 # Connect AgentGuard OSS to AgentGuard Cloud
 
-AgentGuard is local-first. Cloud is optional and adds hosted policy, redacted audit sync, session timelines, and approval workflows.
+AgentGuard is local-first. Cloud is optional and adds hosted policy, redacted audit sync, and session timelines.
 
 ## Install and initialize
 
@@ -13,12 +13,25 @@ This creates `~/.agentguard/config.json`, `~/.agentguard/audit.jsonl`, and local
 
 ## Connect Cloud
 
+OpenClaw users can connect without an API key after initialization:
+
+```bash
+agentguard init --agent openclaw
+agentguard connect
+```
+
+In this mode, `connect` registers a local Agent JWT, prints an activation link,
+and may send that link to the latest OpenClaw channel. Open the link to bind the
+local agent to your AgentGuard account.
+
+API-key auth is also supported:
+
 ```bash
 AGENTGUARD_API_KEY=ag_live_xxxxx \
   agentguard connect --url https://agentguard.gopluslabs.io
 ```
 
-`connect` stores the API key locally, fetches `/api/v1/policies/effective`, and caches the policy. If Cloud is unavailable, AgentGuard keeps enforcing with cached policy or the bundled default policy.
+With API-key auth, `connect` stores the API key locally, fetches `/api/v1/policies/effective`, and caches the policy. With Agent JWT auth, `connect` stores the local agent credential instead of an API key. If Cloud is unavailable, AgentGuard keeps enforcing with cached policy or the bundled default policy.
 
 Prefer `AGENTGUARD_API_KEY` or an ignored `.env.local` file over passing secrets as CLI flags, because shell history can persist command-line arguments.
 
@@ -28,7 +41,7 @@ Prefer `AGENTGUARD_API_KEY` or an ignored `.env.local` file over passing secrets
 2. AgentGuard evaluates locally by default.
 3. Local audit is written to `~/.agentguard/audit.jsonl`.
 4. Connected clients sync redacted audit events to `/api/v1/events/ingest`.
-5. `require_approval` creates `/api/v1/approvals` and blocks the action until reviewed.
+5. `require_approval` is handled by the agent host's native permission channel when one is available. If the host cannot safely resume an approved call, AgentGuard blocks locally and asks the user to retry only after intentionally changing local policy.
 
 Use `AGENTGUARD_DECISION_MODE=cloud` or `agentguard protect --decision-mode cloud` only when Cloud should be authoritative for a specific hook.
 

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,17 @@ 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
+```
+
+Show that command to the user before running it. Run it only after the user
+explicitly approves that exact action; do not let the agent approve its own
+blocked command proactively. 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,26 @@ 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
+```
+
+Show that command to the user before running it. Run it only after the user
+explicitly approves that exact action; do not let the agent approve its own
+blocked command proactively. 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.20",
+  "version": "1.1.27",
   "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

@@ -103,6 +103,8 @@ Supported CLI commands and options:
 | `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 |
@@ -117,6 +119,8 @@ Connect behavior:
 
 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. Show the exact approval command to the user before running it. Never run an approval command proactively, and never infer approval from context or from the agent's own plan. 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 only after the user has seen the command and understands which action is being approved. 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.