oh-my-opencode-slim/src/tools/codemap.md

src/tools/

Responsibility

src/tools/ exposes plugin tooling and runtime command hooks used by OpenCode.

• AST-aware search/replace via ast-grep stack.
• Remote fetch/transform utility via smartfetch (webfetch tool).
• Council orchestration via createCouncilTool (council.ts).
• (No custom subtask feature in V2 — use native background task + task_status)
• Runtime preset switching via /preset hook via createPresetManager (preset-manager.ts).

It is the bridge between plugin runtime integration (src/index.ts) and the lower-level implementations in feature folders.

Export surface (src/tools/index.ts)

• ast_grep_search, ast_grep_replace from ./ast-grep
• createWebfetchTool, WEBFETCH_DESCRIPTION, and related types from ./smartfetch

• createCouncilTool

• createPresetManager and PresetManager type

Design patterns

• Factory-based registration: each feature exposes a factory that returns an executable/tool or handler object bound to plugin context.
• Clear boundaries: all plugin lifecycle hooks are emitted from factory methods (handleCommandExecuteBefore, handleEvent, registerCommand) rather than in tool modules.
• Metadata-first output: tool calls return text plus internal metadata writes when possible (for richer UI surfaces).

Subsystems and data flow

Council tool path

• createCouncilTool defines council_session.
• execute performs guarded invocation:
  • validates toolContext and sessionID,
  • only allows direct use by agent: 'council' (or missing agent for backward compatibility),
  • calls CouncilManager.runCouncil(prompt, preset, parentSessionId).
• On success, appends a councillor response summary and normalized model list to output.
• On failure, returns a concise error string.
• Shows config deprecation warnings when CouncilManager exposes deprecated field metadata.

Preset-manager command path

• createPresetManager(ctx, config) returns:
  • registerCommand(opencodeConfig): injects /preset command definition if absent,
  • handleCommandExecuteBefore(input, output): intercepts /preset command handling.
• Command behavior:
  • no args → clear output and list available presets (active marker supported),
  • single token arg → switch preset through client.config.update(...) with mapped agent overrides,
  • multi-word arg → suggestion + no update.
• Mapping logic converts plugin preset override format (AgentOverrideConfig) into runtime SDK agent config (model, temperature, variant, options) and skips fields not supported in runtime updates (prompt, orchestratorPrompt, skills, mcps, displayName).
• In-memory activePreset supports immediate status display and updates after successful switches.

Smartfetch path

• createWebfetchTool owns fetch orchestration, permission prompts, cache checks, llms.txt probing, binary/text branching, and optional secondary-model post-processing.
• smartfetch modules split work into:
  • transport/policy (network.ts),
  • cache + TTL semantics (cache.ts),
  • output shaping (utils.ts),
  • file-backed binaries (binary.ts),
  • secondary-model summarization (secondary-model.ts),
  • constants and types.
• webfetch is always registered from src/index.ts as a public tool.

AST-grep path

• ast-grep is split into CLI/CLI-discovery and tool-definition concerns.
• ast_grep_search/ast_grep_replace execution calls into runSg, which handles argument normalization, binary availability, timeout/error handling, and output truncation.
• src/tools/ast-grep/index.ts re-exports tool definitions and utility helpers for discoverability (ensureCliAvailable, getAstGrepPath, downloader/runtime checks).

Integration points in src/index.ts

• Tool registration:

  • council tools (only when config.council exists),

  • webfetch,

  • AST tools.

• presetManager is initialized in plugin init and:

  • calls registerCommand during config hook,
  • handles command interception in command.execute.before.

• /preset handling is explicitly user-facing (command hook), while webfetch and council are tool-facing.