How Factory Droid Handles Tool Mapping from Bash to Execute

Factory Droid converts Claude Code's bash tool into the Droid runtime's Execute capability through a static translation table defined in src/converters/claude-to-droid.ts.

Factory Droid, part of the EveryInc/compound-engineering-plugin repository, bridges Claude Code plugins with the Droid agent runtime. A critical step in this pipeline is tool mapping from Bash to Execute, which ensures that when a Claude agent references shell commands, the resulting Droid agent receives the correct execution permissions.

The Core Translation Mechanism

The conversion relies on two key data structures in src/converters/claude-to-droid.ts: a bidirectional mapping table and a validation whitelist.

Mapping Definition in CLAUDE_TO_DROID_TOOLS

At lines 8–15, the converter defines a static record that pairs Claude tool names with their Droid equivalents:

const CLAUDE_TO_DROID_TOOLS: Record<string, string> = {
  // ...
  bash: "Execute",   // Bash → Execute mapping
  // ...
}

When the parser encounters the bash tool in a Claude agent definition, it looks up this key and replaces it with "Execute" for the Droid runtime.

Whitelist Validation with VALID_DROID_TOOLS

To prevent invalid tools from reaching the runtime, lines 26–36 declare a VALID_DROID_TOOLS array containing approved identifiers. This whitelist includes "Execute" among other valid capabilities, ensuring that the mapped tool is emitted only if it appears in this authorized set.

Extracting and Converting Agent Tools

The conversion process involves scanning agent definitions and rewriting their tool permissions into the final Droid bundle format.

Scanning Agent Bodies with mapAgentTools

The mapAgentTools function (lines 4–9) performs regex-style detection of tool references within an agent's textual content:

function mapAgentTools(agent: ClaudeAgent): string[] | undefined {
  const bodyLower = `${agent.name} ${agent.description ?? ""} ${agent.body}`.toLowerCase()
  const mentionedTools = new Set<string>()
  for (const [claudeTool, droidTool] of Object.entries(CLAUDE_TO_DROID_TOOLS)) {
    if (bodyLower.includes(claudeTool)) {
      mentionedTools.add(droidTool)   // "bash" ⇒ "Execute"
    }
  }
  // ...
}

This loop checks if the agent's name, description, or body contains the string "bash" (or other Claude tool names). When found, it adds the corresponding Droid tool—"Execute"—to the set of mentioned capabilities.

Writing Tools to Frontmatter

After extraction, the convertAgent function (lines 81–84) injects the collected tools into the agent's frontmatter metadata. This step produces the final .md file that Droid consumes, where the tools array contains "Execute" if the original Claude agent referenced bash commands.

Code Implementation Details

The complete mapping flow relies on these specific implementations in src/converters/claude-to-droid.ts:

// Static translation table (lines 8-15)
const CLAUDE_TO_DROID_TOOLS: Record<string, string> = {
  bash: "Execute",
  // ... other mappings
};

// Validation whitelist (lines 26-36)
const VALID_DROID_TOOLS = [
  "Execute",
  // ... other valid tools
];

// Extraction logic (lines 4-9 within mapAgentTools)
for (const [claudeTool, droidTool] of Object.entries(CLAUDE_TO_DROID_TOOLS)) {
  if (bodyLower.includes(claudeTool)) {
    mentionedTools.add(droidTool);
  }
}

Summary

• Factory Droid converts Claude Code plugins to Droid runtime format via src/converters/claude-to-droid.ts.
• The CLAUDE_TO_DROID_TOOLS map explicitly pairs bash with "Execute" at lines 8–15.
• The VALID_DROID_TOOLS whitelist ensures only authorized tools like "Execute" appear in final output (lines 26–36).
• mapAgentTools scans agent content for tool references and performs the translation (lines 4–9).
• convertAgent writes the mapped tools into the Droid agent's frontmatter metadata (lines 81–84).

Frequently Asked Questions

What is the CLAUDE_TO_DROID_TOOLS map?

The CLAUDE_TO_DROID_TOOLS map is a static TypeScript record defined in src/converters/claude-to-droid.ts that translates Claude tool names into their Droid equivalents. It contains the entry bash: "Execute", which directs the converter to replace any reference to the Claude bash tool with the Droid Execute capability.

How does Factory Droid validate mapped tools?

Factory Droid validates tools against the VALID_DROID_TOOLS array, a whitelist defined at lines 26–36 of src/converters/claude-to-droid.ts. This array contains approved tool identifiers including "Execute". Only tools appearing in this whitelist are emitted in the final Droid agent definition, preventing invalid or unsupported capabilities from reaching the runtime.

Where does the Execute tool appear in the final output?

The Execute tool appears in the tools array within the frontmatter of the generated Droid agent markdown files. The convertAgent function at lines 81–84 of src/converters/claude-to-droid.ts injects the collected tools into the frontmatter metadata, which the Droid runtime reads to determine which capabilities an agent is permitted to use.

Can I add custom tool mappings to Factory Droid?

Yes, you can extend the tool mapping by adding entries to the CLAUDE_TO_DROID_TOOLS record in src/converters/claude-to-droid.ts. Each entry should map a Claude tool name (string) to its corresponding Droid tool identifier. Ensure the target tool is also added to the VALID_DROID_TOOLS whitelist so the converter recognizes it as a valid capability for the Droid runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}