From 9a07fd83fbd30d44d43af2918cc12bef60b3f8eb Mon Sep 17 00:00:00 2001 From: George Zhang Date: Sun, 29 Mar 2026 10:50:44 -0700 Subject: [PATCH] docs(plugins): describe before_install policy foundation --- CHANGELOG.md | 2 +- docs/automation/hooks.md | 12 ++++++++---- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bbb5c91525..209e08daf71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ Docs: https://docs.openclaw.ai - LINE/outbound media: add LINE image, video, and audio outbound sends on the LINE-specific delivery path, including explicit preview/tracking handling for videos while keeping generic media sends on the existing image-only route. (#45826) Thanks @masatohoshino. - WhatsApp/reactions: agents can now react with emoji on incoming WhatsApp messages, enabling more natural conversational interactions like acknowledging a photo with ❤️ instead of typing a reply. Thanks @mcaxtr. - MCP: add remote HTTP/SSE server support for `mcp.servers` URL configs, including auth headers and safer config redaction for MCP credentials. (#50396) Thanks @dhananjai1729. -- Plugins/hooks: add a `before_install` hook so external security scanners and policy engines can inspect built-in install scan findings, add their own warnings, and block skill or plugin installs. (#56050) thanks @odysseus0. +- Plugins/hooks: add a `before_install` hook with structured request provenance, built-in scan status, and install-target metadata so external security scanners and policy engines can review and block skill, plugin package, plugin bundle, and single-file plugin installs. (#56050) thanks @odysseus0. ### Fixes diff --git a/docs/automation/hooks.md b/docs/automation/hooks.md index af1660cc57d..4fa54202b6b 100644 --- a/docs/automation/hooks.md +++ b/docs/automation/hooks.md @@ -497,7 +497,7 @@ If the gateway is unavailable or does not support plugin approvals, the tool cal #### before_install -Runs after the built-in install security scan and before installation continues. OpenClaw fires this hook for interactive skill installs as well as plugin bundle/package installs. +Runs after the built-in install security scan and before installation continues. OpenClaw fires this hook for interactive skill installs as well as plugin bundle, package, and single-file installs. Return fields: @@ -509,9 +509,13 @@ Event fields: - **`targetType`**: Install target category (`skill` or `plugin`) - **`targetName`**: Human-readable skill name or plugin id for the install target -- **`sourceDir`**: Absolute path to the source directory being scanned -- **`source`**: Install origin when available (for example `openclaw-bundled`, `openclaw-workspace`, `plugin-bundle`, or `plugin-package`) -- **`builtinFindings`**: Findings already produced by the built-in scanner +- **`sourcePath`**: Absolute path to the install target content being scanned +- **`sourcePathKind`**: Whether the scanned content is a `file` or `directory` +- **`source`**: Normalized install origin when available (for example `openclaw-bundled`, `openclaw-workspace`, `plugin-bundle`, `plugin-package`, or `plugin-file`) +- **`request`**: Provenance for the install request, including `kind`, `mode`, and optional `requestedSpecifier` +- **`builtinScan`**: Structured result of the built-in scanner, including `status`, summary counts, findings, and optional `error` +- **`skill`**: Skill install metadata when `targetType` is `skill`, including `installId` and the selected `installSpec` +- **`plugin`**: Plugin install metadata when `targetType` is `plugin`, including the canonical `pluginId`, normalized `contentType`, optional `packageName` / `manifestId` / `version`, and `extensions` Decision semantics: