AirCoding/AirPlan/docs/architecture/tool-registry-v1.md

AirCoding V1.0.0 Alpha Tool Registry V1

Date: 2026-05-27 Status: Canonical V1.0.0 Alpha built-in tool registry

This document freezes the built-in tools required for the V1.0.0 Alpha skeleton. Additional tools may be added by capabilities/plugins later, but the tools here define the minimum stable execution surface.

Tool contract is defined in interface-contracts-v1.md §12 and exported from packages/contracts/tool.ts.

1. Registry Principles

1. Tools are schema-validated at input and output boundaries.
2. Tools emit lifecycle events from event-registry-v1.md: tool.started, tool.progress, tool.completed, tool.failed, tool.cancelled.
3. Tools must go through PermissionEngine before filesystem writes, command execution, network access, or system-sensitive operations.
4. File edit tools follow Claude Code style discipline: read-before-edit, exact replacement, small edits, no broad rewrite unless the tool is explicitly fs.write or template scaffolding.
5. Shell tools capture stdout/stderr as artifacts when output exceeds inline limits or when the command participates in verification evidence.
6. Tool implementations return structured outputs; human-readable summaries are presentation data, not the source of truth.
7. Tool names are stable API identifiers and use dotted namespaces.

2. Common Tool Types

ToolCategory, ToolResultEnvelope, ToolDefinition, ToolExecutor, StreamingToolExecutor, and ToolRegistry are defined in interface-contracts-v1.md §12. This document references those contracts; it does not re-define them.

Inline output limits are implementation config, but V1 defaults should be conservative:

stdout/stderr inline preview: 16 KiB each
file read inline default: 2000 lines
single tool event payload target: < 256 KiB
larger content: artifact reference

3. Filesystem Tools

fs.list v1

Category: filesystem. Permission: read paths.

Purpose: list directory entries with metadata.

Input:

interface FsListInput {
  path: string
  recursive?: boolean
  max_depth?: number
  include_hidden?: boolean
  glob?: string
}

Output:

interface FsListOutput {
  entries: Array<{
    path: string
    type: "file" | "directory" | "symlink" | "other"
    size_bytes?: number
    modified_at?: string
    target_path?: string
  }>
  truncated: boolean
}

fs.read v1

Category: filesystem. Permission: read paths.

Purpose: read text, binary metadata, images, PDFs, or notebooks through typed adapters.

Input:

interface FsReadInput {
  path: string
  offset_lines?: number
  limit_lines?: number
  pages?: string
  encoding?: "utf8" | "base64" | "auto"
}

Output:

interface FsReadOutput {
  path: string
  content?: string
  content_type: "text" | "binary" | "image" | "pdf" | "notebook" | "empty"
  line_count?: number
  truncated: boolean
  artifact_id?: string
}

fs.write v1

Category: filesystem. Permission: write paths.

Purpose: create new files or overwrite files only when explicitly authorized by the caller policy.

Input:

interface FsWriteInput {
  path: string
  content: string
  create_parent_dirs?: boolean
  expected_existing_sha256?: string
}

Output:

interface FsWriteOutput {
  path: string
  bytes_written: number
  sha256: string
  backup_artifact_id?: string
}

fs.edit v1

Category: filesystem. Permission: read/write paths.

Purpose: exact string replacement in an existing file.

Input:

interface FsEditInput {
  path: string
  old_string: string
  new_string: string
  replace_all?: boolean
  expected_existing_sha256?: string
}

Output:

interface FsEditOutput {
  path: string
  replacements: number
  sha256: string
  diff_artifact_id: string
}

Rules:

• The file must have been read in the active task before edit.
• old_string must be unique unless replace_all = true.
• The tool fails rather than guessing indentation or nearby replacements.

fs.patch v1

Category: filesystem. Permission: read/write paths.

Purpose: apply a unified patch generated by the execution layer.

Input:

interface FsPatchInput {
  patch: string
  strip?: number
  expected_paths?: string[]
}

Output:

interface FsPatchOutput {
  changed_files: string[]
  diff_artifact_id: string
  rejected_hunks_artifact_id?: string
}

fs.stat v1

Category: filesystem. Permission: read paths.

Purpose: inspect path metadata and realpath for permission decisions.

Input:

interface FsStatInput { path: string }

Output:

interface FsStatOutput {
  path: string
  realpath?: string
  exists: boolean
  type?: "file" | "directory" | "symlink" | "other"
  size_bytes?: number
  modified_at?: string
}

4. Shell and Process Tools

shell.run v1

Category: shell. Permission: execute plus command risk analysis.

Purpose: run a bounded non-interactive command.

Input:

interface ShellRunInput {
  command: string
  cwd: string
  timeout_ms?: number
  env?: Record<string, string>
  stdin?: string
  capture_mode?: "inline" | "artifact" | "both"
  purpose?: "build" | "test" | "debug" | "doctor" | "general"
}

Output:

interface ShellRunOutput {
  command_run_id: string
  exit_code: number
  duration_ms: number
  stdout_preview?: string
  stderr_preview?: string
  stdout_artifact_id?: string
  stderr_artifact_id?: string
  combined_artifact_id?: string
  parsed_diagnostics_json?: unknown
}

Rules:

• No interactive commands in V1 unless a dedicated tool owns the interaction model.
• Destructive commands require PermissionEngine approval based on command risk analysis.
• The command runner emits command.started, command stream deltas, and terminal command events.

process.kill v1

Category: shell/debug. Permission: execute; system-sensitive when target is outside AirCoding process tree.

Input:

interface ProcessKillInput {
  pid: number
  signal?: "SIGTERM" | "SIGKILL" | "SIGINT"
  reason: string
}

Output:

interface ProcessKillOutput {
  pid: number
  signal: string
  delivered: boolean
}

5. Git Tools

git.status v1

Category: git. Permission: read paths.

Input:

interface GitStatusInput { cwd: string }

Output:

interface GitStatusOutput {
  branch?: string
  clean: boolean
  staged: string[]
  modified: string[]
  untracked: string[]
  conflicted: string[]
}

git.diff v1

Category: git. Permission: read paths.

Input:

interface GitDiffInput {
  cwd: string
  base_ref?: string
  pathspecs?: string[]
  staged?: boolean
}

Output:

interface GitDiffOutput {
  diff: string
  diff_artifact_id?: string
  truncated: boolean
}

git.worktree.create v1

Category: git. Permission: write project-local paths.

Input:

interface GitWorktreeCreateInput {
  cwd: string
  path: string
  branch_name: string
  base_ref?: string
}

Output:

interface GitWorktreeCreateOutput {
  workspace_id: string
  path: string
  branch_name: string
  base_ref?: string
}

git.merge_workspace v1

Category: git. Permission: write project paths.

Input:

interface GitMergeWorkspaceInput {
  workspace_id: string
  strategy: "fast_forward" | "patch_apply" | "manual_merge"
  target_ref?: string
}

Output:

interface GitMergeWorkspaceOutput {
  status: "merged" | "conflicted" | "failed"
  changed_files: string[]
  diff_artifact_id?: string
  conflict_artifact_id?: string
}

6. Project Tools

project.scan v1

Category: project. Permission: read project paths.

Purpose: collect project metadata for initialization and profile updates.

Input:

interface ProjectScanInput {
  project_root: string
  include_directory_tree: true
  include_git_summary?: boolean
  include_extension_stats?: boolean
  include_special_files?: boolean
}

Output:

interface ProjectScanOutput {
  project_root: string
  directory_tree_artifact_id: string
  extension_stats: Record<string, number>
  special_files: string[]
  git_summary?: unknown
}

project.profile.write v1

Category: project. Permission: write .air/shared/project.json.

Input:

interface ProjectProfileWriteInput {
  project_root: string
  profile_json: unknown
  expected_schema_version?: number
}

Output:

interface ProjectProfileWriteOutput {
  path: string
  schema_version: number
  sha256: string
}

7. C++ Toolchain MVP Tools

cpp.detect v1

Category: build. Permission: read project paths.

Output includes detected build systems, compiler hints, test frameworks, and confidence notes.

interface CppDetectInput { project_root: string }
interface CppDetectOutput {
  build_systems: Array<"cmake" | "make" | "ninja" | "custom" | "unknown">
  preferred_build_system?: string
  source_roots: string[]
  test_roots: string[]
  notes: string[]
}

cpp.cmake.configure v1

Category: build. Permission: execute and write build directory.

interface CppCmakeConfigureInput {
  project_root: string
  build_dir: string
  generator_preference?: "ninja_then_make" | "ninja" | "make"
  cmake_args?: string[]
}
interface CppCmakeConfigureOutput {
  command_run_id: string
  compile_commands_path?: string
  diagnostics?: unknown
}

cpp.build v1

Category: build. Permission: execute and write build directory.

interface CppBuildInput {
  project_root: string
  build_dir?: string
  target?: string
  clean_first?: boolean
}
interface CppBuildOutput {
  command_run_id: string
  status: "passed" | "failed"
  diagnostics?: unknown
}

cpp.test v1

Category: test. Permission: execute project/build outputs.

interface CppTestInput {
  project_root: string
  build_dir?: string
  framework?: "ctest" | "gtest" | "custom"
  filter?: string
}
interface CppTestOutput {
  command_run_id: string
  status: "passed" | "failed"
  test_count?: number
  failed_tests?: string[]
  report_artifact_id?: string
}

cpp.static.cppcheck v1

Category: static_analysis. Permission: execute/read project paths.

interface CppcheckInput {
  project_root: string
  paths?: string[]
  compile_commands_path?: string
}
interface CppcheckOutput {
  command_run_id: string
  diagnostic_ids: string[]
  report_artifact_id?: string
}

cpp.clangd.query v1

Category: static_analysis. Permission: read project paths and execute clangd helper.

interface ClangdQueryInput {
  project_root: string
  compile_commands_path?: string
  query: "definition" | "references" | "symbols" | "diagnostics"
  file?: string
  line?: number
  column?: number
  symbol?: string
}
interface ClangdQueryOutput {
  results: unknown
  artifact_id?: string
}

8. Debug and Evidence Tools

debug.run v1

Category: debug. Permission: execute project/build outputs.

interface DebugRunInput {
  command: string
  cwd: string
  timeout_ms?: number
  collect_core_dump?: boolean
  collect_backtrace?: boolean
}
interface DebugRunOutput {
  command_run_id: string
  exit_code?: number
  crash_detected: boolean
  backtrace_artifact_id?: string
  core_dump_artifact_id?: string
}

debug.parse_logs v1

Category: debug. Permission: read paths.

interface DebugParseLogsInput {
  paths: string[]
  task_id?: string
  hint?: string
}
interface DebugParseLogsOutput {
  diagnostic_ids: string[]
  summary: string
  report_artifact_id?: string
}

9. GUI and Network Evidence Tools

gui.screenshot v1

Category: gui. Permission: read display/session state; system-sensitive if outside controlled test display.

interface GuiScreenshotInput {
  target: "active_window" | "display" | "window_title" | "pid"
  value?: string
}
interface GuiScreenshotOutput {
  screenshot_artifact_id: string
  width?: number
  height?: number
}

network.capture v1

Category: network. Permission: network and system-sensitive when packet capture requires elevated permissions.

interface NetworkCaptureInput {
  interface?: string
  duration_ms: number
  filter?: string
  reason: string
}
interface NetworkCaptureOutput {
  pcap_artifact_id?: string
  summary_artifact_id?: string
  packet_count?: number
}

10. Context, Artifact, Permission, and Doctor Tools

artifact.create v1

Category: artifact. Permission: write session artifact path.

interface ArtifactCreateInput {
  type: string
  original_name?: string
  content?: string
  source_path?: string
  associated_entity_type?: string
  associated_entity_id?: string
  metadata?: Record<string, unknown>
}
interface ArtifactCreateOutput {
  artifact_id: string
  uri: string
  path: string
  sha256?: string
  size_bytes?: number
}

context.assemble v1

Category: context. Permission: read DB/artifacts/rules.

interface ContextAssembleInput {
  task_id?: string
  purpose: "main" | "execute" | "review" | "debug" | "compact" | "mine_experience"
  refs?: string[]
  token_budget?: number
}
interface ContextAssembleOutput {
  canonical_format: "anthropic"
  messages_artifact_id: string
  omissions: string[]
  token_estimate?: number
  compaction_requested?: boolean
}

permission.request v1

Category: permission. Permission: internal.

interface PermissionRequestInput {
  subject: string
  risk_level: "low" | "medium" | "high" | "critical"
  reason: string
  options: string[]
  default_option?: string
  request_ref?: unknown
}
interface PermissionRequestOutput {
  prompt_id: string
  selected_option?: string
  decision_id?: string
}

doctor.run v1

Category: doctor. Permission: read system/project state; fix mode may require execute/write.

interface DoctorRunInput {
  mode: "read_only" | "fix"
  scope?: "startup" | "project" | "toolchain" | "release_gate"
  capabilities?: string[]
}
interface DoctorRunOutput {
  run_id: string
  status: "passed" | "issues_found" | "fixed" | "failed"
  issue_count: number
  blocking_issue_count: number
  report_artifact_id?: string
}

11. MVP Required Tool Index

fs.list
fs.read
fs.write
fs.edit
fs.patch
fs.stat
shell.run
process.kill
git.status
git.diff
git.worktree.create
git.merge_workspace
project.scan
project.profile.write
cpp.detect
cpp.cmake.configure
cpp.build
cpp.test
cpp.static.cppcheck
cpp.clangd.query
debug.run
debug.parse_logs
gui.screenshot
network.capture
artifact.create
context.assemble
permission.request
doctor.run

12. Post-MVP Tool Candidates

These are intentionally not required for the V1.0.0 Alpha skeleton:

image.generate
image.edit
browser.automate
gui.interact
container.run
package.manager.install
mcp.call
skill.run
clang-tidy native wrapper
sanitizer runner
coverage reporter

They may be registered by capabilities once the V1 registry, permission model, event schema, and artifact model are stable.