# `MingaAgent.Tool.Executor`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_agent/tool/executor.ex#L1)

Executes agent tools through the registry with approval checking and
Config.Advice integration.

The execution pipeline:

1. Look up the tool spec in `MingaAgent.Tool.Registry`
2. Check the tool's approval level (`:auto`, `:ask`, `:deny`)
3. If `Minga.Config.Advice` has advice for the tool name (as an atom),
   wrap the execution through the advice chain
4. Execute the tool callback in the calling process (no spawning)
5. Return `{:ok, result}` or `{:error, reason}`

## ETS fast-path

The advice check is a single ETS read via `Minga.Config.Advice.advised?/1`.
When no advice is registered (the common case), the wrap is skipped
entirely and the callback runs directly.

## Approval

Tools with `:auto` approval execute immediately. Tools with `:deny`
are rejected. Tools with `:ask` return `{:needs_approval, spec}` so
the caller (typically `Agent.Session`) can request user confirmation
before calling `execute_approved/2`.

# `result`

```elixir
@type result() ::
  {:ok, term()}
  | {:error, term()}
  | {:needs_approval, MingaAgent.Tool.Spec.t(), map()}
```

Result of tool execution.

# `execute`

```elixir
@spec execute(String.t(), map()) :: result()
```

Executes a tool by name with the given arguments.

Looks up the spec in the registry, checks approval, optionally wraps
through Config.Advice, and runs the callback. Returns `{:ok, result}`,
`{:error, reason}`, or `{:needs_approval, spec, args}` for tools
that require user confirmation.

The optional third argument is the registry table name (for testing).

# `execute`

```elixir
@spec execute(String.t(), map(), atom()) :: result()
```

# `execute_approved`

```elixir
@spec execute_approved(MingaAgent.Tool.Spec.t(), map()) ::
  {:ok, term()} | {:error, term()}
```

Executes a tool that has already been approved by the user.

Skips the approval check and runs the callback directly (with
advice wrapping if applicable). Use this after receiving
`{:needs_approval, spec, args}` from `execute/2` and getting
user confirmation.

---

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