feat(tools): add ToolRegistry, ToolSearchTool and ExpertTool to support on-demand tool visibility, discovery, activation, and expert/subagent tooling; extend DualAgentOrchestrator API and interfaces to manage tool lifecycle

readme.hints.md

@@ -7,6 +7,7 @@
 - **DualAgentOrchestrator**: Main entry point, coordinates Driver and Guardian agents
 - **DriverAgent**: Reasons about tasks, plans steps, proposes tool calls (supports both XML and native tool calling)
 - **GuardianAgent**: Evaluates tool calls against configured policies
+- **ToolRegistry**: Manages tool lifecycle, visibility, and discovery
 - **BaseToolWrapper**: Base class for creating custom tools
 - **plugins.ts**: Imports and re-exports smartai and other dependencies
 
@@ -19,6 +20,49 @@
 
 ## Additional Tools (must register manually)
 6. **JsonValidatorTool** - JSON validation and formatting (NOT in registerStandardTools)
+7. **ToolSearchTool** - AI-facing interface for tool discovery and activation
+8. **ExpertTool** - Wraps a DualAgentOrchestrator as a specialized expert tool
+
+## Tool Visibility System
+Tools can be registered with visibility modes:
+- **initial**: Always visible to Driver, included in system prompt (default)
+- **on-demand**: Only discoverable via search, must be activated before use
+
+```typescript
+// Register with visibility options
+orchestrator.registerTool(myTool, {
+  visibility: 'on-demand',
+  tags: ['database', 'sql'],
+  category: 'data'
+});
+```
+
+## Expert/SubAgent System
+Experts are specialized agents wrapped as tools, enabling hierarchical agent architectures:
+
+```typescript
+orchestrator.registerExpert({
+  name: 'code_reviewer',
+  description: 'Reviews code for quality and best practices',
+  systemMessage: 'You are a code review expert...',
+  guardianPolicy: 'Allow read-only file access',
+  tools: [new FilesystemTool()],
+  visibility: 'on-demand',
+  tags: ['code', 'review']
+});
+```
+
+## Tool Search
+Enable tool discovery for the Driver:
+
+```typescript
+orchestrator.enableToolSearch();
+// Driver can now use:
+// - tools.search({"query": "database"})
+// - tools.list({})
+// - tools.activate({"name": "database_expert"})
+// - tools.details({"name": "filesystem"})
+```
 
 ## Key Features
 - Token streaming support (`onToken` callback)
@@ -28,6 +72,9 @@
 - Result truncation with configurable limits
 - History windowing to manage token usage
 - **Native tool calling mode** (`useNativeToolCalling: true`) for providers like Ollama
+- **Tool visibility system** (initial vs on-demand)
+- **Expert/SubAgent system** for hierarchical agents
+- **Tool search and discovery** via ToolSearchTool
 
 ## Native Tool Calling
 When `useNativeToolCalling` is enabled: