# `PtcRunner.SubAgent.BuiltinTools`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/sub_agent/builtin_tools.ex#L1)

Pure functions for resolving builtin tool families into tool maps.

Extracted from `PtcRunner.SubAgent` to break a runtime dependency cycle
between `SubAgent`, `Loop`, and `SystemPrompt`.

# `effective_tools`

```elixir
@spec effective_tools(map()) :: map()
```

Returns the agent's tools with builtin tools injected.

Merges `llm_query` and `builtin_tools` families into the tools map.
User-defined tools are never overwritten by builtins.

## Examples

    iex> agent = PtcRunner.SubAgent.new(prompt: "test", builtin_tools: [:grep])
    iex> tools = PtcRunner.SubAgent.BuiltinTools.effective_tools(agent)
    iex> Map.has_key?(tools, "grep")
    true

    iex> agent = PtcRunner.SubAgent.new(prompt: "test", builtin_tools: [:grep], tools: %{"grep" => fn _ -> :custom end})
    iex> tools = PtcRunner.SubAgent.BuiltinTools.effective_tools(agent)
    iex> is_function(tools["grep"])
    true

# `expand_builtin_tools`

```elixir
@spec expand_builtin_tools([atom()]) :: [{String.t(), atom()}]
```

Expands a list of builtin tool family atoms to `[{name, sentinel}]` pairs.

Useful for external modules that need to generate tool descriptions
for builtins without reaching into SubAgent internals.

## Examples

    iex> PtcRunner.SubAgent.BuiltinTools.expand_builtin_tools([:grep])
    [{"grep", :builtin_grep}, {"grep-n", :builtin_grep_n}]

    iex> PtcRunner.SubAgent.BuiltinTools.expand_builtin_tools([])
    []

---

*Consult [api-reference.md](api-reference.md) for complete listing*