AGENTS.md

1# src/tools/ — 12–31 Native Tools Across 13 Tool Directories (+ shared utilities)
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7Tools registered via [`createToolRegistry()`](../plugin/tool-registry.ts) in `src/plugin/`. Native tools are factory-based (`createXXXTool`) except `interactive_bash` (`ToolDefinition`). LSP tools are served by the Tier-1 built-in MCP `lsp`; structural search and rewrite is handled by the `ast-grep` skill.
8 
9## TOOL CATALOG
10 
11### Always On (12 native tools)
12 
13| Group | Tools |
14|-------|-------|
15| **Search** (2) | `grep`, `glob` |
16| **Sessions** (4) | `session_list`, `session_read`, `session_search`, `session_info` |
17| **Background tasks** (2) | `background_output`, `background_cancel` |
18| **Delegation** (2) | `task` (delegate, full skill+category support), `call_omo_agent` (named agent only: explore, librarian) |
19| **Skills/MCP** (2) | `skill` (load skill or invoke command), `skill_mcp` (call skill-embedded MCP tool/resource/prompt) |
20 
21> LSP tools are provided by the built-in `lsp` MCP (Tier-1 stdio), backed by `packages/lsp-tools-mcp/`. AST-aware code search and rewrite is available through the `ast-grep` skill using `sg`.
22 
23### Conditional (up to +19 native tools)
24 
25| Tool(s) | Gate | Source |
26|---------|------|--------|
27| `look_at` | not in `disabled_agents` for `multimodal-looker` | `look-at/` |
28| `interactive_bash` | `isInteractiveBashEnabled(config)` (tmux config) | `interactive-bash/` |
29| `task_create`, `task_get`, `task_list`, `task_update` | `experimental.task_system` | `task/` |
30| `edit` (hashline-edit) | `hashline_edit: true` | `hashline-edit/` |
31| 12 `team_*` tools | `team_mode.enabled: true` | `../features/team-mode/tools/` |
32 
33### 12 team_* Tools (when team_mode enabled)
34 
35| Tool | Purpose |
36|------|---------|
37| `team_create` | Spawn team + member sessions from a TeamSpec (named or inline) |
38| `team_delete` | Tear down — removes mailbox, tasklist, worktrees, optional tmux layout |
39| `team_shutdown_request` | Member or lead requests its own shutdown |
40| `team_approve_shutdown` | Lead acks a pending shutdown |
41| `team_reject_shutdown` | Lead rejects a shutdown with reason |
42| `team_send_message` | Async message to specific member or `*` broadcast |
43| `team_task_create` | Create task on shared list |
44| `team_task_list` | List tasks (filter by status, owner) |
45| `team_task_update` | Claim/complete/delete (atomic file lock) |
46| `team_task_get` | Fetch single task |
47| `team_status` | Full team run status (members, tasks, mailbox) |
48| `team_list` | List declared + active teams |
49 
50## DELEGATION CATEGORIES (built-in 8)
51 
52`task` (delegate) selects model by category. Default category models live in provider-specific files under `src/tools/delegate-task/` and aggregate via `BUILTIN_CATEGORIES` in `builtin-categories.ts`. Authoritative fallback chains live in [`packages/model-core/src/category-model-requirements.ts`](../../../model-core/src/category-model-requirements.ts) `CATEGORY_MODEL_REQUIREMENTS`.
53 
54| Category | Default Model | Source File | Domain |
55|----------|---------------|-------------|--------|
56| `visual-engineering` | anthropic/claude-opus-5 (variant: max) | google-categories.ts | Frontend, UI/UX |
57| `ultrabrain` | openai/gpt-5.6-sol (variant: xhigh) | openai-categories.ts | Hard logic / heavy reasoning |
58| `deep` | openai/gpt-5.6-sol (variant: medium) | openai-categories.ts | Autonomous multi-step problem-solving |
59| `artistry` | anthropic/claude-fable-5 (variant: xhigh) | google-categories.ts | Creative / unconventional approaches |
60| `quick` | kimi-for-coding/kimi-for-coding-highspeed | openai-categories.ts | Trivial single-file changes |
61| `unspecified-low` | openai/gpt-5.6-luna (variant: xhigh) | openai-categories.ts | Moderate effort fallback |
62| `unspecified-high` | kimi-for-coding/kimi-k3 (variant: max) | anthropic-categories.ts | High effort fallback |
63| `writing` | kimi-for-coding/kimi-k3 (variant: low) | kimi-categories.ts | Documentation, prose |
64 
65User-defined categories declared in `categories: { ... }` config override and extend this set.
66 
67## TOOL DIR LAYOUT
68 
69```
70tools/
71├── background-task/      # background_output, background_cancel (LLM interface; engine in features/background-agent)
72├── call-omo-agent/       # call_omo_agent (explore + librarian only)
73├── delegate-task/        # task — full delegation with categories + skills
74├── glob/                 # glob (60s timeout, 100 file limit)
75├── grep/                 # grep (60s timeout, 10MB limit)
76├── hashline-edit/        # edit — hash-anchored line edits with LINE#ID validation
77├── interactive-bash/     # interactive_bash — tmux session control
78├── look-at/              # look_at — image/PDF analysis
79├── session-manager/      # 4 session_* tools
80├── skill/                # skill — load skill or run command
81├── skill-mcp/            # skill_mcp — call skill-embedded MCP servers
82├── slashcommand/         # discoverCommandsSync — feeds skill tool with /-command list
83├── task/                 # 4 task_* tools (Sisyphus task system)
84└── index.ts              # barrel exports
85```
86 
87## ADDING A NEW TOOL
88 
891. Create `src/tools/{name}/index.ts` with factory `createXXXTool`
902. Add `types.ts` for parameter Zod schemas
913. Add `tools.ts` (or single index.ts) for implementation
924. Export factory from `src/tools/index.ts`
935. Register in `src/plugin/tool-registry.ts`:
94   - Always-on: spread into `allTools` directly
95   - Conditional: build a `Record<string, ToolDefinition>` and gate-spread
966. If the tool needs disabling, ensure it appears in `filterDisabledTools` allow-list (its name will be matched against `disabled_tools`)
97