# Agent Commands

## Purpose

This document defines agent-scoped command dispatch inside a conversation.

It covers slash-prefixed commands and configurable shorthand command forms that are interpreted before a prompt is sent to the runner.

## Boundary Rule

Agent command dispatch belongs to `agents`.

Why:

- it decides whether inbound text is treated as agent control or normal agent input
- it is scoped to one conversation session key inside an agent
- it must remain meaningful even if the concrete runner changes

It does not belong to `runners`, because runners should receive already-decided input.

It does not belong to `control`, because these commands are used inside a user conversation rather than an operator-only surface.

## Dispatch Rule

When a message starts with `/`:

1. check whether it matches a reserved control slash command
2. if it matches, execute the control command immediately
3. if it matches an agent-reserved execution command, execute that command
4. otherwise, forward the slash command unchanged to the agent as native runner input

Control slash commands always have higher priority than native agent slash commands.

When a message starts with a configured bash shortcut such as `!`:

1. treat the remaining text as an agent-scoped bash command
2. execute it in the current agent workspace

## Current Control Slash Commands

- `/start`: show onboarding help for the current surface
- `/help`: show the available control slash commands
- `/status`: show the current route status and operator setup hints
- `/whoami`: return the current platform sender and route identity plus the
  current session id view for the active conversation
- `/transcript`: return the current full conversation session transcript
- `/stop`: send `Escape` to interrupt current processing in the current conversation session, clear clisbot's active-run state, and let queued prompts continue
- `/new`: start a new session for the current routed conversation and save the new `sessionId`
- `/nudge`: send one extra `Enter` to the current tmux session without resending the prompt body
- `/queue <message>` or `\q <message>`: create one durable queued prompt for the current session
- `/queue list`: show pending queued prompts for the current session
- `/queue clear`: clear pending queued prompts for the current session without interrupting a running prompt
- `/followup status`
- `/followup auto`
- `/followup mention-only` or `/mention`
- `/followup mention-only channel` or `/mention channel`
- `/followup mention-only all` or `/mention all`
- `/followup pause` or `/pause`
- `/followup resume` or `/resume`

Current meaning:

- `start`: show the current route onboarding or setup guidance
- `status`: show the current conversation follow-up policy and operator guidance for the route
- `auto`: continue naturally after the bot has replied in the thread, subject to policy TTL
- `mention-only`: require explicit mention for every later turn in the thread; shorthand: `/mention`
- `mention-only channel`: persist mention-only as the default for the current channel, group, or DM container; shorthand: `/mention channel`
- `mention-only all`: persist mention-only as the default for all routed conversations on the current bot; shorthand: `/mention all`
- `pause`: stop passive follow-up until explicitly resumed or re-activated; shorthand: `/pause`
- `resume`: restore the default follow-up policy for that conversation; shorthand: `/resume`

Follow-up target for continuity cleanup:

- `/whoami` and `/status` should prefer runtime-memory `sessionId` truth when a
  live run already knows it
- they should still show whether that value is:
  - persisted
  - not persisted yet
- if runtime memory captured a new `sessionId` and persistence is still behind,
  the response should not pretend the old stored value is the freshest truth

These commands should stay agent-scoped.

They are not operator-only controls.

## Current Agent Execution Commands

- `/bash <command>`: run a bash command in the current agent workspace
- configured bash shortcuts such as `!<command>`: shorthand for running a bash command in the current agent workspace

## Sensitive Command Gate

Transcript inspection and bash execution are sensitive chat-surface capabilities.

Current rule:

- transcript inspection follows route `verbose`
- `verbose: "minimal"` allows:
  - `/transcript`
  - configured slash-style transcript shortcuts such as `::transcript` or `\transcript`
- `verbose: "off"` blocks transcript inspection
- bash execution follows resolved agent auth
- `shellExecute` gating applies to:
  - `/bash <command>`
  - configured bash shortcuts such as `!<command>`

When the route does not allow them, clisbot must deny the command instead of forwarding or executing it.

## Bash Execution Model

Bash execution should not take over the main agent CLI pane.

Current rule:

- keep one reusable `bash` tmux window inside the same conversation session
- use the same workspace path as the current agent
- serialize bash commands through that one window
- capture the command output

Why this model:

- it keeps the command scoped to the same conversation session and workspace
- it does not disturb the main Codex or CLI pane
- it keeps shell context available for debugging and later reuse
- it avoids creating one extra tmux window per shell command

## Native Slash Commands

If a slash command is not reserved by clisbot control dispatch, it should be forwarded to the agent unchanged.

Examples:

- `/model`
- `/help` for a future native runner, if clisbot does not reserve it
- other agent CLI slash commands

## Current Notes

- current reserved commands are intentionally small
- control slash commands are agent-scoped, not workspace-global
- follow-up can now change at conversation scope or persist to the current channel or bot defaults when the command explicitly asks for it
- `/bash` and configured bash shortcuts are agent execution commands, not operator control commands
- `/queue` uses durable session-scoped queue items under `StoredSessionEntry.queues`; pending items survive runtime restart and are also visible through `clisbot queues`
- current bash routing uses one default reusable shell surface per conversation session
- future addressing such as `!1:` or `!bash:` belongs to later command-surface expansion, not the current default
- later growth may add argument-aware commands, but the dispatch order should not change
- current follow-up policy commands map to the same runtime control API that future agent tools and skills should use
