feat: add controlled Telegram terminal agent

README.md

@@ -169,6 +169,12 @@ TELEGRAM_AI_HISTORY_MESSAGES=8
 TELEGRAM_AI_MAX_INPUT_CHARS=2000
 TELEGRAM_AI_MAX_TOKENS=2048
 TELEGRAM_AI_TIMEOUT_MS=300000
+TELEGRAM_AGENT_ENABLED=true
+TELEGRAM_AGENT_MAX_STEPS=4
+TELEGRAM_AGENT_CONFIRM_TTL_SECONDS=300
+TELEGRAM_AGENT_PROACTIVE_ENABLED=true
+TELEGRAM_AGENT_PROACTIVE_MIN_CHANGES=3
+TELEGRAM_AGENT_PROACTIVE_COOLDOWN_MINUTES=30
 DISCORD_BOT_TOKEN=
 DISCORD_CHANNEL_ID=
 DISCORD_GUILD_ID=
@@ -367,6 +373,10 @@ Intelligence Terminal doubles as an interactive Telegram bot. Beyond sending ale
 | `/brief` | Compact text summary of the latest intelligence (direction, key metrics, top OSINT) |
 | `/ask <question>` | Ask the configured LLM about the latest intelligence and conversation context |
 | `/reset` | Clear the in-memory AI conversation history |
+| `/tools` | List the allowlisted terminal tools and whether confirmation is required |
+| `/trace` | Show tools, duration, result state, and short rationale from the last request |
+| `/confirm <id>` | Confirm a pending mutating action if inline buttons are unavailable |
+| `/cancel <id>` | Cancel a pending mutating action |
 | `/portfolio` | Portfolio status (if Alpaca connected) |
 | `/alerts` | Recent alert history with tiers |
 | `/mute` / `/mute 2h` | Silence alerts for 1h (or custom duration) |
@@ -377,6 +387,14 @@ Normal text messages in the configured private chat are treated as AI questions,
 
 This requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, and a configured LLM in `.env`. The bot ignores every other chat ID and polls every 5 seconds by default. For group chats, BotFather privacy settings may prevent the bot from receiving normal text; private chat is recommended. Local reasoning models can take several minutes, so the bot refreshes Telegram's typing indicator while waiting.
 
+#### Intelligence Terminal Tool Agent
+
+When `TELEGRAM_AGENT_ENABLED=true`, the chat can perform up to `TELEGRAM_AGENT_MAX_STEPS` structured tool calls before answering. The allowlist includes system status, latest brief, sweep delta, markets, source health, evidence search, memory, predictions, scenarios, and generated ideas. The agent has no generic shell, filesystem, network, environment, or secret-access tool.
+
+Read-only tools run automatically. `trigger_sweep`, `mute_alerts`, and `unmute_alerts` return an expiring confirmation request with Telegram **Confirm** and **Cancel** buttons. Confirmation is bound to the configured chat and cannot be reused. `/trace` exposes only tool names, duration, status, and a short operational rationale; private chain-of-thought is neither requested nor stored.
+
+With `TELEGRAM_AGENT_PROACTIVE_ENABLED=true`, material sweep changes trigger a separate bounded analysis. The agent can cross-check evidence, source health, scenarios, memory, and predictions before deciding whether to notify. A cooldown limits repeat notifications, and the deterministic alert evaluator remains the fallback when the agent fails or declines a notification that still meets fixed alert rules.
+
 ### Discord Bot (Two-Way)
 
 Intelligence Terminal also supports Discord as a full-featured bot with slash commands and rich embed alerts. It mirrors the Telegram bot's capabilities with Discord-native formatting.
@@ -674,6 +692,12 @@ All settings are in `.env` with sensible defaults:
 | `TELEGRAM_AI_MAX_INPUT_CHARS` | `2000` | Maximum characters accepted from one Telegram message |
 | `TELEGRAM_AI_MAX_TOKENS` | `2048` | Maximum tokens for one Telegram AI answer |
 | `TELEGRAM_AI_TIMEOUT_MS` | `300000` | Telegram AI request timeout for local models |
+| `TELEGRAM_AGENT_ENABLED` | `true` | Enable the allowlisted multi-step terminal tool agent |
+| `TELEGRAM_AGENT_MAX_STEPS` | `4` | Maximum read-only tool decisions before a final response |
+| `TELEGRAM_AGENT_CONFIRM_TTL_SECONDS` | `300` | Lifetime of a pending mutating action confirmation |
+| `TELEGRAM_AGENT_PROACTIVE_ENABLED` | `true` | Analyze material sweep changes before proactive Telegram notification |
+| `TELEGRAM_AGENT_PROACTIVE_MIN_CHANGES` | `3` | Change-count threshold for proactive analysis; critical changes always qualify |
+| `TELEGRAM_AGENT_PROACTIVE_COOLDOWN_MINUTES` | `30` | Minimum interval between proactive agent notifications |
 | `DISCORD_BOT_TOKEN` | disabled | For Discord alerts + slash commands |
 | `DISCORD_CHANNEL_ID` | — | Discord channel for alerts |
 | `DISCORD_GUILD_ID` | — | Server ID (instant slash command registration) |