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:

```text
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:

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

Output:

```ts
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:

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

Output:

```ts
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:

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

Output:

```ts
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:

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

Output:

```ts
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:

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

Output:

```ts
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:

```ts
interface FsStatInput { path: string }
```

Output:

```ts
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:

```ts
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:

```ts
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:

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

Output:

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

## 5. Git Tools

### `git.status` v1

Category: git. Permission: read paths.

Input:

```ts
interface GitStatusInput { cwd: string }
```

Output:

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

### `git.diff` v1

Category: git. Permission: read paths.

Input:

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

Output:

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

### `git.worktree.create` v1

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

Input:

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

Output:

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

### `git.merge_workspace` v1

Category: git. Permission: write project paths.

Input:

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

Output:

```ts
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:

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

Output:

```ts
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:

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

Output:

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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

```text
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:

```text
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.