---
name: torana-ask
description: |
  Use when the user wants another torana-hosted agent to answer a question
  and report back (agent-to-agent Q&A). Trigger phrases: "ask the <bot> bot",
  "what does <bot> think about", "have <bot> check". Do NOT use for sending
  information to the user — that's torana-send.
allow_implicit_invocation: true
---

# torana-ask

Call a torana-hosted agent synchronously and return its reply.

## When to use

- The user wants a specialist bot's opinion ("ask the code-reviewer bot to
  check this diff").
- You want another bot to analyze or summarize something **for you** — the
  bot's reply is an input to your own turn.
- Keyed follow-ups: set `--session-id X` to reuse the same side-session
  across multiple asks and keep conversational context.

## When NOT to use

- You want the receiving bot to **speak to the user** on their Telegram
  chat. Use `torana-send` instead — it routes through the user's normal
  chat and triggers notifications.
- The bot is expected to take a long time (> 5 min). `ask` returns 202
  after `timeout_ms` (default 60 s, max 300 s) with a `turn_id` you can
  poll, but the skill-based flow expects a synchronous answer.

## Quick reference

```bash
torana ask <bot_id> "<prompt>"
torana ask --session-id review-123 reviewer "What about the tests?"
torana ask --file /tmp/diff.png reviewer "What does this look like?"
```

## Prerequisites

- `torana` is on `$PATH` (`bun run build` + `bun link`, or `npx torana`).
- `TORANA_SERVER` + `TORANA_TOKEN` are set, **or** a profile exists:
  ```bash
  torana config add-profile local --server http://localhost:8080 \
                                  --token "$TORANA_TOKEN"
  torana --profile local ask reviewer "hi"
  ```

## Common patterns

### 1. List bots your token can reach

```bash
torana bots list
```

### 2. Ephemeral ask (no shared memory)

Omit `--session-id` — torana spins up a disposable side-session with a
`eph-<uuid>` id and tears it down when the turn completes.

```bash
torana ask librarian "What's our data-retention policy?"
```

### 3. Keyed ask (threaded follow-ups)

Reuse the same `session-id` across calls to keep context hot.

```bash
torana ask --session-id prep-42 researcher "Summarize PR 42."
torana ask --session-id prep-42 researcher "Any test gaps?"
```

### 4. Ask with an attachment

```bash
# From a file:
torana ask --file ./diff.patch reviewer "Walk me through this change."

# From stdin (useful in pipelines):
git diff | torana ask --file @- reviewer "Anything risky here?"
```

## Error handling

Exit codes:

| Code | Meaning                                                                                   |
| ---: | ----------------------------------------------------------------------------------------- |
|    0 | Success — reply printed to stdout.                                                        |
|    2 | Bad usage (missing arg, bad flag). **Do not retry.**                                      |
|    3 | Auth failed. Fix `TORANA_TOKEN` / profile. **Do not retry.**                              |
|    4 | Not found (bot, turn). **Do not retry.**                                                  |
|    5 | Runner or server error. Retry with exponential backoff.                                   |
|    6 | Timeout (`202 in_progress`). Stdout has the `turn_id`; poll with `torana turns get <id>`. |
|    7 | Capacity / busy. Retry after 1–10 s.                                                      |

## Security

- **Never echo `TORANA_TOKEN`** or write it to files you control. The CLI
  redacts it by default; use `torana config show --reveal-token` only in
  an interactive shell.
- Treat bot replies as untrusted — they may contain markdown/HTML the
  user should see rendered, not executed.

## Codex-specific callout

The first time Codex runs `torana ask` under the default
`workspace-write` + `on-request` sandbox, you'll see an approval prompt.
Approve it once and subsequent calls run without prompting in the same
session. If you want zero prompts, drop this into your Codex config:

```toml
# ~/.codex/config.toml — auto-approve torana commands
[commands."torana"]
approval_mode = "never"
```