Compose Extension Tools and Agents

Separate evidence collection from judgment

Tools should perform a bounded operation and return inspectable output. Agents should interpret that output using a focused rubric. Keeping those responsibilities separate makes authorization clearer, tests more deterministic, and prompts easier to review.

Layer	Good responsibility	Avoid
Tool	List commits since a revision	Ask an LLM to invent release notes inside a shell handler
Tool	Run one named test file	Accept an arbitrary command string from the caller
Agent	Classify a reproduced test failure and cite files	Claim a root cause without reproducing or reading evidence
Agent	Build a release checklist from exact ranges	Publish, tag, or push without an explicit product workflow

Design tools for predictable authorization

Tool descriptions are visible to the model, while handlers are visible to package reviewers and the authorization system. Use both to make intent clear. A read-only Git command may still require approval according to the user's policy; describe it as read-only without promising that it will bypass a prompt.

{
  "name": "changed_files_since",
  "description": "List files changed between a base revision and HEAD",
  "parameters": {
    "type": "object",
    "properties": {
      "base": {
        "type": "string",
        "description": "Base branch, tag, or commit"
      }
    },
    "required": ["base"]
  },
  "handler": "git diff --name-only {{base}}...HEAD",
  "source": "user"
}

At invocation, Autohand shell-escapes base, checks tool availability and plan-mode rules, evaluates immutable security patterns, resolves permission context, runs pre-tool hooks, obtains any required approval, executes, and records lifecycle/accounting events.

Use narrow inputs

Prefer path, base, count, or file over generic args.
Require every value used by the handler template.
Keep a command's executable and fixed options in the handler, not caller input.
Use repository-relative paths when the operation is about the active workspace.
Split read-only discovery from mutation so denial and approval behavior are understandable.
Bound potentially large output in the command itself, such as a Git log count.

Shell escaping is not a product boundary by itself. A narrowly designed handler, install-time safety checks, and invocation-time authorization work together. Do not expose a parameter whose intended value is an arbitrary shell fragment.

Give each agent a specialist contract

A good description tells the parent agent when delegation is useful. The prompt then defines process and output quality. Keep the tool allowlist small enough that a reviewer can understand the specialist's reach.

---
description: Reproduce and triage focused test failures before proposing a fix
tools: read_file, fff_grep, run_focused_test
---
Start from the exact failing test and error.
Reproduce it, trace the real production path, and separate product failures
from environment noise. Propose the smallest contract-preserving correction.
Do not weaken assertions merely to make a test pass.

The file name becomes the agent name. Choose a stable, specific file name such as failure-triage.md. Renaming the file changes the callable identity and should be treated as a compatibility change.

Understand allowlist resolution

The agent's tools frontmatter is a requested allowlist, not a grant. Autohand builds the active registry from built-ins, persisted tools, extensions, and other runtime integrations, removes conflicts, applies client-context filtering, then gives the specialist only matching names.

This has two important consequences:

If the extension tool is invalid, disabled, conflicting, or filtered out, listing its name in the agent does not make it available.
If the tool is active, its invocation still goes through normal approval and permission checks inside the sub-agent or teammate path.

Test the pair, not only each file

Validate the package and assert exact tool and agent contribution names.
Install it into an isolated user or project root.
Inspect provenance with extensions show.
Invoke each tool directly with a normal approval policy.
Delegate a representative task to each agent and confirm it chooses the intended tool.
Deny the tool call and confirm the agent reports the limitation instead of bypassing it.
Disable the package and confirm both tool and agent disappear together.
Enable it, start a fresh process, and repeat a smoke task.

For a complete build, use the Test Triage tutorial.