@f4bioo/berry-shield 2026.3.3-2 → 2026.3.17

package/docs/wiki/deploy/installation.md

@@ -34,6 +34,16 @@ Practical rule:
 For official OpenClaw plugin installation behavior, see:
 - https://docs.openclaw.ai/tools/plugin
 
+## Host hook note
+
+OpenClaw host behavior can influence prompt-level guidance hooks used by Berry Shield.
+
+Operational note:
+- if the host explicitly disables plugin prompt-injection style prepend behavior for hooks, `Berry.Root` and Vine reminder guidance from `before_agent_start` can be partially degraded.
+
+See more:
+- [Technical limitations and host behavior](../../../README.md#-technical-limitations--sdk-diary)
+
 
 ### Quick navigation
 

package/docs/wiki/layers/root.md

@@ -98,6 +98,8 @@ Root is useful for:
 ## Limits and caveats
 
 - Root is instruction-level control, not hard execution enforcement.
+- If the host disables prompt-injection style prepend behavior for plugin hooks, Root guidance can be partially degraded because `before_agent_start` context may no longer be injected.
+- This is a host/runtime constraint, not a full Berry Shield plugin failure.
 - If runtime context identity is missing, global safety fallback can increase policy verbosity.
 - Excessive full injections increase token cost.
 - Too little reinjection can reduce model adherence in long sessions.

package/docs/wiki/layers/stem.md

@@ -24,6 +24,7 @@ The tool evaluates operation intent (exec, read, write) against destructive-comm
   - sensitive file access in read/write requests
 - Emits structured audit events in both audit and enforce paths.
 - Returns allow/deny response payloads to the agent.
+- Returns the standard `CONFIRM_REQUIRED` challenge when Vine risk is active, even if host/runtime identity is degraded.
 - Triggers adaptive escalation signaling on enforce denies.
 
 ## What Stem does not do
@@ -40,10 +41,11 @@ flowchart TD
     A[Agent requests gate check] --> B[Berry.Stem]
     B --> C{Input valid?}
     C -->|No| E[Reject request]
-    C -->|Yes| D{Risk match?}
+    C -->|Yes| D{Policy or Vine risk?}
     D -->|No| ALLOW[Return ALLOWED]
-    D -->|Yes + audit| WB[Emit would_block event]
-    D -->|Yes + enforce| DENY[Return DENIED + blocked event]
+    D -->|Yes + audit| WB[Emit would_block or would_confirm_required]
+    D -->|Yes + confirm| CONFIRM[Return CONFIRM_REQUIRED]
+    D -->|Yes + deny| DENY[Return DENIED + blocked event]
     WB --> ALLOW
     DENY --> ESC[Adaptive escalation signal]
 ```

package/docs/wiki/layers/vine.md

@@ -13,6 +13,18 @@ Berry.Vine is the **external-content trust guard layer**.
 
 It reduces prompt-injection risk by treating external content as untrusted by default and enforcing trust-aware checks before sensitive operations.
 
+## Philosophy
+
+Vine is designed to act as a **pause layer**, not as a hard isolation barrier.
+
+Its job is to slow down risky external-content-driven flows long enough to require visible human intent before the agent continues with a sensitive action.
+
+Operationally, this means:
+- prefer an explicit confirmation pause over a silent allow when external risk is active;
+- avoid turning degraded binding or imperfect session identity into a hard product lockout by default;
+- use confirmation as the pragmatic fallback when the host/runtime context is incomplete but the channel can still support a human pause;
+- keep the focus on interrupting unsafe momentum, not on pretending Vine is a complete antivirus-style boundary.
+
 ## What Vine does
 
 - Tracks external-risk signals per session.
@@ -29,6 +41,32 @@ It reduces prompt-injection risk by treating external content as untrusted by de
 - It does not rely on semantic AI classification.
 - It does not auto-remediate without explicit operator action.
 
+## Confirmation strategies
+
+Vine supports two confirmation strategies for sensitive actions under active external risk:
+
+- `one_to_one` (`1:1`): one human confirmation code is consumed by one sensitive action.
+- `one_to_many` (`1:N`): one human confirmation code can unlock multiple sensitive actions within a short bounded window.
+
+Operational default:
+- `one_to_many` is the default strategy.
+
+Important fields:
+- code TTL: how long a challenge code remains valid.
+- confirmation window: how long the `1:N` execution window stays open after approval.
+- max actions per window: how many sensitive actions the `1:N` approval can unlock inside that window.
+- max attempts: how many invalid confirmation attempts are tolerated before the challenge is exhausted.
+
+High-level confirmation flow:
+- Berry detects active external-risk state.
+- A sensitive action is evaluated through `berry_check` or `before_tool_call`.
+- Vine emits a confirmation challenge when human intent must be made explicit.
+- Human approval unlocks the real action according to the configured strategy.
+
+Degraded path:
+- if native binding or session identity is degraded, Berry still uses the normal `CONFIRM_REQUIRED` code-based challenge instead of silently allowing the action;
+- degraded identity may reduce correlation precision, but it does not change the public confirmation protocol.
+
 ## Runtime flow
 
 ```mermaid
@@ -61,6 +99,7 @@ Key operational rule:
 ### Enforce
 - Sensitive actions under active external risk can be blocked.
 - In strict profile, unknown-origin sensitive attempts can also block.
+- When native confirmation binding is degraded, Berry still uses the same explicit code-based confirmation flow instead of silently allowing the action.
 
 ### Audit
 - No hard block.
@@ -129,6 +168,7 @@ Important scope:
 ## Limits and caveats
 
 - Hook timing and availability still depend on host runtime behavior.
+- If the host disables prompt-injection style context prepend for plugin hooks, Vine reminder text from `before_agent_start` can be neutralized even though risk tracking and action guarding still exist.
 - Unknown-origin classification can create false positives if over-tuned.
 - Risk decay should not depend only on elapsed time.
 

package/docs/wiki/operation/cli/README.md

@@ -96,6 +96,13 @@ openclaw bshield vine set mode strict
 ```
 Expected: CLI confirms strict Vine mode for external-content guard behavior.
 
+### 9) Inspect or change Vine confirmation strategy
+Use this when you need to verify or switch between `1:1` and `1:N` confirmation behavior.
+```bash
+openclaw bshield vine confirmation
+```
+Expected: CLI opens the interactive selector for Vine confirmation strategy.
+
 ## Documentation structure
 
 Each command page follows the same structure:

package/docs/wiki/operation/cli/status.md

@@ -16,6 +16,7 @@ Show the effective Berry Shield runtime state resolved from OpenClaw plugin conf
 - Prints current plugin state (`Status`, `Mode`, and rule counters).
 - Prints policy state (`Profile`, adaptive values, and global escalation toggle).
 - Prints Vine state (`Mode`, thresholds, retention, and allowlist size).
+- Prints Vine confirmation state (`Confirmation Strategy`, active strategy marker, TTL, attempts, and window values).
 - Prints each security layer status as `ACTIVE` or `OFF`.
 
 ## When to use
@@ -63,6 +64,17 @@ Result expected:
 - Thresholds and retention values match expected operational tuning.
 - `Allowlist` shows the number of exempt tools.
 
+### Vine Confirmation section
+Command for this check: `openclaw bshield status`.
+Result expected:
+- `Confirmation Strategy` shows the configured runtime contract (`1:1` or `1:N`).
+- `1:1` and `1:N` show which strategy is currently `ACTIVE`.
+- `Code TTL (sec)` shows how long the challenge code remains valid.
+- `Max Attempts` shows how many invalid confirmation tries are tolerated.
+- `Window (sec)` and `Max Actions/Window` matter primarily for `1:N`.
+- `Window (sec)` is the active multi-action approval window after a successful confirmation.
+- `Max Actions/Window` is the maximum number of sensitive actions that one `1:N` approval can unlock inside that window.
+
 ### Security layers section
 Command for this check: `openclaw bshield status`.
 Result expected:

package/docs/wiki/operation/cli/vine.md

@@ -16,6 +16,7 @@ Manage Berry.Vine configuration and tool allowlist from CLI.
 - Writes deterministic Vine paths (set).
 - Adds one tool to Vine allowlist (allow).
 - Removes one tool from Vine allowlist (deny).
+- Opens the interactive confirmation-strategy selector (confirmation).
 
 ## When to use
 - Before smoke tests that need strict/balanced Vine behavior.
@@ -80,6 +81,21 @@ Supported `set` paths:
 - `thresholds.forcedGuardTurns` (integer `>= 1`)
 - `retention.maxEntries` (integer `>= 1`)
 - `retention.ttlSeconds` (integer `>= 1`)
+- `confirmation.strategy` (`one_to_one | one_to_many`)
+- `confirmation.codeTtlSeconds` (integer `>= 1`)
+- `confirmation.maxAttempts` (integer `>= 1`)
+- `confirmation.windowSeconds` (integer `>= 1`)
+- `confirmation.maxActionsPerWindow` (integer `>= 1`)
+
+Confirmation strategy meanings:
+- `one_to_one` (`1:1`): one code unlocks one sensitive action.
+- `one_to_many` (`1:N`): one code can unlock multiple sensitive actions inside the active confirmation window.
+
+Default:
+- `one_to_many` is the default confirmation strategy.
+
+Operational note:
+- if host/runtime binding is degraded, Vine still uses the same visible code-based confirmation flow without changing the configured confirmation strategy itself.
 
 ## Tuning guide
 
@@ -139,6 +155,20 @@ openclaw bshield vine set thresholds.forcedGuardTurns 2
 ```
 Result: CLI confirms forced guard turns updated.
 
+### Switch confirmation strategy to one-to-one
+Use this when every sensitive action must consume its own confirmation.
+```bash
+openclaw bshield vine set confirmation.strategy one_to_one
+```
+Result: CLI confirms `confirmation.strategy = one_to_one`.
+
+### Open interactive confirmation strategy selector
+Use this when you prefer the TTY selector with `1:1` and `1:N` labels.
+```bash
+openclaw bshield vine confirmation
+```
+Result: CLI opens the interactive selector and updates strategy after confirmation.
+
 ### Allowlist one tool
 Use this when one trusted tool should not trigger Vine escalation.
 ```bash
@@ -180,6 +210,13 @@ openclaw bshield vine set thresholds.forcedGuardTurns zero
 ```
 Expected: CLI fails with integer validation message.
 
+### Invalid confirmation strategy value
+Use this check when a direct confirmation strategy write uses an unsupported value.
+```bash
+openclaw bshield vine set confirmation.strategy invalid
+```
+Expected: CLI fails and prints the allowed confirmation strategies.
+
 ## Related commands
 - [index](README.md)
 - [status](status.md)

package/docs/wiki/tutorials/README.md

@@ -16,6 +16,7 @@ Use these pages when you want guided execution rather than command reference.
 
 - [secure session](secure-session.md): end-to-end first session with verification checkpoints
 - [choose your profile](choose-profile.md): decide strict/balanced/minimal with practical checks
+- [choose your Vine confirmation strategy](choose-vine-confirmation.md): decide when to use `1:1` or `1:N`
 - [tune policy](tune-policy.md): configure adaptive and retention values safely
 - [build custom rules](build-custom-rules.md): add, test, list, and remove organization-specific rules
 - [audit-to-enforce rollout](audit-to-enforce-rollout.md): move from observation to active mitigation

package/docs/wiki/tutorials/choose-vine-confirmation.md

@@ -0,0 +1,94 @@
+---
+summary: "Choose the right Vine confirmation strategy for external-risk workflows"
+read_when:
+  - You are deciding between one-to-one and one-to-many confirmation
+  - You want a practical Vine baseline before smoke tests or rollout
+  - You need to verify confirmation behavior from CLI and status output
+title: "Choose Your Vine Confirmation Strategy"
+---
+
+# `Choose Your Vine Confirmation Strategy`
+
+This tutorial helps you choose and validate the Vine confirmation strategy without editing low-level config files.
+Use it when you need a predictable human pause after external-content risk becomes active.
+
+## Prerequisites
+
+- Berry Shield installed and enabled
+- Access to run `openclaw bshield` commands
+- Vine layer enabled in the active runtime
+
+## Step 1: Inspect current confirmation state
+
+Use this command to inspect the active Vine confirmation strategy before changing anything.
+```bash
+openclaw bshield status
+```
+Expected:
+- `Vine Confirmation` section is visible
+- `Confirmation Strategy` is shown as `ONE_TO_ONE` or `ONE_TO_MANY`
+
+## Step 2: Start with the default strategy
+
+Use this command when you want the recommended general-purpose confirmation baseline.
+```bash
+openclaw bshield vine set confirmation.strategy one_to_many
+```
+Expected:
+- CLI confirms `confirmation.strategy = one_to_many`
+
+## Step 3: Verify the runtime state
+
+Use this command to confirm the strategy is visible in status output.
+```bash
+openclaw bshield status
+```
+Expected:
+- `Confirmation Strategy` is `ONE_TO_MANY`
+- `ONE_TO_MANY` is marked `ACTIVE`
+
+## Step 4: Try the interactive selector
+
+Use this command when you want the TTY selector with `1:1` and `1:N` labels.
+```bash
+openclaw bshield vine confirmation
+```
+Expected:
+- CLI opens the confirmation strategy selector
+
+## Step 5: Switch to one-to-one when every action must pause
+
+Use this command when each sensitive action should require its own human confirmation.
+```bash
+openclaw bshield vine set confirmation.strategy one_to_one
+```
+Expected:
+- CLI confirms `confirmation.strategy = one_to_one`
+
+## Step 6: Return to one-to-many for smoother operator flow
+
+Use this command when you want one confirmation to unlock a short bounded sequence of sensitive actions.
+```bash
+openclaw bshield vine set confirmation.strategy one_to_many
+```
+Expected:
+- CLI confirms `confirmation.strategy = one_to_many`
+
+## Decision guide
+
+- Choose `one_to_one` (`1:1`) when every sensitive action should stop and wait for a new human confirmation.
+- Choose `one_to_many` (`1:N`) when the goal is to insert one visible human pause and then allow a short bounded sequence of related sensitive actions.
+- Keep `one_to_many` as the default when operator experience matters and the bounded window is acceptable.
+- Use `one_to_one` for higher-friction validation sessions or when you want the clearest action-by-action audit trail.
+
+## Related pages
+- [tutorial index](README.md)
+- [Vine layer reference](../layers/vine.md)
+- [vine command reference](../operation/cli/vine.md)
+- [status command reference](../operation/cli/status.md)
+
+---
+
+## Navigation
+- [Back to Tutorials Index](README.md)
+- [Back to Wiki Index](../README.md)

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
     "id": "berry-shield",
     "name": "Berry Shield",
     "description": "Security plugin that helps to block destructive commands, redact secrets and PII",
-    "version": "2026.3.3-2",
+    "version": "2026.3.17",
     "configSchema": {
         "type": "object",
         "additionalProperties": false,
@@ -173,6 +173,46 @@
                         },
                         "default": [],
                         "description": "Tool names exempt from Vine escalation"
+                    },
+                    "confirmation": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "description": "Confirmation flow tuning for sensitive actions under Vine risk",
+                        "properties": {
+                            "strategy": {
+                                "type": "string",
+                                "enum": [
+                                    "one_to_one",
+                                    "one_to_many"
+                                ],
+                                "default": "one_to_many",
+                                "description": "Confirmation strategy: 1:1 = one code per action, 1:N = one code for multiple actions within a short window"
+                            },
+                            "codeTtlSeconds": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "default": 180,
+                                "description": "Confirmation code time-to-live in seconds"
+                            },
+                            "maxAttempts": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "default": 3,
+                                "description": "Maximum invalid code attempts per challenge"
+                            },
+                            "windowSeconds": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "default": 120,
+                                "description": "Window lifetime in seconds when strategy is 1:N"
+                            },
+                            "maxActionsPerWindow": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "default": 3,
+                                "description": "Maximum sensitive actions allowed during 1:N confirmation window"
+                            }
+                        }
                     }
                 }
             },
@@ -290,4 +330,4 @@
             "sensitive": false
         }
     }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f4bioo/berry-shield",
-  "version": "2026.3.3-2",
+  "version": "2026.3.17",
   "description": "OpenClaw plugin for policy checks, command/file blocking, and sensitive-data redaction.",
   "keywords": [
     "openclaw",
@@ -24,7 +24,7 @@
   },
   "homepage": "https://github.com/F4bioo/berry-shield#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.16.0"
   },
   "type": "module",
   "files": [
@@ -44,27 +44,32 @@
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
+    "pretest": "npm run plugin:manifest:sync",
     "typecheck": "tsc --noEmit",
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:openclaw/plugin-sdk --target=node20",
+    "pretypecheck": "npm run plugin:manifest:sync",
+    "plugin:manifest:sync": "node scripts/sync-manifest.mjs",
+    "prebuild": "npm run plugin:manifest:sync",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:openclaw/plugin-sdk --target=node22",
     "build:types": "tsc -p tsconfig.build.json",
     "//release": "Preflight gates run before version bump",
-    "release:preflight": "npm run build && npm run typecheck && npm test && npm run wiki:claim",
+    "prerelease:preflight": "npm run plugin:manifest:sync",
+    "release:preflight": "npm run typecheck && npm test && npm run build && npm run wiki:claim",
     "release": "npm run release:preflight && npm run version:update",
     "version:update": "npx ts-node --esm scripts/update-version.ts",
     "update-patterns": "npx ts-node --esm scripts/update-patterns.ts",
     "wiki:claim": "npx ts-node --esm scripts/doc-sanity.ts"
   },
   "peerDependencies": {
-    "openclaw": "^2026.2.3-1"
+    "openclaw": "^2026.3.12"
   },
   "dependencies": {
-    "@clack/prompts": "^0.7.0"
+    "@clack/prompts": "^1.0.1"
   },
   "devDependencies": {
     "@iarna/toml": "^2.2.5",
     "@types/node": "^25.2.2",
-    "esbuild": "^0.27.3",
+    "esbuild": "^0.27.4",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }