Library API reference

A Node.js host that needs an allow or deny decision inside its own process can call checkCommand instead of installing an agent integration. The function checks one shell command against the current policy and returns the decision. It never runs the command. This is one function, not a plugin framework. See Integration architecture for the integrations it can replace.

Install and import

npm install cc-safety-net

import { checkCommand } from 'cc-safety-net/api';

The package exports the cc-safety-net/api subpath alongside its root export:

"./api": { "types": "./dist/api.d.ts", "import": "./dist/api.js" }

It requires Node.js 18 or later and ESM. The package is "type": "module" and there is no CommonJS build, so require() cannot resolve the subpath.

`checkCommand`

function checkCommand(input: CheckCommandInput): CheckCommandResult;

The call is synchronous. It reads local policy files, filesystem facts, and CC_SAFETY_NET_* environment settings, then returns an allow or a deny.

Input

type CheckCommandInput = Readonly<{
  command: string;
  cwd: string;
}>;

Field	Type	Description
`command`	`string`	The shell command text to check. Must be non-empty
`cwd`	`string`	An absolute directory path. It anchors relative command targets and selects the project’s rule configuration

cwd is required and has no default. The API never falls back to process.cwd(), so the host decides which project a command belongs to.

Result

type CheckCommandResult =
  | Readonly<{ kind: 'allow' }>
  | Readonly<{ kind: 'deny'; reason: string; ruleId: string }>;

Field	Presence	Description
`kind`	always	`'allow'` or `'deny'`
`reason`	deny only	The block message, as displayed to a user
`ruleId`	deny only	The id of the rule or fixed denial that produced the block

Read kind for the decision. A deny means the host must not execute the command. reason is display text. Do not parse or compare it. Every deny carries a ruleId. It is a built-in rule id such as git.reset-hard, a secret rule id, a custom. rule id, or one of the fixed denial ids, such as cwd.requested-unusable. You can branch on it to handle one kind of deny differently, for example to tell the user to fix the working directory. A deny blocks the command whatever its id. A later version can add ids, so treat an id you do not recognize as a plain deny. For what a deny can be, see Blocked commands.

Errors

The function re-validates its input, because an untyped caller can pass anything TypeScript would reject. checkCommand throws TypeError with one of these messages:

Message	Condition
`checkCommand requires an input object with command and cwd`	`input` is not a non-null object
`command must be a non-empty string`	`command` is not a string, or is blank
`cwd must be an absolute directory path`	`cwd` is not a string, is blank, or is not absolute

checkCommand catches a known guard failure and returns its fail-closed deny instead, so that failure does not become a fail-open host mistake. Every other throw reaches the caller.

If checkCommand throws, do not execute the command. A throw is not an allow.

Unusable working directory

cwd is normalized with resolve(), then checked. The path must stat as a directory and be readable and searchable. There is deliberately no realpath step, so the OpenCode plugin and this function decide alike for one directory. When that check fails, the call returns a deny with ruleId cwd.requested-unusable instead of analyzing the wrong project. The reason is:

CC Safety Net could not use the requested working directory because it does not exist, is inaccessible, is not a directory, or uses an unsupported path form. Use an existing accessible working directory. If the requested directory is missing, create it from an accessible location before retrying the command.

Example

import { checkCommand } from 'cc-safety-net/api';

function canRun(command: string, cwd: string): boolean {
  try {
    const result = checkCommand({ command, cwd });
    if (result.kind === 'allow') return true;
    console.error(result.reason);
    return false;
  } catch (error) {
    console.error('CC Safety Net could not check the command', error);
    return false;
  }
}

canRun('git status', process.cwd());

What one call does

The function builds a command tool invocation named library-api, with the shell set to auto and both the config and execution working directories set to the resolved cwd. It then evaluates the guard directly. Because it calls the guard rather than an agent integration, it never executes the command, writes an audit record, changes configuration, or makes a network request. It checks commands in full, including any secret-file access a command performs. It does not check the host’s own non-shell file tools, such as read, write, edit, and search.

Environment

Every call reads the CC_SAFETY_NET_* settings from the process environment, so changing them changes later decisions. An invalid CC_SAFETY_NET_LEVEL is ignored and reported on stderr:

CC Safety Net: ignored invalid CC_SAFETY_NET_LEVEL="<value>". Use standard, strict, paranoid.

The reported value is JSON-quoted and truncated to its first 40 characters. See Environment variables for the full list.

Environment variables documents every setting a call reads.
Blocked commands lists what a deny can be.
Integration architecture covers the agent integrations this function replaces when the host runs its own commands.

Get started

Configuration

Reference

Guides

Project

Install and import

`checkCommand`

Input

Result

Errors

Unusable working directory

Example

What one call does

Environment

​Install and import

​checkCommand

​Input

​Result

​Errors

​Unusable working directory

​Example

​What one call does

​Environment

​Related pages

Install and import

`checkCommand`

Input

Result

Errors

Unusable working directory

Example

What one call does

Environment

Related pages