影 kaged
← back to Architecture Decision Records Accepted

ADR-0033: Tool dot-namespace convention

  • Status: Accepted
  • Date: 2026-06-05
  • Deciders: @karasu
  • Supersedes: —
  • Superseded by: —

Context

Tool names in kaged use a dot-delimited <namespace>.<tool> convention (e.g. file.read, search.grep, code.lsp). This was established implicitly — no ADR codified it — and has worked well. ADR-0022 added new namespaces (kaged.issue.*, kaged.workflow.*) and ADR-0023 added plugin-prefix tool naming, but neither formally documented the namespace convention or its rules.

Two problems have emerged:

Problem 1: no codified namespace directory. Namespace assignment has been ad-hoc. file, search, code, debug, shell, and kaged exist without a stated rule for why each tool lives where it does. Future tools (edit.ast, web.search, compute.calc) need a consistent home.

Problem 2: file.edit is misnamespaced. The file namespace groups filesystem I/O tools (file.read, file.write, file.create). file.edit is not filesystem I/O — it is content editing via exact-string replacement. Grouping it with filesystem operations obscures its mechanism and blocks a natural edit namespace that can grow to include edit.ast (AST-aware structural editing). The naming should reflect the domain, not the substrate.

Decision

kaged adopts a formal dot-namespace convention for all tools. The convention assigns each tool to a domain-based namespace. file.edit is renamed to edit.text to establish the edit domain. The namespace directory is documented in this ADR and maintained in docs/specs/agent-tooling.md.

1. Namespace directory

Namespace Domain Current tools Future tools
file Filesystem I/O file.read, file.write, file.create —
edit Content editing edit.text edit.ast
search Content discovery search.grep, search.glob, search.ast search.ast_replace
code Code intelligence code.lsp —
shell Command execution shell.bash shell.eval, shell.ssh
web Web operations — web.search, web.browser
compute Pure computation — compute.calc
debug Debugging debug (unified) —
project Project management — project.recipe, project.todo
kaged System / meta / interaction kaged.checkpoint, kaged.issue, kaged.ask, kaged.form kaged.task, kaged.issue (expansion)
discover Tool discovery — discover.tool
media Media analysis — media.inspect
job Background jobs — job
<plugin>.* Plugin-defined per-plugin per-plugin

2. Naming rules

  • Tool names are dot-delimited: <namespace>.<method> or <namespace>.<subgroup>.<method>.
  • The namespace is the first segment before the first dot.
  • Built-in namespace names (file, edit, search, code, debug, shell, web, compute, project, kaged, discover, media, job) are reserved. Plugins cannot register tools under these namespaces.
  • debug and job are single-segment tools (no subgroup) — the namespace IS the tool name.
  • The DSL schema allows arbitrary tool names; this convention governs built-in tools only. Plugin tools use <plugin-name>.<method> per ADR-0023.

3. Rename: file.edit → edit.text

The only existing tool affected by this ADR. Rationale:

  • edit is the domain (content editing). text is the mechanism (exact-string replacement).
  • Pairs with future edit.ast (AST-aware structural editing), forming a coherent namespace.
  • Separates content editing concerns from filesystem I/O concerns.
  • The .text suffix clarifies the mechanism: exact-string text replacement, as opposed to structural or AST-based editing.

No other existing tools are renamed.

Consequences

What this commits us to

  • A formal namespace directory maintained in this ADR and reflected in docs/specs/agent-tooling.md § Namespaces.
  • New built-in tools MUST be assigned to an existing namespace or a new namespace documented here first (ADR amendment or new ADR).
  • A one-time rename of file.edit to edit.text across: tool definition (@kaged/agent-tooling), handler registration (@kaged/daemon), default tool list (@kaged/dsl), all tests, all documentation.
  • The file namespace drops from 4 tools to 3. The new edit namespace starts with 1 tool.

What this forecloses

  • Adding filesystem I/O tools under edit.* — the edit namespace is for content editing, not filesystem operations.
  • Using single-segment tool names for tools that have a clear domain (they get <domain>.<method>). Only debug and job are exempt.
  • Plugin tools claiming reserved namespace prefixes.

What becomes easier

  • Adding edit.ast as a natural sibling to edit.text without namespace awkwardness.
  • Reasoning about tool domains: file = filesystem, edit = content modification, search = content discovery.
  • Future tool naming: the directory removes ambiguity.

What becomes harder

  • Migration cost for file.edit → edit.text. Pre-alpha; the only consumers are the dogfood project and internal tests. External migration is not a concern.

Spec amendments required

# File Change
1 docs/specs/agent-tooling.md Rename file.edit section to edit.text. Update namespace table. Update provenance table. Update all inline references (audit events, test scenarios, open questions, implementation notes).
2 docs/specs/project-dsl.md Update tool resolution section: file namespace is now 3 tools, add edit namespace (1 tool). Update namespace count from "6 namespaces" to "7 namespaces". Update example tools: blocks referencing file.edit.
3 docs/specs/http-api.md Update resolved_tools example to use edit.text.
4 docs/specs/local-config.md Update default_tools example to use edit.text.

Existing ADRs amended

  • ADR-0022 — Tool namespaces kaged.issue.* and kaged.workflow.* are unaffected. The namespace count reference is updated.
  • ADR-0023 — Plugin-prefix naming unchanged. Reserved namespace list expanded to include edit.

Alternatives considered

Alternative A — Keep file.edit in the file namespace

Why tempting: zero migration cost. The name is already in use and works.

Why rejected: file.edit is not filesystem I/O. Grouping it with file.read/file.write conflates the mechanism (exact-string patching) with the substrate (a file). The edit namespace is a natural home that scales to edit.ast, edit.diff, etc. The cost of renaming now (pre-alpha, no external consumers) is trivially low compared to the cost of living with a misnamespaced tool forever.

Alternative B — Rename to file.text_edit (keep file namespace)

Why tempting: keeps all file-related tools together.

Why rejected: file.text_edit is still misnamespaced — the tool is not doing filesystem I/O, it is editing content. The file prefix implies filesystem-domain semantics (read, write, create) that don't apply to content editing. It also doesn't scale: file.ast_edit, file.diff_edit would further bloat the file namespace with tools that aren't about filesystem operations.

Alternative C — Don't codify a namespace convention; keep it informal

Why tempting: avoids the ceremony of an ADR for something that "just works."

Why rejected: the ad-hoc approach already produced a misnamespaced tool. Future tools (web.*, compute.*, media.*) will compound the problem without a clear directory. The ADR is small and the convention is already de facto — this just makes it de jure.

References