# `ALLM.ToolResultEncoder.JSON`
[🔗](https://github.com/cykod/ALLM/blob/v0.3.0/lib/allm/tool_result_encoder/json.ex#L1)

Default `ALLM.ToolResultEncoder` — JSON-encodes the tool return value
via `Jason.encode!/1`, with targeted passthrough / unwrap shortcuts so
handlers that pre-format a string for the model aren't double-encoded.

## Input-shape → output-shape

| Input                       | Output                                |
|-----------------------------|---------------------------------------|
| `"already a string"`        | `"already a string"` (unchanged)      |
| `""`                        | `""` (unchanged)                      |
| `%{a: 1}`                   | `~s({"a":1})`                         |
| `[1, 2, 3]`                 | `"[1,2,3]"`                           |
| `{:ok, %{a: 1}}`            | `~s({"ok":{"a":1}})`                  |
| `{:ok, "inner"}`            | `~s({"ok":"inner"})`                  |
| `{:error, :not_found}`      | `~s({"error":":not_found"})`          |
| `{:error, "reason"}`        | `~s({"error":"reason"})` (verbatim)   |
| `{:error, %RuntimeError{}}` | `~s({"error":"%RuntimeError{…}"})`    |
| `nil`                       | `"null"`                              |
| `42`                        | `"42"`                                |
| `true` / `false`            | `"true"` / `"false"`                  |

Non-JSON-encodable values (PIDs, refs, bare tuples, funs) raise
`Protocol.UndefinedError` — Jason dispatches through the
`Jason.Encoder` protocol and a missing impl surfaces at dispatch time,
not as a `Jason.EncodeError`. The orchestrator wraps the call in
`try/rescue` and converts the raise to
`{:error, %ALLM.Error.ToolError{reason: :encoding_failed}}` (Phase 6).

Used automatically when `engine.tool_result_encoder` is `nil`; the
call site resolves to this module via
`engine.tool_result_encoder || ALLM.ToolResultEncoder.JSON`.

Users who want a different encoding (MessagePack, XML, Protobuf) plug
in their own module implementing `ALLM.ToolResultEncoder`.

# `encode`

```elixir
@spec encode(term()) :: String.t()
```

Serialize a tool's return value into a JSON string.

See the module doc for the full input-shape → output-shape table.

## Examples

    iex> ALLM.ToolResultEncoder.JSON.encode("pre-formatted")
    "pre-formatted"

    iex> ALLM.ToolResultEncoder.JSON.encode({:ok, %{a: 1}}) |> Jason.decode!()
    %{"ok" => %{"a" => 1}}

    iex> ALLM.ToolResultEncoder.JSON.encode({:error, :not_found}) |> Jason.decode!()
    %{"error" => ":not_found"}

---

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