Skip to main content
skill CX Codex

subprocess-safety — Claude Code skill: rules and installation

The subprocess-safety skill sets requirements for child-process calls. Use it when adding, changing, or reviewing code that invokes spawn, spawnSync, or child_process.

MIT ★ 539 updated 2026-10-29

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

What subprocess-safety does

The skill requires subprocess calls to pass arguments as an array, set a working directory and timeout, bound output, and kill the process in a finally block. For execFileSync, it also specifies stdio settings so the child does not inherit the parent’s input. This matters when running Bun on Windows.

On Windows, resolve .cmd wrappers explicitly rather than enabling shell: true. For paginated gh api requests, add --slurp; without it, combined page output can fail JSON parsing or lose results. Before changing subprocess code, read AGENTS.md and docs/engineering-invariants.md. Separate guidance covers tests and migration from mock.module to _internals.

What it helps with

  • check subprocess calls for a missing timeout
  • pass command arguments without a shell string
  • set a child process working directory explicitly
  • parse paginated gh api results without losing pages
  • verify .cmd execution on Windows

Example prompts for the agent

  • Review the spawn call in this file against subprocess-safety.
  • Add a child-process call with a timeout and cleanup in finally.
  • Check that this gh api --paginate request handles every page.

How to install subprocess-safety

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill subprocess-safety -a claude-code

2Manually: put the files in place

~/.claude/skills/subprocess-safety/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/subprocess-safety/

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

Questions about subprocess-safety

How do I install subprocess-safety in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill subprocess-safety -a claude-code. The skill file is available at ~/.claude/skills/subprocess-safety/SKILL.md.

What does subprocess-safety do?

It defines safeguards for child-process calls, including array-form arguments, an explicit working directory, a timeout, bounded output, and process cleanup.

What should I account for when spawning processes on Windows?

Resolve npm and bun .cmd wrappers to an executable path. The skill advises against using shell: true to work around PATH resolution.

Source text

SKILL.md · MIT
---
name: subprocess-safety
description: Guidelines for safe subprocess calls in opencode-swarm. Load before adding, modifying, or reviewing any file that calls spawn, spawnSync, bunSpawn, or child_process. Covers the six required properties, Windows portability, _internals DI seam pattern, and verification grep.
metadata:
  audience: swarm-plugin
---

# Subprocess Safety

Read, in order:

1. `AGENTS.md` (Invariant 3: subprocesses)
2. `docs/engineering-invariants.md` (subsection 3)
3. `.agents/skills/writing-tests/SKILL.md` if tests are touched
4. `.opencode/skills/generated/mock-to-internals-migration/SKILL.md` if converting mock.module to _internals

Codex-specific execution notes:
- This skill consolidates AGENTS.md Invariant 3 into an actionable checklist.
- The canonical spawn shape and six required properties are non-negotiable per AGENTS.md.
- The CI quality job enforces these via `bun run check:invariants` (Check 1: subprocess timeout).
- Violations are advisory in CI but blocking in code review.

## When to use this skill

- You are adding, modifying, or reviewing a subprocess call (`bunSpawn`, `spawn`,
  `spawnSync`, `child_process.execFile`, etc.)
- You are writing or updating tests that exercise subprocess-dependent code
- A PR review flags a subprocess call missing timeout, cwd, or cleanup

## Scope

This skill applies to all files that spawn child processes:
- `src/utils/git*.ts`
- `src/hooks/*.ts`
- `src/tools/*.ts`
- `src/services/*.ts`
- `src/plugins/*.ts`
- `src/index.ts` (init-path subprocesses)
- Any test file (`tests/**`) that stubs or exercises subprocess code

## Canonical spawn shape

Every subprocess call MUST follow this pattern:

```typescript
const PER_CALL_TIMEOUT_MS = 10_000; // module-level constant (choose an appropriate value)

const proc = bunSpawn(['git', '-C', dir, 'rev-parse', '--show-toplevel'], {
  stdin: 'ignore',
  cwd: dir,
  timeout: PER_CALL_TIMEOUT_MS,
  // stdout/stderr: piped, bounded, or ignored
});
try {
  const result = await proc;
  // process result
} finally {
  proc.kill(); // best-effort cleanup
}
```

## Six required properties

| Property | Required | Rationale |
|----------|----------|-----------|
| Array-form args | Yes | No shell-string commands (injection risk, quoting hell) |
| `cwd` or `git -C` | Yes | Never rely on inherited process.cwd() |
| `stdin: 'ignore'` | Yes | A never-closed stdin pipe under Bun/Windows can block child exit (v7.3.3) |
| `timeout: <ms>` | Yes | No subprocess is "always fast" on every platform |
| stdout/stderr bounded | Yes | Never leave piped stream unattended on long-running child |
| `proc.kill()` in `finally` | Yes | Outer withTimeout lets awaiter proceed but doesn't abort child |

## execFile callback vs execFileSync distinction

`child_process.execFile` (callback form) and `child_process.execFileSync` have different
default stdio behavior:

| API | Default stdin | Risk |
|-----|---------------|------|
| `execFileSync` | `'inherit'` | Child inherits parent stdin — **v7.3.3 vector** on Windows/Bun if stdin is never closed |
| `execFile` (callback) | `'pipe'` | Child gets an internal pipe — lower risk but still not ideal for defense-in-depth |

**Key differences from the canonical spawn pattern:**

1. **`proc.kill()` in `finally` (line 69)**: **Applicable to callback-form `execFile`.**
   The function returns a `ChildProcess` reference (matching the canonical spawn
   pattern per Node.js docs). The child reference enables `kill()` before that
   point for timeout safety, and failing to call `proc.kill()` in `finally` can
   leave orphaned children when combined with an outer `withTimeout`. The
   `timeout` option triggers internal `SIGTERM`, but is not a substitute for
   explicit kill in `finally` — always kill the child in `finally`.

2. **`stdin: 'ignore'` (line 66)**: Technically default-safe for callback `execFile`
   (stdin is piped, not inherited). However, always add `stdio: ['ignore', 'pipe', 'pipe']`
   for defense-in-depth and consistency with `execFileSync` calls. Note: Bun's
   TypeScript definitions do not include `stdio` in `ExecFileOptions` — use
   `execOpts as any` when passing stdio to callback-form `execFile`.

3. **`execFileSync` should always use `stdio: ['ignore', 'pipe', 'pipe']`** to
   prevent the stdin-inheritance hang on Windows/Bun (v7.3.3).

## Windows-specific notes

- `.cmd` extensions: npm/bun binaries on Windows are `.cmd` wrappers. Resolve
  the executable path explicitly using `which`/`where` or the project's
  cross-platform helper. Do NOT enable `shell: true` or shell-mediated
  execution to work around PATH resolution.
- PATH differences: `cmd.exe` and PowerShell resolve PATH differently. Test on
  Windows, not just macOS/Linux.
- `child_process.spawn('bin', ...)` does not behave identically to running
  under `cmd.exe`. Use array-form args and explicit `cwd`.
- `fs.renameSync` cannot overwrite existing directories on Windows. Use a
  remove-then-rename pattern or `fs.rename` with error handling.

## gh CLI Subprocess Patterns

The `gh` CLI is a common subprocess in this repo (`scripts/release-notes-fragments.mjs`, CI workflows). It follows the same six required properties as all subprocesses, plus several `gh`-specific patterns.

### `gh api --paginate` requires `--slurp`

**Bug pattern (PR #1762 F-002):** `gh api --paginate` without `--slurp` produces concatenated JSON arrays on stdout. `JSON.parse()` can only parse the first array — subsequent arrays cause a parse error or are silently lost.

**Correct pattern:**
```javascript
const raw = execFileSync('gh', ['api', '--paginate', '--slurp', 'repos/.../pulls', ...], {
  encoding: 'utf8',
  timeout: 30_000,
  maxBuffer: 16 * 1024 * 1024,
  stdio: ['ignore', 'pipe', 'pipe'], // required for execFileSync (AGENTS.md §3)
});
// --slurp wraps paginated results as [[page1], [page2], ...]
const pages = JSON.parse(raw);
const allItems = pages.flat(); // flatten to single array
```

**Without `--slurp`:** stdout is `[item1, item2][item3, item4]` — invalid JSON after the first array. This is a silent data loss bug that only manifests when results span multiple pages (>30 items by default).

### `stdin: 'ignore'` for `gh` calls

`gh` subprocess calls must include `stdin: 'ignore'` (or `stdio: ['ignore', 'pipe', 'pipe']` for `execFileSync`). This is the same invariant as all subprocesses (AGENTS.md §3). For example, `scripts/release-notes-fragments.mjs` defines `ghJson()` and `ghText()` helpers using `execFileSync` — these must include `stdio: ['ignore', 'pipe', 'pipe']` per the six required properties. A PR review (pre-merge) identified this gap.

### `Number.isInteger()` for API response validation

When validating integer IDs from API responses (PR numbers, issue numbers, run IDs), use `Number.isInteger()`, not `Number.isFinite()`. `Number.isFinite()` accepts floats like `1.5`, which are never valid IDs.

```javascript
// Correct
function isValidPrNumber(n) {
  return Number.isInteger(n) && n > 0;
}

// Wrong — accepts 1.5, NaN, Infinity
function isValidPrNumber(n) {
  return Number.isFinite(n) && n > 0;
}
```

> **Note:** This is a stricter pattern. Some existing code uses `Number.isFinite()` after `parseInt()` — while technically safe for parsed integers, `Number.isInteger()` is the correct guard for all ID validation going forward.

### `maxBuffer` for large API responses

`gh api` can return large payloads. Set `maxBuffer: 16 * 1024 * 1024` (16 MiB) to prevent silent truncation. This is especially important for `--paginate` calls that aggregate multiple pages.

> **Note:** `maxBuffer` is specific to Node.js `child_process.execFile`/`execFileSync`. For Bun's `bunSpawn`, use the equivalent output bounding option.

## Testing pattern: `_internals` DI seam, NOT `mock.module`

`mock.module(...)` leaks across test files in Bun's shared test-runner process.
Use dependency injection instead:

```typescript
// --- source file (e.g. src/utils/gitignore-warning.ts) ---
import { bunSpawn } from './bun-compat';

export const _internals: { bunSpawn: typeof bunSpawn } = { bunSpawn };

// In production code, call _internals.bunSpawn(...) instead of bunSpawn(...)

// --- test file ---
import { _internals } from '../../src/utils/gitignore-warning';
const real = _internals.bunSpawn;
beforeEach(() => { _internals.bunSpawn = stub; });
afterEach(() => { _internals.bunSpawn = real; });
```

For the full migration protocol, load the `mock-to-internals-migration` skill.

## Verification grep

After changing any file with subprocess calls, run:

```bash
grep -n "bunSpawn\|spawn(\|spawnSync(" src/<changed>/*.ts
```

Every match MUST have all of:
1. `timeout` set to a concrete millisecond value
2. `stdin: 'ignore'` (unless intentionally interactive; note: callback-form `execFile` uses `stdio: ['ignore', 'pipe', 'pipe']` instead)
3. `cwd` or `git -C <directory>` for explicit working directory
4. `proc.kill()` in a `finally` block or equivalent cleanup path (exception: callback-form `execFile` manages cleanup internally via `timeout` option)

## Historical failures

- **v7.0.3 (#704)**: repo-graph Desktop hang -- unbounded filesystem scan on
  plugin init. No timeout, no kill path. Result: "no agents in TUI/GUI" with
  no error message.
- **v7.3.3 (#732)**: Git-hygiene startup regression -- `ensureSwarmGitExcluded`
  called git without timeout, stdin, or kill. Result: same silent failure on
  Windows.

Both caused OpenCode to silently drop the plugin manifest. Users saw no agents
and no error. Every subprocess call is a potential repeat of these failures
unless all six properties are enforced.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Security →

From the same set121

The whole set →
brainstorm The brainstorm skill for Claude Code scans code, asks focused questions, and drafts a specification when requirements are still exploratory. CX Codex +1 ★ 539repo stars bundle-safety The bundle-safety skill guides bundle minification checks, identifier preservation, and namespace re-export coverage. Use it before build changes that could rename or remove code. CX Codex +1 ★ 539repo stars swarm-implement swarm-implement runs feature work, bug fixes and refactors through a swarm workflow: parallel exploration, a scoped plan, then reviewer and critic passes on the diff. CX Codex +1 ★ 539repo stars safe-rename safe-rename is a Claude Code skill that guides the renaming of exported symbols and files without breaking dependents, imports, or tests. CX Codex +1 ★ 539repo stars council Brings the COUNCIL mode of opencode-swarm into your session: three agents weigh a question and the architect returns one answer. CX Codex +1 ★ 539repo stars safe-extraction safe-extraction guides the safe refactoring of monolithic files into submodules. Keeps test mocks working through _internals proxies, preserves public APIs, and updates CI path allowlists. CX Codex +1 ★ 539repo stars critic-gate The critic-gate skill sends a plan to a critic agent and blocks execution until approval is recorded. Use it to review a plan before implementation starts. CX Codex +1 ★ 539repo stars tech-debt-ci-review tech-debt-ci-review audits a repository for technical debt and CI stability: tests that prove nothing, flakes and brittle build steps that keep pull requests from going green. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open