openclaw-plugin-exec-grant 1.0.0

package/index.ts

@@ -0,0 +1,57 @@
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+const SCRIPTS_DIR = join(__dirname, "skills", "exec-grant", "scripts");
+
+function runScript(name: string, args: string[] = []): string {
+  const scriptPath = join(SCRIPTS_DIR, name);
+  try {
+    return execFileSync("bash", [scriptPath, ...args], {
+      encoding: "utf-8",
+      timeout: 30_000,
+    }).trim();
+  } catch (err: any) {
+    const stderr = err.stderr?.toString().trim() || "";
+    const stdout = err.stdout?.toString().trim() || "";
+    return stderr || stdout || `Script ${name} failed with exit code ${err.status}`;
+  }
+}
+
+export default function register(api: any) {
+  api.registerCommand({
+    name: "grant",
+    description: "Activate time-boxed elevated shell access (admin only)",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler(ctx: any) {
+      const minutes = ctx.args?.trim();
+      if (!minutes || !/^\d+$/.test(minutes)) {
+        return { text: "Usage: /grant <minutes>  (1-120)" };
+      }
+      const result = runScript("grant.sh", [minutes]);
+      return { text: result };
+    },
+  });
+
+  api.registerCommand({
+    name: "revoke",
+    description: "Revoke elevated shell access immediately (admin only)",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler() {
+      const result = runScript("revoke.sh");
+      return { text: result };
+    },
+  });
+
+  api.registerCommand({
+    name: "grant-status",
+    description: "Check current grant state and remaining time",
+    acceptsArgs: false,
+    requireAuth: false,
+    handler() {
+      const result = runScript("status.sh");
+      return { text: result };
+    },
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,24 @@
+{
+  "id": "exec-grant",
+  "name": "Exec Grant",
+  "description": "Time-boxed elevated shell access with WhatsApp admin approval",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "adminPhone": {
+        "type": "string",
+        "description": "E.164 phone number of the admin who approves grants"
+      }
+    },
+    "required": ["adminPhone"],
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "adminPhone": {
+      "label": "Admin Phone (E.164)",
+      "placeholder": "+16505551234"
+    }
+  },
+  "skills": ["skills/exec-grant"]
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "openclaw-plugin-exec-grant",
+  "version": "1.0.0",
+  "description": "Time-boxed elevated shell access with WhatsApp admin approval for OpenClaw",
+  "main": "index.ts",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "security",
+    "exec",
+    "grant",
+    "whatsapp"
+  ],
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "skills/"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "install": {
+      "npmSpec": "openclaw-plugin-exec-grant",
+      "defaultChoice": "npm"
+    }
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.0.0"
+  }
+}

package/skills/exec-grant/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: exec-grant
+description: This skill should be used when a shell command is blocked by allowlist security, when the agent needs elevated access to run commands, when the agent encounters "permission denied" or "command not allowed" errors, or when the agent needs to request temporary full shell access from the admin.
+version: 1.0.0
+---
+
+# Exec Grant -- Time-Boxed Elevated Shell Access
+
+## Overview
+
+This skill provides the workflow for requesting, monitoring, and working within time-boxed elevated shell access grants. When operating under allowlist security mode, certain commands will be blocked. Rather than failing silently or attempting workarounds, request explicit admin approval for a time-limited window of full shell access.
+
+## When to Use
+
+Activate this skill when:
+- A shell command fails due to allowlist restrictions
+- A task requires commands not on the current allowlist
+- The agent needs temporary elevated privileges to complete work
+
+## Core Workflow
+
+### 1. Request Elevated Access
+
+When a command is blocked, estimate how much time the task requires and call:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/exec-grant/scripts/request.sh <minutes> "<reason>"
+```
+
+- `minutes`: Time needed (1-120). Round up to the nearest 5-minute increment.
+- `reason`: Clear, specific justification. Include the blocked command and what it accomplishes.
+
+Example:
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/exec-grant/scripts/request.sh 15 "Need to run docker compose and curl for API integration testing"
+```
+
+After calling request.sh, **wait for admin approval**. Do not proceed with blocked commands until status shows "active".
+
+### 2. Check Grant Status
+
+To check whether a grant is active, pending, or expired:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/exec-grant/scripts/status.sh
+```
+
+Possible states:
+- **active** -- Full shell access is available. Output includes remaining time.
+- **pending** -- Approval request sent, waiting for admin reply.
+- **inactive** -- No grant. Commands are restricted to the allowlist.
+
+### 3. Work Within the Grant Window
+
+Once active, execute the required commands promptly. Monitor remaining time by calling status.sh periodically during long tasks. If the grant expires mid-task:
+
+1. Stop executing privileged commands immediately
+2. Assess remaining work
+3. Request a **new** grant with justification for the additional time needed
+
+### 4. Grant Expiration
+
+Grants auto-revoke via an OS-level timer. When revoked, security returns to allowlist mode. There is no way to extend an active grant -- request a new one if more time is needed.
+
+## Critical Rules
+
+- **Never modify `~/.openclaw/exec-approvals.json` directly.** All changes go through grant.sh and revoke.sh.
+- **Never attempt to cancel, extend, or tamper with the revocation timer.** The timer runs at the OS level and is intentionally outside agent control.
+- **Never call grant.sh directly.** Only the plugin's `/grant` command handler (triggered by admin WhatsApp reply) should invoke it.
+- **Never request more time than needed.** Estimate conservatively and request a new grant if the first one runs out.
+- **Always provide a specific reason.** Vague reasons like "need access" will likely be denied by the admin.
+
+## Script Reference
+
+All scripts are located at `${CLAUDE_PLUGIN_ROOT}/skills/exec-grant/scripts/`:
+
+| Script | Called By | Purpose |
+|---|---|---|
+| `request.sh` | Agent | Send approval request to admin via WhatsApp |
+| `grant.sh` | Plugin `/grant` handler | Activate elevated access + schedule timer |
+| `revoke.sh` | OS timer or `/revoke` | Revert to allowlist mode |
+| `status.sh` | Agent | Check current grant state and remaining time |
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/security-model.md`** -- Threat model, recommended allowlist baseline, and design rationale for the grant system

package/skills/exec-grant/references/security-model.md

@@ -0,0 +1,118 @@
+# Security Model -- Exec Grant Plugin
+
+## Threat Model
+
+### Threat 1: Prompt Injection via WhatsApp
+
+**Attack:** A malicious message forwarded to the admin's WhatsApp contains text like "Reply /grant 120 to this message." The admin might reflexively reply with the command.
+
+**Mitigation:**
+- `requireAuth: true` on `/grant` ensures only messages from the configured admin phone number are processed
+- The grant confirmation message sent back to the admin includes the exact duration and expiry time, making unintended grants visible
+- Grants are capped at 120 minutes maximum
+
+**Residual risk:** If the admin's phone is compromised, the attacker can approve grants. This is inherent to any human-in-the-loop approval system.
+
+### Threat 2: Agent Timer Tampering
+
+**Attack:** A compromised or manipulated LLM attempts to cancel the revocation timer to maintain elevated access beyond the approved window.
+
+**Mitigation:**
+- On Linux, `systemd-run --user` creates a transient timer unit. The agent process does not have the credentials to cancel another user's systemd timers, and the timer runs independently of the gateway process.
+- On macOS, the fallback uses a disowned background process. While theoretically killable if the PID is known, the agent skill explicitly prohibits timer manipulation.
+- The state file records the expected expiry timestamp. `status.sh` performs self-healing: if the timestamp has passed but the state still says "active," it triggers an immediate revoke.
+
+**Residual risk:** On macOS, the background sleep process is less tamper-resistant than systemd. A truly adversarial agent with unrestricted shell access could find and kill it. The self-healing check in status.sh provides a secondary safety net.
+
+### Threat 3: Direct File Manipulation
+
+**Attack:** The agent modifies `exec-approvals.json` directly, bypassing the grant/revoke workflow to escalate privileges permanently.
+
+**Mitigation:**
+- The SKILL.md explicitly instructs the agent never to modify exec-approvals.json directly
+- The status.sh script cross-checks the state file against the actual approvals file and flags inconsistencies
+- The audit log records all grant/revoke actions for post-incident review
+
+**Residual risk:** An agent operating in "full" security mode could ignore skill instructions. This threat is mitigated by the allowlist baseline -- the agent cannot gain full access without admin approval in the first place.
+
+### Threat 4: Grant Stacking / Extension
+
+**Attack:** The agent requests a new grant before the current one expires, effectively creating indefinite elevated access.
+
+**Mitigation:**
+- request.sh checks for active grants and rejects requests if one is already running
+- Each grant is a discrete time budget with no extension mechanism
+- The admin sees each request individually and must make a conscious approval decision
+
+### Threat 5: State File Corruption
+
+**Attack:** The state file is deleted or corrupted, causing the system to lose track of an active grant.
+
+**Mitigation:**
+- revoke.sh operates on exec-approvals.json directly, not just the state file. Even if the state file is lost, the timer still fires and revokes access.
+- status.sh detects inconsistencies between the state file and the actual approvals file
+
+## Recommended Allowlist Baseline
+
+For routine operations, the allowlist in `exec-approvals.json` should permit:
+
+```json
+{
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "allowlist": [
+        "ls", "cat", "head", "tail", "wc", "grep", "find", "file",
+        "echo", "printf", "date", "whoami", "pwd",
+        "git status", "git log", "git diff", "git show",
+        "node --version", "npm --version", "python3 --version",
+        "openclaw config get", "openclaw message send",
+        "jq", "sed", "awk", "sort", "uniq", "tr", "cut"
+      ]
+    }
+  }
+}
+```
+
+This baseline allows:
+- **File inspection** -- reading files, listing directories, searching content
+- **Git read operations** -- viewing history, diffs, and status (not push/pull/commit)
+- **Version checks** -- verifying tool availability
+- **OpenClaw operations** -- reading config and sending messages (needed by this plugin)
+- **Text processing** -- jq, sed, awk for data manipulation
+
+Commands that typically require a grant:
+- `docker`, `docker compose` -- container management
+- `curl`, `wget` -- network requests
+- `npm install`, `pip install` -- package installation
+- `git push`, `git commit` -- repository mutations
+- `systemctl`, `service` -- service management
+- `rm`, `mv`, `cp` -- file mutations
+- `ssh`, `scp` -- remote access
+- `sudo` -- privilege escalation
+
+## Design Rationale
+
+### Why OS-Level Timers
+
+The revocation timer must be something the agent cannot prevent. If the timer ran inside the gateway process (e.g., `setTimeout`), a compromised agent could theoretically influence it. systemd-run creates an independent OS-level scheduled task that executes regardless of the gateway's state.
+
+### Why Targeted jq Edits
+
+On revoke, the script only sets `.agents.main.security = "allowlist"` rather than restoring a saved snapshot. This preserves any allowlist modifications the admin made during the grant window. A snapshot-restore approach would silently discard those changes.
+
+### Why No Auto-Extension
+
+Requiring a fresh approval for each time window prevents "approval fatigue creep" -- a pattern where automated extension requests become rubber-stamped. Each grant is a discrete, conscious decision by the admin.
+
+### Why State File + Approvals File
+
+Two separate files serve different purposes:
+- `exec-approvals.json` is the source of truth for the gateway's security enforcement
+- `exec-grant-state.json` tracks the grant lifecycle (pending/active/revoked) and provides metadata for the agent and admin
+
+This separation means the gateway does not need to understand grant semantics -- it only checks the security field.
+
+### Why WhatsApp as the Approval Channel
+
+WhatsApp provides an out-of-band approval channel that the agent cannot impersonate. The admin receives requests on their phone, can evaluate context, and responds with a simple command. This is preferable to in-band approval (e.g., a web UI the agent could potentially interact with).

package/skills/exec-grant/scripts/grant.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# grant.sh -- Called by plugin /grant handler: activates elevated access + timer
+# Usage: grant.sh <minutes>
+set -euo pipefail
+
+# Ensure openclaw is on PATH (npm global bin may not be in non-interactive shells)
+for p in "$HOME/.npm-global/bin" "$HOME/.local/bin" "$HOME/node_modules/.bin"; do
+  [[ -d "$p" ]] && export PATH="$p:$PATH"
+done
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+STATE_FILE="$HOME/.openclaw/exec-grant-state.json"
+APPROVALS_FILE="$HOME/.openclaw/exec-approvals.json"
+AUDIT_LOG="$HOME/.openclaw/exec-grant-audit.log"
+
+# --- Arg validation ---
+if [[ $# -lt 1 ]]; then
+  echo "Usage: grant.sh <minutes>" >&2
+  exit 1
+fi
+
+MINUTES="$1"
+
+if ! [[ "$MINUTES" =~ ^[0-9]+$ ]] || [[ "$MINUTES" -lt 1 ]] || [[ "$MINUTES" -gt 120 ]]; then
+  echo "Error: minutes must be between 1 and 120" >&2
+  exit 1
+fi
+
+# --- Cross-platform date handling ---
+NOW=$(date +%s)
+SECONDS_TO_ADD=$(( MINUTES * 60 ))
+EXPIRY=$(( NOW + SECONDS_TO_ADD ))
+
+if date -v+1S +%s >/dev/null 2>&1; then
+  # macOS (BSD date)
+  EXPIRY_HUMAN=$(date -r "$EXPIRY" '+%Y-%m-%d %H:%M:%S %Z')
+else
+  # Linux (GNU date)
+  EXPIRY_HUMAN=$(date -d "@${EXPIRY}" '+%Y-%m-%d %H:%M:%S %Z')
+fi
+
+# --- Modify exec-approvals.json: set security to "full" ---
+mkdir -p "$(dirname "$APPROVALS_FILE")"
+
+if [[ ! -f "$APPROVALS_FILE" ]]; then
+  cat > "$APPROVALS_FILE" <<'ENDJSON'
+{
+  "agents": {
+    "main": {
+      "security": "allowlist"
+    }
+  }
+}
+ENDJSON
+fi
+
+# Targeted jq edit: only change .agents.main.security
+TEMP_FILE=$(mktemp)
+jq '.agents.main.security = "full"' "$APPROVALS_FILE" > "$TEMP_FILE" && mv "$TEMP_FILE" "$APPROVALS_FILE"
+
+# --- Schedule auto-revoke timer ---
+REVOKE_SCRIPT="${SCRIPT_DIR}/revoke.sh"
+TIMER_ID=""
+
+if command -v systemctl >/dev/null 2>&1 && systemctl --user status >/dev/null 2>&1; then
+  # Linux: systemd-run (tamper-resistant -- agent cannot cancel)
+  systemd-run --user \
+    --on-active="${MINUTES}m" \
+    --unit=exec-grant-revoke \
+    --description="Auto-revoke exec grant" \
+    -- bash "$REVOKE_SCRIPT" 2>/dev/null && TIMER_ID="systemd:exec-grant-revoke" || true
+fi
+
+if [[ -z "$TIMER_ID" ]] && [[ "$(uname)" == "Darwin" ]]; then
+  # macOS: launchd plist
+  PLIST_LABEL="com.openclaw.exec-grant-revoke"
+  PLIST_PATH="$HOME/Library/LaunchAgents/${PLIST_LABEL}.plist"
+  mkdir -p "$HOME/Library/LaunchAgents"
+
+  cat > "$PLIST_PATH" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${PLIST_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>${REVOKE_SCRIPT}</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>0</integer>
+    <key>LaunchOnlyOnce</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <false/>
+    <key>StandardOutPath</key>
+    <string>${HOME}/.openclaw/exec-grant-revoke.log</string>
+    <key>StandardErrorPath</key>
+    <string>${HOME}/.openclaw/exec-grant-revoke.log</string>
+</dict>
+</plist>
+PLIST
+
+  # Use a delayed start: unload any existing, then schedule via at-style workaround
+  launchctl unload "$PLIST_PATH" 2>/dev/null || true
+
+  # launchd doesn't have on-active like systemd; use sleep-based subprocess
+  (sleep "$SECONDS_TO_ADD" && bash "$REVOKE_SCRIPT") &
+  BG_PID=$!
+  disown "$BG_PID" 2>/dev/null || true
+  TIMER_ID="bg:${BG_PID}"
+
+  # Clean up the plist since we're using bg approach
+  rm -f "$PLIST_PATH"
+fi
+
+if [[ -z "$TIMER_ID" ]]; then
+  # Fallback: background sleep + revoke
+  (sleep "$SECONDS_TO_ADD" && bash "$REVOKE_SCRIPT") &
+  BG_PID=$!
+  disown "$BG_PID" 2>/dev/null || true
+  TIMER_ID="bg:${BG_PID}"
+fi
+
+# --- Write active state ---
+cat > "$STATE_FILE" <<ENDJSON
+{
+  "status": "active",
+  "granted_minutes": ${MINUTES},
+  "granted_at": ${NOW},
+  "expiry": ${EXPIRY},
+  "expiry_human": $(jq -n --arg v "$EXPIRY_HUMAN" '$v'),
+  "timer_id": $(jq -n --arg v "$TIMER_ID" '$v')
+}
+ENDJSON
+
+# --- Audit log ---
+echo "[$(date -u '+%Y-%m-%dT%H:%M:%SZ')] GRANT: ${MINUTES}m, expires ${EXPIRY_HUMAN}, timer=${TIMER_ID}" >> "$AUDIT_LOG"
+
+# --- Notify admin ---
+ADMIN_PHONE=$(openclaw config get plugins.entries.exec-grant.config.adminPhone 2>/dev/null | tail -1 | tr -d '[:space:]' || true)
+
+if [[ -n "$ADMIN_PHONE" ]]; then
+  MSG="Grant active for *${MINUTES}m*. Expires at ${EXPIRY_HUMAN}. Reply \`/revoke\` to end early."
+  openclaw message send --target "$ADMIN_PHONE" --channel whatsapp --message "$MSG" 2>/dev/null || true
+fi
+
+echo "Grant activated: ${MINUTES}m of full shell access. Expires at ${EXPIRY_HUMAN}."

package/skills/exec-grant/scripts/request.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# request.sh -- Agent-facing: sends WhatsApp approval request to admin
+# Usage: request.sh <minutes> "<reason>"
+set -euo pipefail
+
+# Ensure openclaw is on PATH (npm global bin may not be in non-interactive shells)
+for p in "$HOME/.npm-global/bin" "$HOME/.local/bin" "$HOME/node_modules/.bin"; do
+  [[ -d "$p" ]] && export PATH="$p:$PATH"
+done
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+STATE_FILE="$HOME/.openclaw/exec-grant-state.json"
+
+# --- Arg validation ---
+if [[ $# -lt 2 ]]; then
+  echo "Usage: request.sh <minutes> \"<reason>\"" >&2
+  exit 1
+fi
+
+MINUTES="$1"
+shift
+REASON="$*"
+
+if ! [[ "$MINUTES" =~ ^[0-9]+$ ]] || [[ "$MINUTES" -lt 1 ]] || [[ "$MINUTES" -gt 120 ]]; then
+  echo "Error: minutes must be between 1 and 120" >&2
+  exit 1
+fi
+
+if [[ -z "$REASON" ]]; then
+  echo "Error: reason is required" >&2
+  exit 1
+fi
+
+# --- Check for existing active grant ---
+if [[ -f "$STATE_FILE" ]]; then
+  STATUS=$(jq -r '.status // "inactive"' "$STATE_FILE" 2>/dev/null || echo "inactive")
+
+  if [[ "$STATUS" == "active" ]]; then
+    EXPIRY=$(jq -r '.expiry // 0' "$STATE_FILE")
+    NOW=$(date +%s)
+    if [[ "$NOW" -lt "$EXPIRY" ]]; then
+      REMAINING=$(( (EXPIRY - NOW + 59) / 60 ))
+      echo "Error: grant already active with ${REMAINING}m remaining. Use status.sh to check." >&2
+      exit 1
+    fi
+    # Expired but not cleaned up -- status.sh will self-heal
+  fi
+
+  if [[ "$STATUS" == "pending" ]]; then
+    REQUESTED_AT=$(jq -r '.requested_at // 0' "$STATE_FILE")
+    NOW=$(date +%s)
+    ELAPSED=$(( NOW - REQUESTED_AT ))
+    if [[ "$ELAPSED" -lt 300 ]]; then
+      echo "Error: approval request already pending (sent $(( ELAPSED ))s ago). Wait for admin response." >&2
+      exit 1
+    fi
+    # Stale pending request (>5m) -- allow re-request
+  fi
+fi
+
+# --- Get admin phone ---
+ADMIN_PHONE=$(openclaw config get plugins.entries.exec-grant.config.adminPhone 2>/dev/null | tail -1 | tr -d '[:space:]' || true)
+
+if [[ -z "$ADMIN_PHONE" ]]; then
+  echo "Error: no admin phone configured. Set plugins.entries.exec-grant.config.adminPhone" >&2
+  exit 1
+fi
+
+# --- Send WhatsApp approval request ---
+MSG="*Elevated Access Request*
+
+Agent requests *${MINUTES}m* of full shell access.
+
+*Reason:* ${REASON}
+
+Reply \`/grant ${MINUTES}\` to approve or ignore to deny."
+
+openclaw message send --target "$ADMIN_PHONE" --channel whatsapp --message "$MSG"
+
+# --- Write pending state ---
+mkdir -p "$(dirname "$STATE_FILE")"
+NOW=$(date +%s)
+
+cat > "$STATE_FILE" <<ENDJSON
+{
+  "status": "pending",
+  "requested_minutes": ${MINUTES},
+  "reason": $(jq -n --arg v "$REASON" '$v'),
+  "requested_at": ${NOW},
+  "admin_phone": $(jq -n --arg v "$ADMIN_PHONE" '$v')
+}
+ENDJSON
+
+echo "Approval request sent to admin. Waiting for /grant ${MINUTES} reply."

package/skills/exec-grant/scripts/revoke.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# revoke.sh -- Called by timer or /revoke: reverts to allowlist mode
+# Usage: revoke.sh
+set -euo pipefail
+
+# Ensure openclaw is on PATH (npm global bin may not be in non-interactive shells)
+for p in "$HOME/.npm-global/bin" "$HOME/.local/bin" "$HOME/node_modules/.bin"; do
+  [[ -d "$p" ]] && export PATH="$p:$PATH"
+done
+
+STATE_FILE="$HOME/.openclaw/exec-grant-state.json"
+APPROVALS_FILE="$HOME/.openclaw/exec-approvals.json"
+AUDIT_LOG="$HOME/.openclaw/exec-grant-audit.log"
+
+# --- Modify exec-approvals.json: set security back to "allowlist" ---
+if [[ -f "$APPROVALS_FILE" ]]; then
+  TEMP_FILE=$(mktemp)
+  jq '.agents.main.security = "allowlist"' "$APPROVALS_FILE" > "$TEMP_FILE" && mv "$TEMP_FILE" "$APPROVALS_FILE"
+else
+  echo "Warning: ${APPROVALS_FILE} not found, nothing to revoke" >&2
+fi
+
+# --- Cancel active timers if called manually (idempotent) ---
+if [[ -f "$STATE_FILE" ]]; then
+  TIMER_ID=$(jq -r '.timer_id // ""' "$STATE_FILE" 2>/dev/null || echo "")
+
+  if [[ "$TIMER_ID" == systemd:* ]]; then
+    UNIT="${TIMER_ID#systemd:}"
+    systemctl --user stop "${UNIT}.timer" 2>/dev/null || true
+    systemctl --user stop "${UNIT}.service" 2>/dev/null || true
+  fi
+  # bg: timers cannot be reliably cancelled cross-process, but the revoke
+  # itself is idempotent so a second invocation is harmless
+fi
+
+# --- Update state file ---
+NOW=$(date +%s)
+cat > "$STATE_FILE" <<ENDJSON
+{
+  "status": "revoked",
+  "revoked_at": ${NOW}
+}
+ENDJSON
+
+# --- Audit log ---
+echo "[$(date -u '+%Y-%m-%dT%H:%M:%SZ')] REVOKE: security restored to allowlist" >> "$AUDIT_LOG"
+
+# --- Notify admin ---
+ADMIN_PHONE=$(openclaw config get plugins.entries.exec-grant.config.adminPhone 2>/dev/null | tail -1 | tr -d '[:space:]' || true)
+
+if [[ -n "$ADMIN_PHONE" ]]; then
+  openclaw message send --target "$ADMIN_PHONE" --channel whatsapp --message "Grant revoked. Security restored to allowlist mode." 2>/dev/null || true
+fi
+
+echo "Grant revoked. Security restored to allowlist mode."

package/skills/exec-grant/scripts/status.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# status.sh -- Agent-facing: checks current grant state
+# Usage: status.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+STATE_FILE="$HOME/.openclaw/exec-grant-state.json"
+APPROVALS_FILE="$HOME/.openclaw/exec-approvals.json"
+
+# --- Read state file ---
+if [[ ! -f "$STATE_FILE" ]]; then
+  echo "Status: inactive (no grant history)"
+  exit 0
+fi
+
+STATUS=$(jq -r '.status // "inactive"' "$STATE_FILE" 2>/dev/null || echo "inactive")
+NOW=$(date +%s)
+
+case "$STATUS" in
+  active)
+    EXPIRY=$(jq -r '.expiry // 0' "$STATE_FILE")
+
+    if [[ "$NOW" -ge "$EXPIRY" ]]; then
+      # Self-heal: grant expired but timer didn't fire (or hasn't yet)
+      echo "Status: expired (auto-revoking...)"
+      bash "${SCRIPT_DIR}/revoke.sh"
+      exit 0
+    fi
+
+    REMAINING_SECS=$(( EXPIRY - NOW ))
+    REMAINING_MINS=$(( (REMAINING_SECS + 59) / 60 ))
+    EXPIRY_HUMAN=$(jq -r '.expiry_human // "unknown"' "$STATE_FILE")
+
+    # Cross-check with actual approvals file
+    ACTUAL_SECURITY="unknown"
+    if [[ -f "$APPROVALS_FILE" ]]; then
+      ACTUAL_SECURITY=$(jq -r '.agents.main.security // "unknown"' "$APPROVALS_FILE" 2>/dev/null || echo "unknown")
+    fi
+
+    if [[ "$ACTUAL_SECURITY" != "full" ]]; then
+      echo "Warning: state says active but exec-approvals.json shows '${ACTUAL_SECURITY}'"
+      echo "Status: inconsistent (run revoke.sh to reset)"
+      exit 1
+    fi
+
+    echo "Status: active"
+    echo "Remaining: ${REMAINING_MINS}m (${REMAINING_SECS}s)"
+    echo "Expires: ${EXPIRY_HUMAN}"
+    ;;
+
+  pending)
+    REQUESTED_AT=$(jq -r '.requested_at // 0' "$STATE_FILE")
+    ELAPSED=$(( NOW - REQUESTED_AT ))
+    MINUTES=$(jq -r '.requested_minutes // "?"' "$STATE_FILE")
+    REASON=$(jq -r '.reason // "unknown"' "$STATE_FILE")
+
+    echo "Status: pending"
+    echo "Requested: ${MINUTES}m (${ELAPSED}s ago)"
+    echo "Reason: ${REASON}"
+    ;;
+
+  revoked)
+    REVOKED_AT=$(jq -r '.revoked_at // 0' "$STATE_FILE")
+    AGO=$(( NOW - REVOKED_AT ))
+    echo "Status: inactive (revoked ${AGO}s ago)"
+    ;;
+
+  *)
+    echo "Status: inactive"
+    ;;
+esac