npm package: @stakeswky/openclaw-permctl
Description: macOS TCC permission error detection, auto-interception, CLI commands, and permctl skill for OpenClaw agents
Author: stakeswky
Latest version: 0.2.0

# @stakeswky/openclaw-permctl

macOS TCC permission error detection, auto-interception, and guided remediation for OpenClaw agents.

## What it does

macOS uses TCC (Transparency, Consent, and Control) to gate access to sensitive resources like screen recording, accessibility, camera, etc. These permissions are **per-binary** — when Node.js gets upgraded via Homebrew, the binary path changes and permissions break silently.

This plugin:
- **Detects** TCC permission errors in command output (12 error patterns across 6 permission categories)
- **Diagnoses** current permission states via the `permctl.sh` skill
- **Guides** users through fixing permissions with step-by-step instructions (English & Chinese)
- **Identifies** which terminal/binary needs authorization (`detect-host`)
- **Monitors** permission changes over time (`watch` for cron/heartbeat integration)
- Provides **CLI commands**, **slash commands**, and **agent tools**

## Install

```bash
openclaw plugins install @stakeswky/openclaw-permctl
```

Or clone locally:
```bash
git clone https://github.com/stakeswky/openclaw-plugin-permctl
# Add to plugins.load.paths in your OpenClaw config
```

## Configuration

All settings are optional. Defaults work out of the box.

```json5
{
  plugins: {
    entries: {
      permctl: {
        enabled: true,
        config: {
          autoDetect: true,      // Auto-analyze exec failures for TCC errors
          notifyOnDenied: true,  // Alert on permission status changes
          language: "auto"       // "auto" | "en" | "zh"
        }
      }
    }
  }
}
```

## Agent Tools (opt-in)

Enable in your agent config:
```json5
{
  agents: {
    list: [{
      id: "main",
      tools: { allow: ["permctl"] }  // enables all permctl tools
    }]
  }
}
```

| Tool | Description |
|------|-------------|
| `tcc_detect` | Analyze command output for TCC errors |
| `permctl_status` | Check current permission states |
| `permctl_guide` | Get step-by-step fix instructions |
| `permctl_detect_host` | Identify terminal app and binary paths |
| `permctl_watch` | Check for permission changes since last run |

## CLI Commands

```bash
openclaw permctl status                    # Check all permissions
openclaw permctl status accessibility      # Check specific permission
openclaw permctl guide screen-recording    # Get fix instructions
openclaw permctl guide accessibility --lang zh  # Chinese instructions
openclaw permctl detect-host               # Show terminal & binary info
openclaw permctl watch                     # Check for changes
```

## Slash Commands

In any chat channel (Telegram, Discord, etc.):

```
/permctl                          # Check all permissions
/permctl status accessibility     # Check specific permission
/permctl guide screen-recording   # Get fix instructions
/permctl detect-host              # Show terminal info
/permctl watch                    # Check for changes
```

## Permissions Covered

| Permission | TCC Service | Detection Method |
|---|---|---|
| Accessibility | kTCCServiceAccessibility | osascript probe |
| Automation | kTCCServiceAppleEvents | osascript probe |
| Screen Recording | kTCCServiceScreenCapture | screencapture test / peekaboo / TCC.db |
| Full Disk Access | kTCCServiceSystemPolicyAllFiles | ~/Library/Mail access test |
| Camera | kTCCServiceCamera | peekaboo |
| Microphone | kTCCServiceMicrophone | peekaboo |

## Watch Mode (Cron Integration)

The `watch` command compares current permission states against `~/.permctl_state.json`. Use it with OpenClaw cron for periodic monitoring:

```json5
// Example: check permissions every 6 hours
{
  schedule: { kind: "cron", expr: "0 */6 * * *" },
  payload: { kind: "agentTurn", message: "Run permctl_watch and alert me if any permissions changed." }
}
```

## Development

```bash
npm install
npm test
```

## License

MIT