# How Factory Droid Handles Tool Mapping from Bash to Execute

> Learn how Factory Droid maps bash tools to Execute capabilities using a static translation table in src/converters/claude-to-droid.ts for efficient command execution.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-droid.ts):

```typescript
// 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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.