@atoms-agent/toolkit-coding

Optional coding toolkit for atoms_agent (v0.6): filesystem, git, process and shell tools with Host-owned Root, Operations Backend, and Permission Claims.

This package depends only on @atoms-agent/core public root exports. It does not depend on @atoms-agent/skills, @atoms-agent/mcp, or @atoms-agent/testing. It is not an OS Sandbox: Root bounds filesystem tools and process cwd; Shell can still reach the rest of the machine.

Install

npm install @atoms-agent/[email protected] @atoms-agent/[email protected]

Usage

import { createCodingToolkit } from "@atoms-agent/toolkit-coding";
import { createAgent } from "@atoms-agent/core";
import type { ModelAdapter } from "@atoms-agent/llm";

declare const workspaceRoot: string;
declare const model: ModelAdapter;

const toolkit = await createCodingToolkit({
  root: workspaceRoot,
  preset: "read-only",
  // Host may inject Fake/SSH/VM Operations; local defaults are progressive.
});

const agent = createAgent({
  model,
  systemPrompt: "Work only inside the configured workspace.",
  tools: [...toolkit.tools],
  authorize: ({ tool }) => (tool.sideEffect === "none" ? "allow" : "defer"),
});

void agent;

Presets

| Preset | Tools | | -------------------- | ---------------------------------------------------------------- | | read-only | read_file, list_directory, glob_files, search_text | | interactive-coding | read + edit_file / write_file + run_process | | full | all 16 tools (requires Host git / process / shell configs) |

Git tools need git: { executable }. Process needs process.programs. Shell needs explicit shell: { id, executable, args, transport } and is always high risk.

Only import from the package root. Subpath / deep imports are not supported.

Safety notes

• Pathspecs are Root-relative; symlink/junction and hardlink policies apply.
• Git uses argv-only spawn with fixed safety env/-c overrides (no shell).
• Process is Host program alias + argv; environment is minimal inherit + Host allowlist.
• Shell is arbitrary code execution; Root is not a sandbox.
• Claims use digests/counts, not large content or env values.

See docs/V06-CODING-TOOLKIT.md in the monorepo for the frozen contract.