docs: Dokumentation aktualisiert – Preparer, ask_user_choice, Plan-Modus, TaskInstruction, Message-Tag

ARCHITECTURE.md:
- Multi-Agent System: 'Review + Finalizer' → 'Preparer + Review + Finalizer'
- Neue Sektion: Vorbereiter-Agent (Preparer) mit Flow, SSE-Events, History-Logik
- Neue Sektion: Interaktive Rückfragen (ask_user_choice) mit Tool-Definition, Backend/Frontend-Flow
- Neue Sektion: Plan-Modus mit Tool-Filterung, System-Prompt-Anpassungen
- System-Prompt-Aufbau: 12 → 14+ Blöcke (Anweisungen, Rückfragen, Plan-Modus, Preparer)
- Tool-System: ask_user_choice + Plan-Modus Read-only Filter dokumentiert
- Agent-System: AllowUserChoice + TaskInstruction Felder
- Datenmodell: preparer_agent_id, plan_mode, Tag, neue StopReasons
- DB-Persistierung: Tag-Markierung für Sub-Agent-Messages

ARCHITECTURE_QUICK.md:
- Sessions/Chains/Messages Tabellen aktualisiert
- Chat-Pipeline: Preparer-Phase + ask_user_choice ergänzt
- Tool-System: 12 → 13 Tools
- System-Prompt: 12 → 14+ Blöcke
- Multi-Agent: Preparer + Tag-System

README.md:
- Features: Vorbereiter-Agent, Interaktive Rückfragen, Plan-Modus
- 12 → 13 Tools

ARCHITECTURE.md

@@ -29,8 +29,10 @@
 15. [Krea-Bildgenerierung](#krea-bildgenerierung)
 16. [Auth & Multi-User](#auth--multi-user)
 17. [Admin-Benutzerverwaltung](#admin-benutzerverwaltung)
-18. [Multi-Agent System (Review + Finalizer)](#multi-agent-system-review--finalizer)
-19. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages)
+18. [Multi-Agent System (Preparer + Review + Finalizer)](#multi-agent-system-preparer--review--finalizer)
+19. [Interaktive Rückfragen (ask_user_choice)](#interaktive-rückfragen-ask_user_choice)
+20. [Plan-Modus](#plan-modus)
+21. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages)
 20. [Workspace & File-Explorer](#workspace--file-explorer)
 21. [Avatar-System](#avatar-system)
 22. [LaTeX/Math-Rendering](#latexmath-rendering)
@@ -267,8 +269,8 @@ Message (1) ─── (*) SharedMessage
 |-------------------|-----------------------------------------------------|
 | `users`           | Benutzer (username, password_hash, persona, settings, default_path) |
 | `tokens`          | Auth-Tokens (token → user_id)                       |
-| `agents`          | AI-Agenten (model, soul, identity, memory, tools, avatar_scale, avatar_offset_x/y) |
-| `sessions`        | Chat-Sessions (workspace, context, telegram-config, avatar_scale, avatar_offset_x/y, telegram_allowed_chat_ids, review_agent_id, max_review_iterations, finalizer_agent_id) |
+| `agents`          | AI-Agenten (model, soul, identity, memory, tools, avatar_scale, avatar_offset_x/y, allow_user_choice, task_instruction) |
+| `sessions`        | Chat-Sessions (workspace, context, telegram-config, avatar_scale, avatar_offset_x/y, telegram_allowed_chat_ids, preparer_agent_id, review_agent_id, max_review_iterations, finalizer_agent_id) |
 | `chains`          | Request-Chains (model, tokens, iterations, timing)  |
 | `messages`        | Einzelne Nachrichten (text, tool_use, tool_result, web_search_result) |
 | `attachments`     | Datei-Anhänge (base64, image/document)              |
@@ -287,7 +289,8 @@ Message (1) ─── (*) SharedMessage
 - `SystemPrompt` – Der vollständige System-Prompt (gespeichert für Nachvollziehbarkeit)
 - `InputTokens`, `OutputTokens`, `CacheCreationTokens`, `CacheReadTokens` – Token-Verbrauch
 - `Iterations` – Anzahl der Tool-Loop-Durchläufe
-- `StopReason` – `end_turn`, `tool_use`, `max_iterations`, `error`, `client_disconnected`
+- `StopReason` – `end_turn`, `tool_use`, `max_iterations`, `error`, `client_disconnected`, `awaiting_user_choice`, `preparer_query`
+- `PlanMode` – Ob die Chain im Plan-Modus erstellt wurde (informativ)
 - `DurationMs` – Gesamtdauer der Chain
 
 **MessageRecord** – Eine einzelne Nachricht innerhalb einer Chain:
@@ -296,6 +299,7 @@ Message (1) ─── (*) SharedMessage
 - `Content` – Textinhalt oder JSON (bei tool_use: Input-JSON)
 - `ToolName`, `ToolCallId` – Bei Tool-Aufrufen
 - `IsMarked` – Als wichtig markierte Nachricht (wird in System-Prompt aufgenommen)
+- `Tag` – Sub-Agent-Markierung (`null` = normal, `"preparer"/"review"/"finalizer"` = Sub-Agent-Message, wird aus API-History gefiltert)
 - `DeletedOn` – Soft-Delete Zeitstempel
 
 ---
@@ -576,10 +580,22 @@ Der Agent hat Zugriff auf folgende Tools, abhängig von Konfiguration:
 | `memory_write` | Memory-Datei schreiben (überschreiben/append) |
 | `memory_list`  | Alle Memory-Dateien des Agents auflisten  |
 
+### Interaktive Rückfragen (wenn AllowUserChoice aktiviert)
+
+| Tool               | Beschreibung                                        |
+|--------------------|-----------------------------------------------------|
+| `ask_user_choice`  | Stellt dem User eine Frage mit 2-5 Auswahlmöglichkeiten |
+
+Dieses Tool wird **nicht ausgeführt**, sondern als SSE-Event an den Client weitergeleitet. Siehe [Interaktive Rückfragen](#interaktive-rückfragen-ask_user_choice).
+
 ### Web-Suche (wenn WebSearchVersion konfiguriert)
 
 Nutzt Anthropics eingebaute Web-Suche als Server-Side-Tool.
 
+### Plan-Modus: Read-only Tools
+
+Im Plan-Modus werden nur folgende Tools bereitgestellt: `read_file`, `list_files`, `glob`, `grep`, `execute`, `todo_write`, `memory_*`, `ask_user_choice`. Write-Tools (`write_file`, `edit_file`, `delete_file`) werden gefiltert.
+
 ### Tool-Choice Strategien
 
 - **`any`**: Erste Iteration erzwingt Tool-Nutzung, danach `auto`. Verhindert dass der Agent nur Text antwortet wenn Tools benötigt werden.
@@ -608,6 +624,8 @@ Ein **Agent** definiert die Persönlichkeit und Fähigkeiten der AI:
 | `UseUserInfo`     | User-Persona in System-Prompt einbinden                          |
 | `UseMemory`       | Memory-Tools aktivieren                                          |
 | `WebSearchVersion`| Web-Suche aktivieren (z.B. `web_search_20260209`)                |
+| `AllowUserChoice` | `ask_user_choice`-Tool verfügbar (Default: true)                 |
+| `TaskInstruction` | Aufgabe/Anweisung – optionaler Text, wird als `## Anweisungen`-Block in System-Prompt eingefügt |
 
 ### Model-Auflösung
 
@@ -633,16 +651,20 @@ Der `SystemPromptBuilder` erzeugt den System-Prompt modular aus konfigurierbaren
 ┌──────────────────────────────────────────┐
 │ 1. IDENTITY.md (UseIdentity)             │  → Wer ist der Agent?
 │ 2. SOUL.md (UseSoul)                     │  → Persönlichkeit, Verhalten
-│ 3. User-Persona (UseUserInfo)            │  → Infos über den User
-│ 4. Tool-Nutzung (Workspace + any)        │  → "IMMER Tools benutzen"
-│ 5. Workspace-Info                        │  → Tools + Workspace-Pfad
-│ 6. Session-Kontext                       │  → Freiformtext
-│ 7. Skills (Agent-Skills)                 │  → Skill-Prompts
-│ 8. Memory (UseMemory)                    │  → Memory-Regeln + MEMORY.md Inhalt
-│ 9. Git-Verhalten (AutoCommit)            │  → Commit-Regeln
-│10. Verhaltensregeln (Workspace + any)    │  → "IMMER Tools aufrufen"
-│11. Erinnerung (Workspace + any)          │  → Höchste Priorität: Tool-Aufrufe!
-│12. Markierte Nachrichten                 │  → Vom User als wichtig markierte Messages
+│ 3. Anweisungen (TaskInstruction)         │  → Aufgaben-/Anweisungstext (optional)
+│ 4. User-Persona (UseUserInfo)            │  → Infos über den User
+│ 5. Tool-Nutzung (Workspace + any)        │  → "IMMER Tools benutzen"
+│ 6. Workspace-Info                        │  → Tools + Workspace-Pfad
+│ 7. Rückfragen (AllowUserChoice)          │  → Hinweis zu ask_user_choice Tool
+│ 8. Session-Kontext                       │  → Freiformtext
+│ 9. Skills (Agent-Skills)                 │  → Skill-Prompts
+│10. Memory (UseMemory)                    │  → Memory-Regeln + MEMORY.md Inhalt
+│11. Git-Verhalten (AutoCommit)            │  → Commit-Regeln
+│12. Verhaltensregeln (Workspace + any)    │  → "IMMER Tools aufrufen"
+│13. Erinnerung (Workspace + any)          │  → Höchste Priorität: Tool-Aufrufe!
+│14. Markierte Nachrichten                 │  → Vom User als wichtig markierte Messages
+│    [Plan-Modus-Block]                    │  → Nur wenn planMode=true (überspringt 5,11,12,13)
+│    [Preparer-Instruktionsblock]          │  → Nur für Preparer-Agents
 └──────────────────────────────────────────┘
 ```
 
@@ -912,14 +934,21 @@ Admins können für jeden User einen **Autologin-Link** generieren – z.B. für
 
 ---
 
-## Multi-Agent System (Review + Finalizer)
+## Multi-Agent System (Preparer + Review + Finalizer)
 
-Das Multi-Agent-System ermöglicht bis zu **drei Agents** pro Session: einen **Worker**, einen optionalen **Reviewer** und einen optionalen **Finalizer**.
+Das Multi-Agent-System ermöglicht bis zu **vier Agents** pro Session: einen **Worker**, einen optionalen **Vorbereiter (Preparer)**, einen optionalen **Reviewer** und einen optionalen **Finalizer**.
 
 ### Architektur
 
 ```
-User-Message → Worker-Agent arbeitet (Tools, Iterationen) → end_turn
+User-Message
+  → Preparer-Phase (optional):
+      → Preparer-Agent bekommt: User-Message + History (inkl. eigener vorheriger Messages)
+      → Preparer arbeitet (kann Tools nutzen: read_file, execute etc.)
+      → Erledigt Vorarbeit mit seinen Fähigkeiten (z.B. JSON bauen, Daten aufbereiten)
+      → [QUESTION] → Rückfrage an User, Flow stoppt, User muss erneut eingeben
+      → Antwort ohne [QUESTION] → automatisch weiterleiten an Worker
+  → Worker-Agent arbeitet (Tools, Iterationen) → end_turn
   → Review-Phase (optional):
       → Review-Agent bekommt: Konversation als Kontext
       → Review-Agent prüft (kann Tools nutzen: read_file, execute etc.)
@@ -940,11 +969,54 @@ Auf **Session-Ebene** (nicht Agent-Ebene):
 
 | DB-Feld | SessionRecord | Beschreibung |
 |---------|---------------|-------------|
+| `preparer_agent_id` | `PreparerAgentId` | ID des Vorbereiter-Agents (optional, null = kein Preparer) |
 | `review_agent_id` | `ReviewAgentId` | ID des Review-Agents (optional, null = kein Review) |
 | `max_review_iterations` | `MaxReviewIterations` | Max. Review-Runden (Default: 3) |
 | `finalizer_agent_id` | `FinalizerAgentId` | ID des Finalizer-Agents (optional, null = kein Finalizer) |
 
-### Backend-Flow
+### Vorbereiter-Agent (Preparer)
+
+Der Preparer wird **vor** dem Worker-Agent aufgerufen. Er analysiert die User-Anfrage, kann Vorarbeit leisten (z.B. Daten aufbereiten, JSON bauen, Code analysieren) und gibt das Ergebnis an den Worker weiter. Bei unklaren Anfragen stellt er Rückfragen.
+
+#### Logik-Pattern: Default = Forward
+
+Die Logik ist **invertiert** gegenüber dem Review-Pattern: Jede Antwort wird automatisch weitergeleitet, **außer** sie enthält explizit `[QUESTION]`. Das ist robuster als ein Pflicht-Tag wie `[FORWARD]`, weil LLMs dazu neigen, Tags zu vergessen.
+
+| Antwort | Ergebnis |
+|---------|----------|
+| Ohne `[QUESTION]` | Automatisch weitergeleitet (`ShouldForward = true`) |
+| Mit `[QUESTION]` | Rückfrage an User, Flow stoppt (`ShouldForward = false`) |
+
+#### Backend-Flow (Preparer)
+
+1. **ChatEndpoint** – Prüft ob `ctx.Preparer` vorhanden
+2. **AnthropicService.RunPreparer()** – Ruft `RunAgentChat()` auf mit `agentType = "preparer"`
+3. **Entscheidung** – `ShouldForward` prüft ob `[QUESTION]` im Text:
+   - **Forward**: Aufbereiteter Text wird als `[Vorbereitet von AgentName]:`-User-Message in DB gespeichert, History wird neu geladen, StreamChat startet
+   - **Rückfrage**: SSE `preparer_done` mit `forwarded: false`, Stream endet mit `stopReason: "preparer_query"`, User muss erneut eingeben
+
+#### Preparer-History
+
+Der Preparer bekommt seine eigene History (`BuildHistoryFromDb(sessionId, includeTag: "preparer")`), damit er seine vorherigen Rückfragen und User-Antworten sieht. Der Session-Agent bekommt die History **ohne** Preparer-Messages (Tag-Filter).
+
+#### System-Prompt
+
+Der Preparer bekommt einen speziellen Instruktionsblock an seinen System-Prompt angehängt:
+- Erklärt die Rolle als Vorbereiter
+- Definiert `[QUESTION]`-Mechanismus für Rückfragen
+- Instruiert aktive Vorarbeit mit eigenen Fähigkeiten und Tools
+- Betont: Antworten werden automatisch weitergeleitet
+
+#### SSE-Events (Preparer)
+
+| Event | Daten | Beschreibung |
+|-------|-------|-------------|
+| `preparer_start` | `{ agent: "Name" }` | Preparer-Phase beginnt |
+| `preparer_text` | `{ text: "..." }` | Preparer-Agent-Text (Token-Stream) |
+| `preparer_tool_use` | `{ tool: "name", input: "..." }` | Preparer nutzt Tool |
+| `preparer_done` | `{ forwarded: true/false }` | Preparer-Phase beendet |
+
+### Backend-Flow (Review)
 
 1. **ChatService.PrepareContext()** – Wenn `session.ReviewAgentId` gesetzt:
    - Review-Agent aus DB laden
@@ -1001,9 +1073,12 @@ public class ReviewContext
 
 ### DB-Persistierung
 
-- **Worker-Antworten**: Normale Messages (role=assistant, type=text)
+- **Worker-Antworten**: Normale Messages (role=assistant, type=text, tag=null)
+- **Preparer-Antworten**: Messages mit `tag="preparer"` (aus API-History gefiltert, nur für Frontend-Anzeige)
+- **Aufbereiteter Prompt**: Als User-Message mit Prefix `[Vorbereitet von AgentName]:`
 - **Review-Feedback**: Als User-Messages mit Prefix `[Review-Feedback von AgentName (Runde X/Y)]:`
-- **Review-Agent-Antworten**: Werden **nicht** in der Chat-History persistiert (nur als SSE-Events gestreamt), da sie Zwischenergebnisse sind
+- **Review-Agent-Antworten**: Messages mit `tag="review"` (aus API-History gefiltert)
+- **Finalizer-Antworten**: Messages mit `tag="finalizer"` (aus API-History gefiltert)
 
 ### Frontend
 
@@ -1047,10 +1122,10 @@ Der Finalizer wird **nach** dem Review (oder direkt nach dem Worker, falls kein
 
 3. **RunFinalizer()** – Baut Messages auf (gesamte Konversation + Finalisierungs-Anweisung), ruft `RunAgentChat()` auf (generische Methode, auch vom Review genutzt)
 
-4. **RunAgentChat()** – Generische Methode für Review/Finalizer:
+4. **RunAgentChat()** – Generische Methode für Preparer/Review/Finalizer:
    - Eigener API-Call an Claude mit Agent-Config
    - Tool-Loop mit SSE-Events (`{type}_text`, `{type}_tool_use`)
-   - Antwort als Message in DB persistieren
+   - Antwort als Message in DB persistieren (mit `Tag = agentType`, wird aus API-History gefiltert)
 
 #### SSE-Events
 
@@ -1063,13 +1138,103 @@ Der Finalizer wird **nach** dem Review (oder direkt nach dem Worker, falls kein
 
 #### Frontend
 
-- **Session-Page**: Dritter Agent-Picker "Finalizer-Agent" im "Weitere Einstellungen"-Bereich
-- **Chat-UI**: Finalizer-Bubbles mit eigenem Styling (`.finalizer-bubble`, grüne Farbe, 🏁-Icon)
-- **History**: `[Finalizer: AgentName]` Prefix → styled Header, `.finalizer-bubble`-Klasse
+- **Session-Page**: Vierter Agent-Picker: "Vorbereiter-Agent", "Review-Agent", "Finalizer-Agent" im "Weitere Einstellungen"-Bereich
+- **Chat-UI**: Preparer-Bubbles (`.preparer-bubble`, Info-Farbe, 🔍-Icon), Finalizer-Bubbles (`.finalizer-bubble`, grüne Farbe, 🏁-Icon)
+- **History**: `[Preparer: AgentName]` → styled Header mit `fa-filter` Icon, `[Vorbereitet von AgentName]` → styled Forwarded-Header, `[Finalizer: AgentName]` → styled Header, `[FORWARD]`/`[QUESTION]` werden ausgeblendet
 - **Dashboard**: 🏁-Badge auf Session-Cards mit Finalizer
 
 ---
 
+## Interaktive Rückfragen (ask_user_choice)
+
+Das `ask_user_choice`-Tool ermöglicht dem Agent, dem User **klickbare Auswahlmöglichkeiten** zu präsentieren, wenn es mehrere sinnvolle Wege gibt oder eine Entscheidung vom User getroffen werden muss.
+
+### Tool-Definition
+
+```json
+{
+  "name": "ask_user_choice",
+  "description": "Stellt dem User eine Frage mit Auswahlmöglichkeiten",
+  "input_schema": {
+    "properties": {
+      "question": { "type": "string" },
+      "choices": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 5 }
+    }
+  }
+}
+```
+
+### Agent-Konfiguration
+
+- **`allow_user_choice`** (AgentRecord) – Boolean, Default `true`. Steuert ob das Tool verfügbar ist.
+- Dashboard-Badge: `🔵 Rückfragen` wenn aktiv
+- System-Prompt-Hinweis: "Nutze `ask_user_choice` sparsam – nur wenn die Entscheidung vom User getroffen werden soll"
+- Bei Review/Finalizer/Cronjobs: **Immer deaktiviert** (kein User zum Fragen)
+
+### Backend-Flow
+
+1. Claude ruft `ask_user_choice` auf → Backend erkennt im `ProcessStream`
+2. Tool wird **nicht ausgeführt** – stattdessen SSE-Event `user_choice` gesendet
+3. `stopReason` wird auf `"awaiting_user_choice"` gesetzt (Guard-Clause verhindert Überschreibung durch `message_delta`)
+4. `tool_use`-Block wird in DB gespeichert, Chain wird finalisiert
+5. User wählt Option → Frontend sendet `POST /api/chat` mit `choiceToolCallId` + `choiceResult`
+6. Backend findet die Chain mit dem offenen `tool_use`, speichert `tool_result` dort
+7. Neuer `StreamChat` startet – History enthält `tool_use` + `tool_result`, Claude arbeitet weiter
+
+### Frontend-Flow
+
+- **Live**: SSE-Event `user_choice` → `addChoiceBubble()` rendert Frage + klickbare Buttons
+- **History**: `tool_use` mit `toolName === 'ask_user_choice'` → Voraus-Suche nach `tool_result`:
+  - Gefunden: `addChoiceBubbleStatic()` mit ausgewählter Option (hervorgehoben, andere ausgegraut)
+  - Nicht gefunden: Aktive Buttons (klickbar, z.B. nach Page-Refresh)
+- **Robustheit**: Guards gegen `choices` als String statt Array (`Array.isArray()` Check)
+- **CSS**: `.choice-bubble`, `.choice-btn` (Primary-Color-Outline), `.choice-selected`/`.choice-unselected`
+
+### SSE-Events
+
+| Event | Daten | Beschreibung |
+|-------|-------|-------------|
+| `user_choice` | `{ toolCallId, question, choices[] }` | Rückfrage mit Auswahloptionen |
+
+---
+
+## Plan-Modus
+
+Der Plan-Modus ist ein **Read-only-Betriebsmodus**, in dem der Agent den Code analysieren, Rückfragen stellen und Pläne erstellen kann – aber keine Dateien ändern oder Befehle ausführen darf.
+
+### Aktivierung
+
+- **Frontend**: Toggle-Button (🗺️ `fa-map`) im Chat-Input-Bereich
+- **API**: `planMode: true` im `ChatRequest`
+- **Pro Chain**: `plan_mode` Feld in der Chain (rein informativ für History-Anzeige)
+- Kein Agent-Setting – wird **pro Nachricht** vom User gesteuert
+
+### Backend-Auswirkungen
+
+| Aspekt | Normal | Plan-Modus |
+|--------|--------|-----------|
+| **Tools** | Alle (read_file, write_file, edit_file, delete_file, execute, ...) | Nur read-only: `read_file`, `list_files`, `glob`, `grep`, `execute`, `todo_write`, `memory_*`, `ask_user_choice` |
+| **System-Prompt** | Normal | + Plan-Modus-Block: "Du darfst NUR lesen und analysieren, KEINE Änderungen vornehmen" |
+| **toolChoice** | `"any"` (wenn Agent so konfiguriert) | Immer `"auto"` (Claude darf frei antworten) |
+| **Chain-Speicherung** | `plan_mode = 0` | `plan_mode = 1` |
+
+### System-Prompt-Anpassungen im Plan-Modus
+
+Folgende Blöcke werden **übersprungen**: KRITISCH (Tool-Nutzung erzwingen), Verhalten ("handle sofort"), Erinnerung ("MUSS Tool aufrufen"), Git-Commits. Der Tools-Block listet nur Read-only-Tools auf. Skills werden als "nur zur Kenntnis, nicht ausführbar" markiert.
+
+### Frontend
+
+- **Toggle**: `#planModeBtn` – wechselt `_planModeActive`, ändert Button-Styling + Placeholder-Text
+- **Chain-Meta**: Badge `📋 Plan-Modus` bei Chains die im Plan-Modus erstellt wurden
+- **System-Prompt-Modal**: Zeigt den angepassten System-Prompt wenn Plan-Modus aktiv
+- **Session-Wechsel**: Plan-Modus wird zurückgesetzt
+
+### Choice-Response im Plan-Modus
+
+Wenn im Plan-Modus eine `ask_user_choice`-Rückfrage kommt und der User antwortet, erbt die Choice-Response den `planMode` des vorherigen Chains.
+
+---
+
 ## Web-Search
 
 Anthropic Claude unterstützt Web-Suche als Server-Tool. Das System integriert Web-Search mit Source-Tracking und Rendering.

ARCHITECTURE_QUICK.md

@@ -55,9 +55,9 @@ User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* At
 | `users` | Login, Persona, Settings (JSON), DefaultPath |
 | `tokens` | Auth-Tokens → User |
 | `agents` | AI-Agenten (Model, Tools, Config, AvatarScale, AvatarOffsetX/Y) |
-| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) |
-| `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations) |
-| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result) |
+| `sessions` | Chat-Sessions (Workspace, Context, Telegram, AvatarScale, AvatarOffsetX/Y, AllowedChatIds, PreparerAgentId, ReviewAgentId, MaxReviewIterations, FinalizerAgentId) |
+| `chains` | Ein Request-Response-Zyklus (Tokens, Timing, Iterations, PlanMode) |
+| `messages` | Einzelne Nachrichten (text / tool_use / tool_result / error / web_search_result), Tag für Sub-Agent-Markierung |
 | `attachments` | Base64-Anhänge (Bilder, Dokumente) |
 | `archives` | Archivierte Chain-Gruppen |
 | `cronjobs` | Geplante Tasks (Cron-Expression + Prompt) |
@@ -118,12 +118,17 @@ User 1──* Agent 1──* Session 1──* Chain 1──* Message 1──* At
 User-Input → POST /api/chat (SSE)
   → ChatService.BuildContext()
     → History aus DB laden (letzte N Chains)
-    → SystemPromptBuilder: 12 Blöcke zusammensetzen
-    → Tool-Definitionen vom ToolService holen
+    → SystemPromptBuilder: 14 Blöcke zusammensetzen (+ Plan-Modus/Preparer-Blöcke)
+    → Tool-Definitionen vom ToolService holen (im Plan-Modus: nur Read-only)
+  → Preparer-Phase (optional, wenn PreparerAgentId gesetzt):
+    → RunPreparer() → RunAgentChat(agentType: "preparer")
+    → Antwort ohne [QUESTION] → automatisch weiterleiten (Default = Forward)
+    → [QUESTION] → Rückfrage an User, Flow stoppt
   → AnthropicService.StreamChat()
     → Claude API Call (SSE)
     → Token-für-Token an Client streamen
     → Bei tool_use → ToolService.Execute() → Ergebnis zurück → neuer API Call
+    → Bei ask_user_choice → SSE user_choice Event → Flow stoppt (awaiting_user_choice)
     → Loop bis end_turn oder max_iterations (100)
     → Bei end_turn + ReviewAgent → Review-Phase:
       → Review-Agent prüft (eigene Tools, max 25 Iterationen)
@@ -143,7 +148,7 @@ User-Input → POST /api/chat (SSE)
 
 ---
 
-## Tool-System (12 Tools)
+## Tool-System (13 Tools)
 
 | Tool | Funktion |
 |------|----------|
@@ -159,6 +164,7 @@ User-Input → POST /api/chat (SSE)
 | `memory_read` | Memory-Datei lesen |
 | `memory_write` | Memory-Datei schreiben/appenden |
 | `memory_list` | Memory-Dateien auflisten |
+| `ask_user_choice` | Interaktive Rückfrage mit 2-5 Auswahlmöglichkeiten (wenn AllowUserChoice aktiv) |
 
 **Sicherheit:** Alle Pfade werden auf das Workspace-Verzeichnis beschränkt (`..` wird blockiert). Tools sind pro Agent konfigurierbar (Feld `tools` als komma-separierte Liste).
 
@@ -166,20 +172,24 @@ User-Input → POST /api/chat (SSE)
 
 ---
 
-## System-Prompt (12 Blöcke, in Reihenfolge)
+## System-Prompt (14+ Blöcke, in Reihenfolge)
 
 1. **Identity** – `IDENTITY.md` des Agents
 2. **Soul** – `SOUL.md` des Agents
-3. **User** – `USER.md` (globale User-Infos) + Persona
-4. **Rules** – Verhaltensregeln (Tool-Nutzung, Workspace)
-5. **Context** – Session-Kontext (custom system prompt)
-6. **Marked Messages** – Als wichtig markierte Nachrichten
-7. **Memory** – Aktueller MEMORY.md-Inhalt
-8. **Skills** – Zugeordnete Skill-Prompts
-9. **Todos** – Aktuelle Todo-Liste
-10. **Tools** – Tool-Beschreibungen und -Regeln
-11. **Workspace** – Pfad-Info, Dateibaum des Workspace
-12. **Date** – Aktuelles Datum/Uhrzeit
+3. **Anweisungen** – `TaskInstruction` des Agents (optional, wenn gesetzt)
+4. **User** – `USER.md` (globale User-Infos) + Persona
+5. **Rules** – Verhaltensregeln (Tool-Nutzung, Workspace)
+6. **Workspace** – Pfad-Info, Tool-Liste
+7. **Rückfragen** – Hinweis zu `ask_user_choice` (wenn AllowUserChoice aktiv)
+8. **Context** – Session-Kontext (custom system prompt)
+9. **Skills** – Zugeordnete Skill-Prompts
+10. **Memory** – Aktueller MEMORY.md-Inhalt + Regeln
+11. **Git** – Commit-Verhalten (wenn AutoCommit konfiguriert)
+12. **Verhaltensregeln** – "IMMER Tools aufrufen" (wenn Workspace + any)
+13. **Erinnerung** – Höchste Priorität: Tool-Aufrufe! (wenn Workspace + any)
+14. **Markierte Nachrichten** – Vom User als wichtig markiert
+- **[Plan-Modus]** – Überspringt 5, 11, 12, 13; Read-only Tools; "Nur analysieren"
+- **[Preparer-Block]** – Instruktionen für Vorbereiter-Agents
 
 ---
 
@@ -241,22 +251,25 @@ Läuft als `systemd`-Service, Kestrel auf konfigurierbarem Port (Default 19000),
 
 ---
 
-## Multi-Agent System (Review + Finalizer)
+## Multi-Agent System (Preparer + Review + Finalizer)
 
-Eine Session kann optional einen **Review-Agent** (`review_agent_id`, `max_review_iterations`) und/oder einen **Finalizer-Agent** (`finalizer_agent_id`) haben.
+Eine Session kann bis zu **vier Agents** haben: Worker (Pflicht), Preparer (optional, `preparer_agent_id`), Review (optional, `review_agent_id`, `max_review_iterations`), Finalizer (optional, `finalizer_agent_id`).
 
-**Flow:** Worker-Agent arbeitet → `end_turn` → Review-Agent prüft → `[APPROVED]` / Feedback-Loop → Finalizer-Agent arbeitet (einmalig, kein Loop) → Fertig.
+**Flow:** Preparer analysiert User-Anfrage (→ Vorarbeit leisten oder `[QUESTION]` Rückfrage) → Worker-Agent arbeitet → Review-Agent prüft (`[APPROVED]` / Feedback-Loop) → Finalizer-Agent arbeitet (einmalig) → Fertig.
 
-**Backend:** `ChatService` baut `ReviewContext` + `FinalizerContext`. `RunReview()` orchestriert Review-Runden. `RunFinalizer()` führt Finalizer aus. Beide nutzen die generische `RunAgentChat()` Methode (eigener Claude-API-Call mit Tool-Loop).
+**Preparer:** Default = Forward (jede Antwort wird automatisch weitergeleitet, `[QUESTION]` stoppt). Bekommt eigene History mit `includeTag: "preparer"`. Aufbereiteter Prompt wird als `[Vorbereitet von AgentName]:` User-Message gespeichert.
+
+**Backend:** `ChatService` baut `PreparerContext` + `ReviewContext` + `FinalizerContext`. `RunPreparer()` im ChatEndpoint (vor StreamChat). `RunReview()` + `RunFinalizer()` in AnthropicService. Alle nutzen `RunAgentChat()` (mit `Tag`-Markierung, Sub-Agent-Messages aus API-History gefiltert).
 
 **SSE-Events:**
+- Preparer: `preparer_start`, `preparer_text`, `preparer_tool_use`, `preparer_done`
 - Review: `review_start`, `review_text`, `review_tool_use`, `review_feedback`, `review_approved`
 - Finalizer: `finalizer_start`, `finalizer_text`, `finalizer_tool_use`, `finalizer_done`
 
 **Frontend-Rendering:**
-- Streaming: `chat.js` rendert Review-/Finalizer-Events als eigene Bubbles (`.review-bubble` / `.finalizer-bubble`)
-- History: `renderMarkdown` parst `[Review: AgentName]`, `[Finalizer: AgentName]`, `[Review-Feedback ...]`, filtert `[APPROVED]`
-- `history.js` + `shared-page.js`: Review-/Finalizer-Nachrichten mit eigenen Bubble-Klassen, kein Merging
+- Streaming: `chat.js` rendert Preparer-/Review-/Finalizer-Events als eigene Bubbles
+- History: `renderMarkdown` parst `[Preparer: AgentName]`, `[Vorbereitet von AgentName]`, `[Review: AgentName]`, `[Finalizer: AgentName]`, filtert `[APPROVED]`, `[FORWARD]`, `[QUESTION]`
+- Bubble-Klassen: `.preparer-bubble` (Info-Farbe), `.review-bubble` (sekundäre Farbe), `.finalizer-bubble` (grüne Farbe)
 
 **Web-Search Sources:**
 - `web_search_result`-Messages in DB gespeichert (Sources als JSON-Array, leere werden übersprungen)

README.md

@@ -8,11 +8,14 @@ Self-hosted AI-Coding-Agent auf Basis der Anthropic Claude API. Stellt eine Web-
 
 ## Features
 
-- **Multi-Agent-System** – Mehrere Agenten mit eigenen Identitäten, Persönlichkeiten und Tool-Konfigurationen
-- **Multi-Agent Review** – Optionaler Review-Agent pro Session, der die Arbeit des Worker-Agents prüft und Feedback gibt
+- **Multi-Agent-System** – Bis zu 4 Agenten pro Session: Worker, Vorbereiter (Preparer), Reviewer, Finalizer
+- **Vorbereiter-Agent** – Optionaler Preparer, der User-Anfragen analysiert, Vorarbeit leistet und aufbereitete Prompts an den Worker weitergibt
+- **Multi-Agent Review** – Optionaler Review-Agent, der die Arbeit des Worker-Agents prüft und Feedback gibt
 - **Finalizer-Agent** – Optionaler Agent, der nach dem Review abschließende Arbeiten durchführt (z.B. Git-Commit, Deployment)
+- **Interaktive Rückfragen** – `ask_user_choice`-Tool: Agent stellt dem User klickbare Auswahlmöglichkeiten
+- **Plan-Modus** – Read-only-Modus zum Analysieren und Planen ohne Änderungen (Toggle im Chat)
 - **Web-Search** – Integrierte Web-Suche mit Quellenangaben (URLs + Titel) in Chat und geteilten Nachrichten
-- **12 Tools** – `read_file`, `write_file`, `edit_file`, `list_files`, `delete_file`, `execute`, `glob`, `grep`, `todo_write`, `memory_read`, `memory_write`, `memory_list`
+- **13 Tools** – `read_file`, `write_file`, `edit_file`, `list_files`, `delete_file`, `execute`, `glob`, `grep`, `todo_write`, `memory_read`, `memory_write`, `memory_list`, `ask_user_choice`
 - **Streaming** – Echtzeit-Antworten via Server-Sent Events (SSE)
 - **Stop-Button** – Laufende Requests zuverlässig abbrechen (inkl. laufender Shell-Befehle)
 - **Skill-System** – Wiederverwendbare Prompt-Bausteine, zuordenbar pro Agent