@wrongstack/tools

Built-in tools the WrongStack agent uses to read, edit, and act on the user's project.

Each tool implements the Tool interface from @wrongstack/core, with a JSON schema, an execute function, a permission level (auto / confirm / deny), and security gates appropriate to its blast radius.

Install

pnpm add @wrongstack/tools @wrongstack/core

Catalog

Filesystem

Execution

Network

Project lifecycle

Agent control

Quick example

import { ToolRegistry } from '@wrongstack/core';
import { readTool, editTool, bashTool, builtinTools } from '@wrongstack/tools';

// Cherry-pick:
const tools = new ToolRegistry([readTool, editTool, bashTool]);

// Or take the whole built-in set:
const all = new ToolRegistry(builtinTools);

Security properties (0.1.6 hardening)

• bash / exec child env sanitized to a fixed allowlist + secret-substring strip (TOKEN / SECRET / PASSWORD / AUTH / BEARER / COOKIE / PRIVATE / KEY). Opt-out via WRONGSTACK_BASH_ENV_PASSTHROUGH=1.
• bash POSIX process-group kill with SIGTERM → 800 ms → SIGKILL. Runaway grandchildren can't survive the timeout.
• fetch SSRF defenses: numeric CIDR checks for IPv4 (10/8, 127/8, 169.254/16, 100.64/10, 224/4, 240/4, …) and 8-group-expanded IPv6 (including Node's compressed ::ffff:7f00:1 form for v4-mapped addresses). Redirect target re-validated on every hop. http:// downgrade refused.
• patch diff-target validation: every +++ target post-strip is resolved against projectRoot before GNU patch sees the diff. strip clamped to ≥1. Temp diff written to a 0700 mkdtemp directory. Run with LANG=C / LC_ALL=C.
• replace / grep symlink-safe: lstat + realpath + projectRoot revalidation; symlinks skipped, not followed.
• User-regex ReDoS guard (_regex.ts): 512-char cap, nested-quantifier rejection ((a+)+, (?:x+)*), 64 KB subject-line cap. Applied to grep, replace, logs.
• git args raw string removed — the -c core.sshCommand=… RCE bypass is no longer reachable.
• grep stdout buffer capped at 1 MB — pathological producers can't pin memory.
• logs rolling window of 100k lines max; lines: 0 no longer means "buffer the whole file".

Full threat model: SECURITY.md at the repo root.

Writing a custom tool

import type { Tool } from '@wrongstack/core';

export const echoTool: Tool<{ text: string }, string> = {
  name: 'echo',
  description: 'Echo a string back.',
  inputSchema: {
    type: 'object',
    properties: { text: { type: 'string' } },
    required: ['text'],
  },
  permission: 'auto',
  mutating: false,
  // Tells permission policy which input field is the trust subject
  subjectKey: 'text',
  async execute(input, _ctx, { signal }) {
    if (signal.aborted) throw new Error('aborted');
    return input.text;
  },
};

See docs/tool-author-guide.md for the full contract.

License

MIT