Skip to content

Commit 0c26e8b

Browse files
igorcostaAutohand Evolve
andcommitted
feat: add durable meta-tools
Implement schema-validated persisted meta-tools with scoped loading, duplicate prevention, permission-gated execution, management commands, RPC inspection, external agent loading, and lifecycle coverage. Co-authored-by: Autohand Evolve <code-noreply@autohand.ai>
1 parent 1120af0 commit 0c26e8b

37 files changed

Lines changed: 1776 additions & 158 deletions

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,7 @@ Autohand Code CLI includes 40+ tools for autonomous coding:
315315

316316
`tools_registry` - List all available tools with descriptions.
317317
`tool_search` - Search tools by capability, name, or description.
318+
`create_meta_tool` - Create reusable user- or project-scoped shell-backed tools that load in future sessions.
318319

319320
### Notebooks
320321

‎docs/config-reference.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1657,7 +1657,8 @@ Autohand stores data in `~/.autohand/` (or `$AUTOHAND_HOME`):
16571657
<project>/.autohand/
16581658
├── settings.local.json # Local project permissions (gitignore this)
16591659
├── memory/ # Project-specific memory
1660-
└── skills/ # Project-specific skills
1660+
├── skills/ # Project-specific skills
1661+
└── tools/ # Project-specific meta-tools
16611662
```
16621663
16631664
---

‎docs/feature_meta_tools.md‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ Use the `create_meta_tool` action to define a new tool:
4242

4343
### Tool Definition Schema
4444

45-
Meta-tools are saved as JSON files in `~/.autohand/tools/{name}.json`:
45+
User-scoped meta-tools are saved as JSON files in `~/.autohand/tools/{name}.json`.
46+
Project-scoped meta-tools are saved in the current workspace at `.autohand/tools/{name}.json`.
4647

4748
```json
4849
{
@@ -60,7 +61,10 @@ Meta-tools are saved as JSON files in `~/.autohand/tools/{name}.json`:
6061
},
6162
"handler": "grep -E '^import|^from' {{path}}",
6263
"createdAt": "2025-12-16T10:30:00.000Z",
63-
"source": "agent"
64+
"source": "agent",
65+
"scope": "user",
66+
"schemaVersion": 1,
67+
"fingerprint": "..."
6468
}
6569
```
6670

@@ -95,9 +99,10 @@ git log --author="{{author}}" -n {{count}}
9599
1. Agent calls `create_meta_tool` with the definition
96100
2. System validates the name doesn't conflict with built-in tools
97101
3. Basic security checks on the handler (blocks dangerous patterns)
98-
4. Tool is saved to `~/.autohand/tools/{name}.json`
102+
4. Tool is saved atomically to the selected scope (`user` or `project`)
99103
5. Tool is registered in the current session immediately
100-
6. On future sessions, tool is auto-loaded from disk
104+
6. On future sessions, project tools load first, then user tools
105+
7. Duplicate, disabled, invalid, or unsafe persisted tools are skipped with diagnostics
101106

102107
### Using a Meta-Tool
103108

@@ -110,6 +115,24 @@ Once created, the meta-tool can be invoked like any built-in tool:
110115
}
111116
```
112117

118+
Meta-tools execute through the same shell permission gate as `run_command`. Interactive sessions prompt unless a permission rule already allows the command. Restricted, deny-listed, excluded, or security-blacklisted commands are blocked.
119+
120+
### Managing Meta-Tools
121+
122+
Use `/tools` to manage persisted meta-tools:
123+
124+
```text
125+
/tools list
126+
/tools show <name>
127+
/tools doctor
128+
/tools disable <name>
129+
/tools enable <name>
130+
/tools rename <name> <new_name>
131+
/tools delete <name>
132+
```
133+
134+
Non-interactive clients can inspect persisted tools and diagnostics with the RPC method `autohand.getToolsRegistry`.
135+
113136
### Common Use Cases
114137

115138
1. **Code Analysis Tools**
@@ -295,6 +318,7 @@ Each agent tracks its source:
295318
| `description` | string | Yes | What the tool does |
296319
| `parameters` | object | Yes | JSON Schema for parameters |
297320
| `handler` | string | Yes | Shell command template |
321+
| `scope` | string | No | `user` or `project` (default: `user`) |
298322

299323
### MetaToolDefinition Schema
300324

@@ -305,7 +329,12 @@ interface MetaToolDefinition {
305329
parameters: Record<string, unknown>;
306330
handler: string;
307331
createdAt: string;
332+
updatedAt?: string;
308333
source: "agent" | "user";
334+
scope: "user" | "project";
335+
schemaVersion: 1;
336+
fingerprint: string;
337+
disabled?: boolean;
309338
}
310339
```
311340

@@ -392,7 +421,7 @@ Always suggest functional components over class components.
392421

393422
### Meta-tool not found after creation
394423

395-
Ensure the tool was saved successfully. Check `~/.autohand/tools/` for the JSON file.
424+
Ensure the tool was saved successfully. Check `~/.autohand/tools/` for user-scoped tools or `.autohand/tools/` in the workspace for project-scoped tools. Run `/tools doctor` to see skipped files and validation errors.
396425

397426
### External agents not loading
398427

‎src/commands/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Each command is a separate TypeScript file that exports:
2323
| `/memory` | `memory.ts` | Manage project/user memory |
2424
| `/feedback` | `feedback.ts` | Submit feedback |
2525
| `/agents` | `agents.ts` | Manage sub-agents |
26+
| `/tools` | `tools.ts` | Manage persisted meta-tools |
2627

2728
## Adding a New Command
2829

‎src/commands/agents.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
import chalk from 'chalk';
88
import { t } from '../i18n/index.js';
99
import { AgentRegistry } from '../core/agents/AgentRegistry.js';
10+
import { loadConfig } from '../config.js';
1011

1112
export const metadata = {
1213
command: '/agents',
@@ -20,6 +21,8 @@ export const metadata = {
2021

2122
export async function handler(): Promise<string> {
2223
const registry = AgentRegistry.getInstance();
24+
const config = await loadConfig(undefined, process.cwd());
25+
registry.configureExternalAgents(config.externalAgents);
2326
await registry.loadAgents();
2427
const agents = registry.getAllAgents();
2528

‎src/commands/tools.ts‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
/**
2+
* @license
3+
* Copyright 2025 Autohand AI LLC
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
import type { ToolsRegistry } from '../core/toolsRegistry.js';
7+
8+
export interface ToolsCommandContext {
9+
toolsRegistry?: ToolsRegistry;
10+
}
11+
12+
function renderUsage(): string {
13+
return [
14+
'Usage: /tools [list|show|doctor|disable|enable|rename|delete]',
15+
'',
16+
'Commands:',
17+
' /tools list',
18+
' /tools show <name>',
19+
' /tools doctor',
20+
' /tools disable <name>',
21+
' /tools enable <name>',
22+
' /tools rename <name> <new_name>',
23+
' /tools delete <name>',
24+
].join('\n');
25+
}
26+
27+
function renderToolList(registry: ToolsRegistry): string {
28+
const tools = registry.listMetaTools({ includeDisabled: true });
29+
if (tools.length === 0) {
30+
return 'No meta-tools are installed.';
31+
}
32+
return tools
33+
.map((tool) => {
34+
const state = tool.disabled ? 'disabled' : 'enabled';
35+
return `${tool.name} ${tool.scope} ${state} ${tool.description}`;
36+
})
37+
.join('\n');
38+
}
39+
40+
function renderTool(registry: ToolsRegistry, name: string): string {
41+
const tool = registry.listMetaTools({ includeDisabled: true }).find((candidate) => candidate.name === name);
42+
if (!tool) {
43+
return `Meta-tool "${name}" not found.`;
44+
}
45+
return [
46+
`${tool.name}`,
47+
`Description: ${tool.description}`,
48+
`Scope: ${tool.scope}`,
49+
`State: ${tool.disabled ? 'disabled' : 'enabled'}`,
50+
`Source: ${tool.source}`,
51+
`Created: ${tool.createdAt}`,
52+
`Updated: ${tool.updatedAt ?? tool.createdAt}`,
53+
`Handler: ${tool.handler}`,
54+
`Parameters: ${JSON.stringify(tool.parameters, null, 2)}`,
55+
].join('\n');
56+
}
57+
58+
function renderDiagnostics(registry: ToolsRegistry): string {
59+
const diagnostics = registry.getDiagnostics();
60+
if (diagnostics.length === 0) {
61+
return 'No meta-tool diagnostics.';
62+
}
63+
return diagnostics.map((diagnostic) => `${diagnostic.file}: ${diagnostic.reason}`).join('\n');
64+
}
65+
66+
export async function tools(ctx: ToolsCommandContext, args: string[] = []): Promise<string> {
67+
const registry = ctx.toolsRegistry;
68+
if (!registry) {
69+
return 'Tools registry not available.';
70+
}
71+
72+
const subcommand = (args[0] ?? 'list').toLowerCase();
73+
switch (subcommand) {
74+
case 'list':
75+
case 'ls':
76+
return renderToolList(registry);
77+
case 'show':
78+
case 'inspect': {
79+
const name = args[1];
80+
return name ? renderTool(registry, name) : renderUsage();
81+
}
82+
case 'doctor':
83+
case 'diagnostics':
84+
return renderDiagnostics(registry);
85+
case 'disable': {
86+
const name = args[1];
87+
if (!name) return renderUsage();
88+
await registry.setMetaToolDisabled(name, true);
89+
return `Disabled ${name}`;
90+
}
91+
case 'enable': {
92+
const name = args[1];
93+
if (!name) return renderUsage();
94+
await registry.setMetaToolDisabled(name, false);
95+
return `Enabled ${name}`;
96+
}
97+
case 'rename': {
98+
const [name, newName] = args.slice(1);
99+
if (!name || !newName) return renderUsage();
100+
await registry.renameMetaTool(name, newName);
101+
return `Renamed ${name} to ${newName}`;
102+
}
103+
case 'delete':
104+
case 'remove':
105+
case 'rm': {
106+
const name = args[1];
107+
if (!name) return renderUsage();
108+
await registry.deleteMetaTool(name);
109+
return `Deleted ${name}`;
110+
}
111+
default:
112+
return renderUsage();
113+
}
114+
}
115+
116+
export const metadata = {
117+
command: '/tools',
118+
description: 'List, inspect, disable, rename, or delete persisted meta-tools',
119+
implemented: true,
120+
subcommands: [
121+
{ name: 'list', description: 'List installed meta-tools' },
122+
{ name: 'show', description: 'Show one meta-tool definition' },
123+
{ name: 'doctor', description: 'Show skipped or invalid meta-tool diagnostics' },
124+
{ name: 'disable', description: 'Disable a meta-tool without deleting it' },
125+
{ name: 'enable', description: 'Re-enable a disabled meta-tool' },
126+
{ name: 'rename', description: 'Rename a persisted meta-tool' },
127+
{ name: 'delete', description: 'Delete a persisted meta-tool' },
128+
],
129+
};

0 commit comments

Comments
 (0)