Skip to main content
skill CX Codex

guardrail-patterns · zaxbyhub, generated — Claude Code skill: destructive shell command guards

guardrail-patterns — a skill for opencode-swarm that maps how the guard blocks inside checkDestructiveCommand() are built, and what breaks when you edit them.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill guardrail-patterns -a claude-code
Open on GitHub

What guardrail-patterns does

Load it before you touch src/hooks/guardrails.ts. It explains how checkDestructiveCommand() is put together, the one function standing between an agent and a destructive shell command. Order matters. NFKC normalisation and doubled-quote collapsing happen in dcNormalizeCommand(), wrapper stripping for bash, sudo, powershell and the rest runs with a 10-pass cap, then segments are split on && and ; before each one faces the sections.

New blocks come in three regex shapes. The two-condition form, flag plus path, is the one the skill recommends: it survives either argument order, so tool --flag .swarm/path and tool .swarm/path --flag both hit. Write the path separator as \x5c and anchor commands with ^\\?, or a leading backslash walks straight past. Every section ships with adversarial tests for the evasions already on record.

Some holes stay open. dcStripOneWrapper() only expects double quotes, so a single-quoted sh -c payload never gets unwrapped. Quote splicing like m'v' and a quoted command name get through as well. Run those strings through your tests, because a section that ignores them looks like protection and is not.

What it helps with

  • add a new guard section without breaking the check order
  • close the backslash-prefix bypass on \mv
  • match move and archive commands against .swarm in either argument order
  • write adversarial tests for the evasions already known
  • trace why single-quoted sh -c payloads slip through

Example prompts for the agent

  • Load guardrail-patterns and walk me through the section order in checkDestructiveCommand() before I edit src/hooks/guardrails.ts.
  • Add a guard for robocopy /MOVE on .swarm, keeping the existing regex style and both argument orders.
  • Which evasions are still open for mv against .swarm? Check with guardrail-patterns and extend the adversarial tests.

How to install guardrail-patterns

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill guardrail-patterns -a claude-code

2Manually: put the files in place

~/.claude/skills/guardrail-patterns/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/guardrail-patterns/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about guardrail-patterns

How do I install guardrail-patterns in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill guardrail-patterns -a claude-code. The skill lands at ~/.claude/skills/guardrail-patterns/SKILL.md.

What does guardrail-patterns do?

It lays out the section structure of checkDestructiveCommand(), the regex mistakes to avoid and the test habits for new guards. Editing that file without it is guesswork.

Which evasions are still open?

Quote splicing such as m'v', a command name wrapped in quotes, and single-quoted sh -c payloads. The skill marks all three as unresolved and points at the normalisation step.

Source text

SKILL.md · MIT
---
name: guardrail-patterns
description: Guardrail patterns for opencode-swarm — pattern structure, bypass surfaces, regex anti-patterns, and test conventions for checkDestructiveCommand()
metadata:
  source_knowledge_ids: '["00cc0fba-5ed8-4e2c-9a3c-96675e09d175", "b02ac9d7-9f2b-4ac0-9afe-5ee5f35f54c3"]'
  generated_at: "2026-06-22T00:00:00.000Z"
  status: active
  version: "2"
  skill_origin: generated
  provenance_note: >
    Re-linked to current knowledge entries (version 2). The original 4 source IDs
    (098926ef, 2c1e4689, 54c33fa4, 4f51d11a) are no longer present in the
    active knowledge store. The skill body and behavior are unchanged.
    New source_knowledge_ids reference current lessons about lint-script
    false positives (testing) and refactoring guards to separate functions
    (architecture), both directly relevant to guardrail patterns.
---

# Skill: Guardrail Patterns for opencode-swarm

**Source knowledge:** `098926ef`, `2c1e4689`, `54c33fa4`, `4f51d11a`

Load this skill **before** modifying `src/hooks/guardrails.ts` — adding, removing, or changing guardrail blocks in `checkDestructiveCommand()`. It documents the pattern structure, known bypass surfaces, regex anti-patterns, and test conventions used across 41 guardrail test files and the ~3900-line guardrails.ts file.

## When to load this skill

Load before any change to:
- `src/hooks/guardrails.ts` — especially `checkDestructiveCommand()` or `dcNormalizeCommand()`
- `tests/unit/hooks/guardrails*.test.ts` — any guardrail test file
- Adding a new section (currently Sections 1–22) to `checkDestructiveCommand()`
- Adding regex patterns for shell command blocking

## Architecture overview

### `checkDestructiveCommand()` — the shell command guard

Located at `src/hooks/guardrails.ts` (line 1304). This is the **only** function that blocks destructive shell commands. It is invoked by the `toolBefore` hook in `guardrails.ts` before every `bash` or `shell` tool call.

**Pipeline (in order):**
1. `dcNormalizeCommand()` (line ~627) — NFKC normalization + evasion collapse: collapses `""` (doubled double-quotes) and `''` (doubled single-quotes). Single-quote splice like `m'v'` remains OPEN.
2. `dcStripOneWrapper()` (line ~664) — detects and strips individual shell wrappers: `bash`, `sh`, `zsh`, `dash`, `fish`, `pwsh`, `powershell`, `cmd` (with `-c`/`-Command`), `sudo`, `nohup`, `time`, `nice`, `env VAR=val`, `call` (batch), `Invoke-Command -ScriptBlock`, `& { }` script blocks, `wsl`, `iex`
3. `dcUnwrapWrappers()` (line ~737) — loops `dcStripOneWrapper` until no more wrappers remain (max depth 10)
4. `dcSplitSegments()` (line ~753) — splits compound commands on `&&`, `;`, `|`, newlines
5. Per-segment loop — each segment evaluated against 22+ guardrail sections
6. `dcValidateTargets()` — runtime `lstat`-ancestor walk on destructive targets

### Key normalization functions

| Function | Line | What it normalizes |
|---|---|---|
| `dcNormalizeCommand` | ~627 | NFKC, caret escapes (`^`), backtick escapes, collapsed `""` and `''` |
| `dcStripOneWrapper` | ~664 | Detects/strips a single shell wrapper (bash/sh/zsh/pwsh/cmd/powershell/wsl etc) |
| `dcUnwrapWrappers` | ~737 | Loops `dcStripOneWrapper` until no more wrappers (max depth 10) |
| `dcSplitSegments` | ~753 | Splits on `&&`, `;`, `|`, `\n` for per-segment checking |

**Known wrapper unwrapping limitation:** `sh -c` and `bash -c` with **single-quoted** inner commands (`sh -c 'mv ...'`) are NOT unwrapped because `dcStripOneWrapper` uses `"?` (optional double-quote). Only double-quoted inner commands are properly stripped.

## Adding a new guardrail block

### Step 1 — Determine the pattern placement

Inside `checkDestructiveCommand()`, the per-segment `for` loop evaluates each segment against sections 1–22. A new section should be added after the last existing section and before the closing `}` of the `for` loop (currently after Section 22 at approximately line 1733).

### Step 2 — Choose the regex pattern structure

There are three patterns used in the codebase:

**Pattern A — Simple inline regex (single condition):**
```typescript
// Good for: single-command blocking with no complex extraction
if (/^blockedcommand\b.*\.swarm[\x5c/\s]?/i.test(seg)) {
  throw new Error(`BLOCKED: "blockedcommand" targeting .swarm/ detected — ...`);
}
```

**Pattern B — Multi-condition (flag check + path check):**
```typescript
// Good for: archive tools with flags + .swarm/ path (prevents argument-order bypass)
if (
  /^toolname\b.*--dangerous-flag\b/i.test(seg) &&
  /\.swarm(?:[\x5c/\s]|$)/i.test(seg)
) {
```
This is **recommended** because it handles both `tool --flag .swarm/path` and `tool .swarm/path --flag` argument orders.

**Pattern C — Argument extraction + stripped check:**
```typescript
// Good for: commands where you need argument isolation (e.g., `mv` with arg capture)
if (/^\\?command\s/i.test(seg)) {
  const match = seg.match(/^\\?command\s+(.+)$/i);
  if (match) {
    const argsStr = match[1].replace(/["']/g, '');
    if (/\.swarm(?:[\x5c/\s]|$)/.test(argsStr)) {
      throw new Error(`BLOCKED: ...`);
    }
  }
}
```

### Step 3 — Handle all platform variants

POSIX, Windows cmd.exe, and PowerShell often use different commands for the same operation. All three must be covered:

```typescript
// POSIX section
if (/^\\?posix-cmd\s/i.test(seg) && /\.swarm/i.test(strippedArgs)) { ... }

// Windows cmd section (case-insensitive, optional .exe)
if (/^\\?(?:cmd-cmd|cmd-cmd-alias)(?:\.exe)?\s/i.test(seg) && /\.swarm/i.test(argsStr)) { ... }

// PowerShell section (case-insensitive, all aliases)
if (/^\\?(?:PowerShell-Cmdlet|alias1|alias2)\b.*\.swarm/i.test(seg)) { ... }
```

### Step 4 — Handle the `.swarm` path separator

Always use `\x5c` (backslash) for cross-platform path matching — `\` alone is the regex escape character.

```typescript
// Correct: matches both / and \
/\.swarm[\x5c/]/

// More complete: also matches .swarm followed by whitespace or end-of-string
// (catches whole-directory targeting like `mv .swarm /tmp/`)
/\.swarm(?:[\x5c/\s]|$)/
```

### Step 5 — Handle backslash-prefixed command evasion

Commands prefixed with `\` (e.g., `\mv`) bypass simple `^command\s` anchors. Always add `\\?`:

```typescript
// Correct: catches both mv and \mv
if (/^\\?mv\s/i.test(seg)) { ... }

// Correct for rm (uses \b instead of \s)
if (/^\\?rm\b/i.test(seg)) { ... }
```

## Known bypass surfaces (must document in adversarial tests)

These are documented bypass vectors that the current regex-based approach cannot fully close. Every new guardrail section should include adversarial tests for these patterns:

| Evasion | Example | Status | Mitigation |
|---|---|---|---|
| Backslash prefix | `\mv .swarm/file` | **CLOSED** | Add `^\\?` to command anchor |
| Quote splicing | `m'v' .swarm/file` | **OPEN** | Requires NFKC normalization change |
| Quoted command name | `"mv" .swarm/file` | **OPEN** | Requires NFKC normalization change |
| Shell wrapper (double-quoted) | `sh -c "mv .swarm/file"` | **CLOSED** | dcUnwrapWrappers handles `"` |
| Shell wrapper (single-quoted) | `sh -c 'mv .swarm/file'` | **OPEN** | dcUnwrapWrappers regex uses `"?` |
| Relative path prefix | `mv ./swarm/file` | **OPEN** | Requires path normalization |
| Env var expansion | `mv $SWARM_DIR/file` | **OPEN** | Requires variable resolution |
| Unicode fullwidth | `mv .swarm/file` | **OPEN** | Requires NFKC normalization |

## Regex anti-patterns (from prior bugs)

### Anti-pattern 1: `[^-]` consuming path characters
```typescript
// WRONG — [^-] consumes the first character of the path
if (/^rm\s+(?!\s*-)(?!-)[^-].*\.swarm/i.test(seg)) {
  // "rm .swarm/file" → [^-] consumes '.' → "swarm/file" doesn't match "\.swarm"
}

// CORRECT — use negative lookahead for flag exclusion
if (
  /^rm\b/i.test(seg) &&
  !/^rm\s+(?:-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)\b/i.test(seg) &&
  /\.swarm(?:[\x5c/\s]|$)/i.test(seg)
) {
  // "rm .swarm/file" → BLOCKED ✓
  // "rm -rf .swarm/" → Section 3 handles ✓
  // "rm -v .swarm/file" → BLOCKED ✓
}
```

### Anti-pattern 2: Negative lookahead too broad (`(?!-\S)`)
```typescript
// WRONG — (?!-\S) excludes ALL flag-prefixed rm commands,
// but Section 3 only catches recursive/force flags
if (/^rm\s+(?!-\S).*\.swarm/i.test(seg)) {
  // "rm -v .swarm/file" → NOT blocked by S19 (excluded by lookahead)
  // "rm -v .swarm/file" → NOT blocked by S3 (no -r/-f flags)
}

// CORRECT — use three-part condition
```

### Anti-pattern 3: `.exec()` confused by SAST
```typescript
// WRONG — SAST confuses RegExp.prototype.exec() with child_process.exec()
const match = /^command\s+(.+)$/i.exec(seg);  // SAST false positive

// CORRECT — use String.prototype.match()
const match = seg.match(/^command\s+(.+)$/i);  // No SAST false positive
```

### Anti-pattern 4: Argument-order dependent patterns
```typescript
// WRONG — .swarm/ must appear AFTER the flag in the command string
if (/^tool\b.*--flag\b.*\.swarm/i.test(seg)) {
  // "tool --flag .swarm/" → BLOCKED ✓
  // "tool .swarm/ --flag" → NOT BLOCKED ✗
}

// CORRECT — split flag check and path check
if (/^tool\b.*--flag\b/i.test(seg) && /\.swarm(?:[\x5c/\s]|$)/i.test(seg)) {
  // Both argument orders BLOCKED ✓
}
```

## Test conventions

### Test file structure

```typescript
// Positive tests: "command → BLOCKED"
test('mv .swarm/evidence/file.json /tmp/ → BLOCKED', async () => { ... });

// Negative tests: "command → ALLOWED (reason)"
test('ls .swarm/evidence/ → ALLOWED (read-only)', async () => { ... });

// Bypass when feature is disabled
test('mv .swarm/file /tmp/ → ALLOWED when block_destructive_commands=false', async () => { ... });
```

### Test infrastructure pattern

```typescript
import { mkdtempSync, realpathSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { createGuardrailsHooks } from '../../../src/hooks/guardrails';
import { resetSwarmState, startAgentSession } from '../../../src/state';

const TEST_DIR = realpathSync(mkdtempSync(join(tmpdir(), 'guardrail-pattern-')));

function defaultConfig(overrides?: Partial<GuardrailsConfig>): GuardrailsConfig {
  return {
    enabled: true,
    max_tool_calls: 200,
    max_duration_minutes: 30,
    idle_timeout_minutes: 60,
    max_repetitions: 10,
    max_consecutive_errors: 5,
    warning_threshold: 0.75,
    profiles: undefined,
    block_destructive_commands: true,
    ...overrides,
  };
}

function makeBashInput(sessionID = 'test-session', command: string) {
  // Note: command is accepted but passed to makeBashOutput, not makeBashInput
  return { tool: 'bash', sessionID, callID: 'call-1' };
}

function makeBashOutput(command: string) {
  return { args: { command } };
}
```

### Required test categories

Every new guardrail section MUST have tests for:
1. **Positive** — command targeting `.swarm/` is blocked
2. **Negative** — same command with non-`.swarm/` path is allowed
3. **Read-only** — read-only commands (ls, cat, find) are not blocked
4. **Config bypass** — verified unblocked when `block_destructive_commands: false`
5. **Platform variants** — POSIX, Windows cmd, PowerShell forms where applicable
6. **Adversarial** — documented bypass surfaces (one test per known evasion type)

### Key testing rules

- Use `bun:test` only (no Jest/Vitest)
- Use `rejects.toThrow(/BLOCKED/)` for positive assertions
- Use `resolves.toBeUndefined()` for negative assertions
- No hardcoded `/tmp` — use `os.tmpdir()` + `mkdtempSync`
- No hardcoded `C:\` strings
- Wrap `mkdtempSync` in `realpathSync` for macOS compatibility

## Section pattern reference (current guardrail sections 1–22)

| Section | Line | Commands blocked | Notes |
|---|---|---|---|---|
| 2 | ~1347 | Junction/symlink CREATION out-of-cwd | `dcCheckJunctionCreation` — creation of junctions/symlinks targeting outside cwd |
| 3 | ~1353 | `rm -r[Ff]*`, `rm -f -r`, etc | Recursive + force only (`[rRfF]+` flag set) |
| 4 | ~1378 | `rmdir /s`, `rd /s` | Windows cmd, recursive |
| 5 | ~1400 | `del /s` | Windows cmd |
| 6–7 | ~1418 | `Remove-Item -Recurse` + pipeline form | PowerShell |
| 8 | ~1457 | Ransomware-grade | vssadmin, wbadmin, diskpart, bcdedit, sdelete, fsutil, takeown, cipher, format, robocopy /MIR |
| 9 | ~1510 | `chmod -R 000`, `chattr +i`, `icacls /deny` | Permission denial-of-service |
| 10 | ~1529 | `dd` with /dev/zero/null/urandom | Data wipe |
| 11 | ~1538 | Git destructive | push --force, reset --hard, reset --mixed, clean -fd, worktree remove --force |
| 12 | ~1567 | `rsync --delete(-before/-after/-during/-delay)` | Mirror/sync with delete |
| 13 | ~1576 | `kubectl delete`, `docker system prune` | Cluster/container |
| 14 | ~1590 | `DROP TABLE/DATABASE/SCHEMA`, `TRUNCATE TABLE` | SQL DDL |
| 15 | ~1604 | `mkfs` | Disk format |
| 16 | ~1615 | `mv` | POSIX — blocked on `.swarm/` |
| 17 | ~1635 | `move`, `ren` | Windows cmd — blocked on `.swarm\` |
| 18 | ~1652 | `Move-Item`, `Rename-Item`, aliases | PowerShell — blocked on `.swarm/` |
| 19 | ~1667 | `rm` (non-recursive) | Blocked on `.swarm/` (recursive → Section 3) |
| 20 | ~1682 | `cp` + `rm` chain | Secondary defense (rm guard is primary) |
| 21 | ~1697 | `rsync --remove-source-files`, `tar --remove-files`, `zip -m`, `7z -sdel` | Archive tools with delete-source flags |
| 22 | ~1728 | `git clean -fd`, `git worktree remove --force` | Verified existing patterns cover `.swarm/` |

## Task checklist for adding a new guardrail block

- [ ] Pattern chosen (A/B/C) and placed in correct section order
- [ ] Command anchor includes `^\\?` (backslash prefix)
- [ ] `.swarm` path check uses `(?:[\x5c/\s]|$)` (whole-root + subpath)
- [ ] Argument-order independent (split flag check from path check)
- [ ] Platform variants covered (POSIX + cmd + PowerShell)
- [ ] `.exec()` → `.match()` to avoid SAST false positives
- [ ] Positive test: `.swarm/` path blocked
- [ ] Negative test: non-`.swarm/` path allowed
- [ ] Read-only test: read commands not blocked
- [ ] Config bypass test: `block_destructive_commands: false`
- [ ] Adversarial tests: document known bypasses
- [ ] `bun run build` succeeds
- [ ] `bunx biome ci .` clean
- [ ] All guardrail test suites pass

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Agent setup: memory, context, orchestration →

guardrail-patterns by other authors comes first.

guardrail-patterns ZaxbyHub guardrail-patterns guides agents when editing destructive-command guards in opencode-swarm, setting document reading order and adversarial testing rules. CX Codex +1 ★ 539repo stars Agent Guardrail eren-solutions Agent Guardrail is an MCP server that checks an agent's planned tool calls, shell commands, and HTTP requests against security policy before execution. CX Codex +1 534installs guardrail-hooks Paweł Huryn guardrail-hooks — a skill for Claude Code converts natural-language instructions into code paths, permission settings, and hooks. Runs when an agent breaks rules repeatedly. CX Codex +1 ★ 741repo stars red-team gaasher red-team finds weaknesses in content filters, classifiers and APIs through adversarial stress-testing — generates attack inputs and builds a catalogue of failures. CX Codex +1 ★ 185repo stars NeuroDock Guardrail tlennon-ie NeuroDock Guardrail flags rumination loops, unregulated hyperfocus and sycophancy in AI conversations. It advises, it never silently blocks. CX Codex +1 ★ 20repo stars multi-reviewer-patterns Seth Hobson The multi-reviewer-patterns skill coordinates parallel reviews across code-quality dimensions and merges the results into one report. Use it when a change needs several review angles. CX Codex +1 9,800installs string-manipulation-mastery JosiahSiegel string-manipulation-mastery is a Claude Code skill for editing and parsing Bash strings. It activates for parameter expansion, regex checks, array splitting, and whitespace trimming. CX Codex +1 163installs

From the same set121

The whole set →
ci-fix-monitor The ci-fix-monitor skill checks a PR’s CI results, diagnoses failed checks from their logs, and guides fixes and another push. Use it when a PR has red checks. CX Codex +1 ★ 539repo stars issue-tracer2 issue-tracer2 pulls in a GitHub Issue, works through a chain of hypotheses to pin down the root cause, and carries the fix through to tests and a PR. CX Codex +1 ★ 539repo stars issue-ingest issue-ingest pulls a GitHub issue, locates the likely cause in the codebase, and writes a resolution spec. Triggered with /swarm issue <url>. CX Codex +1 ★ 539repo stars deep-dive deep-dive audits a selected part of a codebase without editing source files. Use it to investigate several aspects of a project and review evidence-backed findings. CX Codex +1 ★ 539repo stars swarm Enables a multi-agent swarm workflow in the active session, running parallel subagents, independent review validation, and critic checks. CX Codex +1 ★ 539repo stars loop The loop skill takes a task through planning, implementation, review, and improvement while keeping run state on disk. Use it for gated, repeatable work toward a defined objective. CX Codex +1 ★ 539repo stars running-tests Sets the rules for running tests in opencode-swarm: when a shell bun call is enough, when to reach for test_runner, and how to keep the session from stalling. CX Codex +1 ★ 539repo stars issue-tracer issue-tracer drives bug reports from reproduction and root-cause analysis to verified PRs under a strict full-resolution contract. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open