# The agent loop

`ExAthena.Loop` is the engine that drives multi-turn tool-using conversations.
`ExAthena.run/2` is the thin facade you'll call in practice.

## End-to-end example

```elixir
config :ex_athena,
  default_provider: :ollama

config :ex_athena, :ollama,
  base_url: "http://localhost:11434",
  model: "qwen2.5-coder"

result =
  ExAthena.run(
    "read mix.exs and list the deps",
    tools: [
      ExAthena.Tools.Read,
      ExAthena.Tools.Glob,
      ExAthena.Tools.Grep
    ],
    cwd: "/path/to/my/project",
    phase: :plan
  )

IO.puts(result.text)
```

The loop:

1. Sends the request to the provider with the tool schemas.
2. Parses the response — text only, or text + `tool_calls`.
3. For each tool call: checks `Permissions` + `PreToolUse` hooks → executes
   the tool → fires `PostToolUse` hooks → appends a tool-result message.
4. Replays everything back to the provider and repeats.
5. Stops when the model responds with text and no tool calls, or hits
   `:max_iterations` (default 25).

## Multi-turn: `ExAthena.Session`

For user-facing chat where the conversation spans multiple messages, use
a `Session`:

```elixir
{:ok, pid} = ExAthena.Session.start_link(
  provider: :ollama,
  model: "qwen2.5-coder",
  tools: :all,
  cwd: "/path/to/project",
  system_prompt: "You are a senior Elixir engineer."
)

{:ok, r1} = ExAthena.Session.send_message(pid, "look at the auth module")
{:ok, r2} = ExAthena.Session.send_message(pid, "ok now add a password-reset flow")
# r2 has the full context of r1 because the Session persists message history.

ExAthena.Session.stop(pid)
```

## Permissions

Five modes, with deny-first ordering — denylist always wins:

```elixir
# Read-only exploration
ExAthena.run("explore", tools: :all, phase: :plan)

# Auto-allow edits, still prompt for bash + custom tools
ExAthena.run("refactor", tools: :all, phase: :accept_edits, can_use_tool: ask)

# Trust mode — skip the callback for every tool. Denylist still respected.
ExAthena.run("CI agent", tools: :all, phase: :trusted)

# Full YOLO — opt-in only:
ExAthena.run("CI agent", tools: :all, phase: :trusted, respect_denylist: false)

# Deny specific tools regardless of phase
ExAthena.run("refactor", tools: :all, disallowed_tools: ["web_fetch"])

# Restrict to an allowlist
ExAthena.run("summarise", tools: :all, allowed_tools: ["read", "glob"])

# Interactive approval
can_use_tool = fn name, args, _ctx ->
  case name do
    "bash" -> ask_user("Run `#{args["command"]}`?")
    _ -> :allow
  end
end

ExAthena.run("deploy", tools: :all, can_use_tool: can_use_tool)
```

See the [permissions guide](permissions.md) for the full ordering, the
`:auto` reservation, and `can_use_tool` callback contract.

## Hooks

Hooks fire at 14 lifecycle events so hosts can:

- Deny specific tool calls mid-loop (`PreToolUse` returning `{:deny, reason}`)
- Capture tool outputs (`PostToolUse`)
- React to conversation end (`Stop` / `StopFailure` / `SessionEnd`)
- Inject context (`{:inject, msg}` from any event)
- Rewrite the user's prompt (`{:transform, prompt}` from `UserPromptSubmit`)
- Observe permission denials, subagent spawns, compaction stages

See the [hooks reference](hooks_reference.md) for the full event
catalog + payload shapes.

```elixir
deny_protected = fn %{tool_name: name, tool_input: %{"path" => path}}, _id ->
  if name in ["write", "edit"] and String.contains?(path, "priv/secrets") do
    {:deny, permission_decision_reason: "protected path"}
  else
    :ok
  end
end

capture_test = fn %{tool_name: "bash", tool_input: %{"command" => cmd}, result: result}, _id ->
  if String.contains?(cmd, "mix test") do
    MyApp.Store.save_test_run(result)
  end

  :ok
end

ExAthena.run("ship it",
  tools: :all,
  hooks: %{
    PreToolUse: [%{matcher: "write|edit", hooks: [deny_protected]}],
    PostToolUse: [%{matcher: "bash", hooks: [capture_test]}]
  })
```

## Streaming to a UI

Pass `:on_event` for LiveView-friendly updates:

```elixir
live_pid = self()

ExAthena.run("explain the architecture",
  tools: :all,
  on_event: fn event -> send(live_pid, {:athena_event, event}) end)
```

The loop emits flat tuples: `{:content, text}`, `{:tool_call, tc}`,
`{:tool_result, tr}`, `{:tool_ui, %{tool_call_id, kind, payload}}`,
`{:iteration, n}`, `{:compaction, metadata}`, `{:subagent_spawn, ...}`,
`{:subagent_result, ...}`, `{:usage, map}`, `{:done, Result.t()}`.

`:tool_ui` is the structured-payload sibling of `:tool_result` — see
the [tools guide](tools.md) for the per-tool kinds.

## Sub-agents

The `SpawnAgent` tool lets a model delegate focused work to a fresh
sub-conversation. v0.4 ships three builtin agent definitions — invoke
by name:

```elixir
# Read-only investigation
ExAthena.run("find the bug",
  tools: :all,
  assigns: %{spawn_agent_opts: [provider: :ollama, model: "qwen2.5-coder"]})

# Inside the loop, the model emits:
# spawn_agent(prompt: "explore the auth module", agent: "explore")
```

Built-in defs: `general` (full-tool default), `explore` (read-only +
`web_fetch`), `plan` (writes restricted to `.exathena/plans/*.md`).
Custom defs live at `.exathena/agents/<name>.md`. With
`isolation: :worktree` set in frontmatter, the subagent runs in an
isolated git checkout. The parent sees only the subagent's final text.

See [agents + subagents](agents_subagents.md) for the full surface.

## Memory + Skills

Drop an `AGENTS.md` at your project root for project-specific rules;
ex_athena prepends it as user-context on every turn. Drop `SKILL.md`
files under `.exathena/skills/<name>/` and they appear in the
system-prompt catalog at ~50 tokens; the body loads when the model
emits `[skill: <name>]`.

Override discovery on a per-call basis:

```elixir
ExAthena.run("hi", tools: :all, memory: false, skills: false)
ExAthena.run("hi", tools: :all, preload_skills: ["deploy", "audit"])
```

See [memory + skills](memory_and_skills.md).

## Sessions + checkpointing

`Session.start_link/1` accepts `:store` — `:in_memory` (default) or
`:jsonl` for durable storage. Resume a prior session:

```elixir
{:ok, prior_messages} = ExAthena.Session.resume("session-id-from-disk", store: :jsonl)

{:ok, pid} = ExAthena.Session.start_link(
  store: :jsonl,
  session_id: "session-id-from-disk",
  messages: prior_messages,
  provider: :ollama, model: "qwen2.5-coder",
  tools: :all
)
```

Every `Edit` / `Write` snapshots the prior file contents to
`.exathena/file-history/<session>/<sha>/<v>.bin`. `/rewind` restores
files + truncates the session log:

```elixir
ExAthena.Checkpoint.rewind(session_id, :code_and_history, to_uuid: uuid)
```

See [sessions + checkpoints](sessions_and_checkpoints.md).

## Structured extraction

When you need a JSON object back — not prose — use `extract_structured/2`:

```elixir
schema = %{
  "type" => "object",
  "required" => ["bugs"],
  "properties" => %{
    "bugs" => %{
      "type" => "array",
      "items" => %{
        "type" => "object",
        "properties" => %{
          "file" => %{"type" => "string"},
          "line" => %{"type" => "integer"},
          "issue" => %{"type" => "string"}
        }
      }
    }
  }
}

{:ok, %{"bugs" => bugs}} =
  ExAthena.extract_structured(
    "Find potential null-deref bugs in this code:\n\n#{source}",
    schema: schema,
    provider: :openai_compatible,
    model: "gpt-4o-mini"
  )
```

Uses the provider's JSON mode when available; falls back to a
`~~~json`-fenced block and validates against the schema.