# Mana-Agent-Infrastruktur — Verbesserungen aus den Claude-Code-Learnings **Stand:** 2026-04-23 **Voraussetzung:** [`claude-code-architecture.md`](./claude-code-architecture.md) > Konkrete, priorisierte Verbesserungsvorschläge für unser Agent-Stack > (`services/mana-ai`, `services/mana-mcp`, `packages/mana-tool-registry`, > `packages/shared-ai`, Persona-Runner), abgeleitet aus den Patterns, die > Claude Code durch Reverse-Engineering exponiert hat. --- ## Inhalt 1. [Zusammenfassung](#1-zusammenfassung) 2. [Ist-Stand: Wo steht unser Stack wirklich?](#2-ist-stand-wo-steht-unser-stack-wirklich) 3. [Gap-Analyse gegen Claude Code](#3-gap-analyse-gegen-claude-code) 4. [Verbesserung 1 — Permission-Gateway `UH1`-Style](#4-verbesserung-1--permission-gateway-uh1-style) 5. [Verbesserung 2 — Reminder-Injection statt History-Pollution](#5-verbesserung-2--reminder-injection-statt-history-pollution) 6. [Verbesserung 3 — Context-Compressor `wU2`-Style](#6-verbesserung-3--context-compressor-wu2-style) 7. [Verbesserung 4 — Parallel-Execution `gW5`-Style](#7-verbesserung-4--parallel-execution-gw5-style) 8. [Verbesserung 5 — Sub-Agent-Pattern `I2A`-Style](#8-verbesserung-5--sub-agent-pattern-i2a-style) 9. [Verbesserung 6 — Haiku-Tier für Background-Tasks](#9-verbesserung-6--haiku-tier-für-background-tasks) 10. [Verbesserung 7 — Async-Steering-Bus `h2A`-Style](#10-verbesserung-7--async-steering-bus-h2a-style) 11. [Verbesserung 8 — Deprecated-Tool-Training](#11-verbesserung-8--deprecated-tool-training) 12. [Roadmap und Priorisierung](#12-roadmap-und-priorisierung) 13. [Explizit nicht übernehmen](#13-explizit-nicht-übernehmen) --- ## 1. Zusammenfassung Claude Code ist im Kern ein **minimaler Agent-Loop mit sehr viel Environment- Engineering drumherum**. Unser Mana-Stack hat den Loop (`runPlannerLoop` in [`packages/shared-ai/src/planner/loop.ts`](../../packages/shared-ai/src/planner/loop.ts)) und die Tool-Registry bereits sauber getrennt — aber fast das gesamte „drumherum" fehlt: Permission-Gating, Reminder-Injection, Context-Compression, parallele Tool-Execution, Sub-Agent-Isolation, Async-Steering. Die gute Nachricht: unsere Architektur ist *vorbereitet*. Die Registry- Trennung (`@mana/tool-registry`, `@mana/shared-ai`), die saubere `ToolContext`- Abstraktion, die LWW-Projektionen — all das sind solide Fundamente, auf denen man die Claude-Code-Patterns inkrementell nachziehen kann, ohne den Stack umzubauen. **Größter Impact-Hebel:** Reminder-Injection + Context-Compression. **Größtes Sicherheitsdefizit:** fehlendes Permission-Gate auf MCP-Ebene. **Größter Performance-Hebel:** Parallel-Tool-Execution bei Read-Tools. --- ## 2. Ist-Stand: Wo steht unser Stack wirklich? ### Die Haupt-Loop: `runPlannerLoop` Unser Äquivalent zu Claude Codes `nO`-Master-Loop lebt in [`packages/shared-ai/src/planner/loop.ts:117-210`](../../packages/shared-ai/src/planner/loop.ts). Das Muster ist isomorph zu Claude Code: ```ts while (rounds < maxRounds) { // entspricht Claude's while-loop const response = await llm.complete(...); // entspricht stop_reason-Check if (response.toolCalls.length === 0) break; // terminiert bei Text for (const call of response.toolCalls) { await onToolCall(call); // entspricht MH1-Dispatch } } ``` **Abweichungen:** - `DEFAULT_MAX_ROUNDS = 5` ([loop.ts:115](../../packages/shared-ai/src/planner/loop.ts#L115)) — Claude Code hat kein hartes Round-Limit, sondern ein Token-Limit. - Tool-Calls werden **sequenziell** abgearbeitet ([loop.ts:172-188](../../packages/shared-ai/src/planner/loop.ts#L172)) — explizit so dokumentiert: „Parallel execution is a perfectly valid optimisation for pure-read tools but we keep order here". - Kein Permission-Gate — `onToolCall` wird einfach aufgerufen. - Kein Reminder-Injection-Mechanismus — System + Prior + User, fertig. ### Mission-Runner: `mana-ai` [`services/mana-ai/src/cron/tick.ts`](../../services/mana-ai/src/cron/tick.ts) (670 Zeilen) orchestriert den Loop im Background. Besonderheiten: - **60-Sekunden-Tick statt event-driven** ([tick.ts:102-286](../../services/mana-ai/src/cron/tick.ts#L102)) — das Polling-Modell fängt DB-Changes nur mit Lag auf. - **Overlap-Guard** via Module-Level-Boolean `running` ([tick.ts:100](../../services/mana-ai/src/cron/tick.ts#L100)) — einfach aber funktioniert. - **Cross-Tick-State-Machine** für Deep Research ([tick.ts](../../services/mana-ai/src/cron/tick.ts), `handleDeepResearch`) — das einzige Feature, das „länger als ein Tick" überbrückt. - **Per-Agent-Concurrency** ([tick.ts:194-208](../../services/mana-ai/src/cron/tick.ts#L194)) — mit Budget-Gate auf Token-Ebene. Gut. - **Key-Grants** ([tick.ts, crypto/](../../services/mana-ai/src/crypto)) — RSA-OAEP-gewrappte MDKs pro Mission, TTL-clamped. Sehr solide. ### MCP-Gateway: `mana-mcp` [`services/mana-mcp/src/`](../../services/mana-mcp/src) ist **bereits implementiert**, nicht nur geplant. 379 LOC total, stateless, JWT-gated. Tool-Registrierung in [`mcp-adapter.ts:81-124`](../../services/mana-mcp/src/mcp-adapter.ts#L81): ```ts for (const spec of getRegistry()) { if (!isExposable(spec)) continue; // filter admin-scoped server.tool(spec.name, spec.description, shape, invoke); } ``` Das ist elegant — aber **`isExposable` ist die einzige Policy-Schicht** ([mcp-adapter.ts:35-37](../../services/mana-mcp/src/mcp-adapter.ts#L35)). Es gibt keine Rate-Limits, keine pro-Request-Policy, keine User-Whitelist pro Tool, keine Command-Injection-Prüfung für freie Text-Felder. ### Tool-Registry: `@mana/tool-registry` [`packages/mana-tool-registry/src/`](../../packages/mana-tool-registry/src) (rund 400 LOC). Sehr sauber: - `ToolSpec` mit Zod-Schemas ([types.ts:91-122](../../packages/mana-tool-registry/src/types.ts#L91)) - `ToolContext` mit `userId`/`spaceId`/`jwt`/`invoker`/`getMasterKey` ([types.ts:58-74](../../packages/mana-tool-registry/src/types.ts#L58)) - `registerTool` + `getRegistry` Singleton ([registry.ts](../../packages/mana-tool-registry/src/registry.ts)) - `encryptedFields` als **deklaratives** Feld — nicht handler-intern. Genial für zukünftige CI-Drift-Checks gegen die web-app `crypto/registry.ts`. **Aktuell abgedeckte Module:** `habits`, `spaces`, `todo`, `notes`, `journal`, `calendar`, `contacts`, `articles`, `missions`, `tags` ([types.ts:18-29](../../packages/mana-tool-registry/src/types.ts#L18)). Laut `mana-ai/CLAUDE.md`: 31 propose-Tools über 16 Module sind server-seitig sichtbar; 28 weitere auto-Tools leben ausschließlich in der Webapp. ### Persona-Runner Nicht implementiert. Plan in [`docs/plans/mana-mcp-and-personas.md`](../plans/mana-mcp-and-personas.md). Wichtig: wir haben dort die Chance, die Sub-Agent-Patterns aus §8 **direkt richtig** zu bauen, statt nachträglich nachzurüsten. --- ## 3. Gap-Analyse gegen Claude Code | Pattern (Claude Code) | Mana-Äquivalent | Status | Priorität | |-------------------------------------|-------------------------------------------------|----------------------------|-----------| | `nO` Master-Loop | `runPlannerLoop` | ✅ vorhanden, solide | — | | `MH1` Tool-Dispatcher | `onToolCall` + Registry-Handler | ✅ vorhanden | — | | `UH1` Permission-Gateway | nur `isExposable` Admin-Filter | ⚠️ stark lückenhaft | **hoch** | | `gW5` Parallel-Scheduler (max 10) | sequenziell | ❌ fehlt | mittel | | `wU2` 92%-Compressor | keinerlei Context-Kompression | ❌ fehlt | **hoch** | | `` Reminder-Injection | User-Prompt-Concat, kein transientes Channel | ❌ fehlt | **hoch** | | `h2A` Async-Message-Queue | 60s-Tick, kein mid-task interrupt | ❌ fehlt | niedrig | | `I2A` Sub-Agent (Fresh-Context) | Persona-Runner (extern, geplant) | 🟡 im Plan, nicht isomorph | mittel | | File-Freshness-Tracking | n/a — wir editieren keine Files | — n/a | — | | Haiku für Background-Tasks | alle Calls gehen an mana-llm primary model | ❌ fehlt | mittel | | BatchTool deprecated | wir haben weder Batch noch parallel | — n/a | — | | CLAUDE.md-Disclaimer-Pattern | Agent-Context / Memory ohne Disclaimer | 🟡 improvement-worth | niedrig | --- ## 4. Verbesserung 1 — Permission-Gateway `UH1`-Style ### Problem [`services/mana-mcp/src/mcp-adapter.ts:34-37`](../../services/mana-mcp/src/mcp-adapter.ts#L34) — der einzige Gate ist Scope-Filter: ```ts function isExposable(spec: AnyToolSpec): boolean { return spec.scope === 'user-space'; } ``` Das reicht nicht: - Kein **pro-User-Opt-In** für gefährliche Tools (z. B. `habits.delete`). - Kein **Rate-Limit** pro User pro Tool (MCP ist JWT-gated, aber ein entwendeter JWT kann in 10 Sekunden 1000 Calls machen). - Kein **Path-/Content-Filter** für Freitext-Argumente (Tool `notes.create` mit `content` könnte Prompt-Injection ins Frontend tragen). - `destructive`-Policy-Hint ist **dokumentiert** ([types.ts:48](../../packages/mana-tool-registry/src/types.ts#L48)) aber nicht **durchgesetzt** — die Registry weiß, welches Tool destructive ist, aber niemand liest das an der Grenze. ### Vorschlag Ein zentrales `evaluatePolicy()` in `@mana/tool-registry`: ```ts // packages/mana-tool-registry/src/policy.ts (neu) export interface PolicyDecision { allow: boolean; reason?: string; /** Optional: inject as on next turn. */ reminder?: string; } export function evaluatePolicy( spec: AnyToolSpec, ctx: ToolContext, rawInput: unknown, opts: { userSettings?: { allowDestructive: boolean; perToolRateLimit?: number }; recentInvocations?: readonly { toolName: string; at: Date }[]; }, ): PolicyDecision; ``` Aufgerufen wird sie in `mcp-adapter.ts` **vor** `spec.handler()` und — wichtig — auch in `mana-ai`s `onToolCall`-Callback. Damit ist die Policy an einer Stelle und für beide Consumer gültig. **Konkrete Regeln für M1:** - `policyHint: 'destructive'` → Default `deny`, User muss explizit in Settings opt-in (pro Tool oder pro Scope). - Rolling 60-Sekunden-Window: Cap bei 30 Calls/Tool/User/Minute auf MCP. - Für Tools mit Freitext-Argumenten (`content`, `description`, `note`): ein Zod `.refine()` das klassische Injection-Marker (`{{`, ``-Blöcke aus [`mana-ai` v0.5](../../services/mana-ai/CLAUDE.md) sind schon ein Schritt in die richtige Richtung, aber sie sind im System-Prompt und nicht transient. ### Vorschlag **`ReminderChannel`** als neuer Input-Slot für `runPlannerLoop`: ```ts // packages/shared-ai/src/planner/loop.ts export interface PlannerLoopInput { // … bestehende Felder … /** Per-round transient hints. Called after every assistant turn; * injected as a fresh system message at the end of `messages` before * the next LLM call. NOT persisted in the returned message log. */ readonly reminderChannel?: (roundIndex: number, state: LoopState) => string | null; } ``` Die Reminder-Strings werden als transiente `{ role: 'system', content: '…' }` **vor jedem LLM-Call** eingefügt und **nach** dem Call wieder entfernt — sie leben nie in `messages`, landen nicht in der Iteration-History. Genau das Pattern von Claude Codes ``-Tags. **Use-Cases heute schon sinnvoll:** - Token-Budget: „Du hast 80 % deines Mission-Budgets verbraucht. Plane Tool-Calls sparsam." - Mission-Timer: „Mission ist in 2 Minuten überfällig — priorisiere." - Zero-Knowledge-Mode: „User ist ZK — verbotene Tabellen werden nicht decrypted. Frag nicht nach." - Nach TodoWrite: aktuellen Todo-State echoen (wie in Claude Code, §7). - Stale-Data-Warning: „Letzter Sync vor 45 min — Daten könnten veraltet sein." ### Aufwand ~4h für die Loop-Änderung, ~2 Tage für die ersten drei Reminder-Producer. ### Warum wichtig Das ist der **größte qualitative Hebel** — er wirkt sich auf jede einzelne Mission-Iteration aus, nicht nur auf Edge-Cases. Genau das, was Claude Code so feedback-sensitiv macht. --- ## 6. Verbesserung 3 — Context-Compressor `wU2`-Style ### Problem Bei langlaufenden Missions (Deep Research, Multi-Round-Plans) wird die Iteration-History in `Mission.iterations[]` immer länger. Heute wird sie komplett in den `buildSystemPrompt()`-Call geschoben — irgendwann overflowed das den Context. [`services/mana-ai/src/cron/tick.ts:211-221`](../../services/mana-ai/src/cron/tick.ts#L211) ruft `planOneMission`, das via `runPlannerLoop` alle Iterations durchreicht. **Kein** Abbruch, kein Pruning, keine Summary. ### Vorschlag Einen dedizierten `compactHistory()` pro Mission-Lifecycle: ```ts // packages/shared-ai/src/planner/compact.ts (neu) export async function compactIterations( iterations: readonly MissionIteration[], llm: LlmClient, opts: { budgetTokens: number; maxInputTokens: number }, ): Promise<{ preserved: MissionIteration[]; summary: CompactSummary }>; ``` **Trigger-Heuristik** (analog zum 92 %-Trigger): - Wenn die kumulierte Token-Schätzung der `iterations[]` > `0.6 × maxInputTokens` → komprimieren. - Alle Iterations älter als die letzten 3 werden in eine einzelne **Compact-Iteration** gefasst mit dem Schema `{ goal, decisions, filesChanged, currentProgress }` (genau das, was Claude Code persistiert). - Die Compact-Iteration wird als synthetische Iteration mit `actor: { kind:'system', source:'compactor' }` in `Mission.iterations[]` geschrieben und die summierten Originale werden **archiviert** in einer neuen Tabelle `mana_ai.iteration_archive` (nicht gelöscht, nur nicht mehr Teil des Prompt-Contexts). **Kompressionsrate** aus Claude Code: ~6.8× gemeldet. Bei uns realistisch ~3-5×, weil Iterations schon strukturiert sind. ### Aufwand ~3-5 Tage inkl. Archiv-Tabelle und Migration. ### Wann sinnvoll **Jetzt** für Deep-Research-Missions (die schon heute Token-Explosion riskieren), später für normale Multi-Round-Plans. --- ## 7. Verbesserung 4 — Parallel-Execution `gW5`-Style ### Problem [`packages/shared-ai/src/planner/loop.ts:172-188`](../../packages/shared-ai/src/planner/loop.ts#L172) — Kommentar im Code: > „Parallel execution is a perfectly valid optimisation for pure-read tools > but we keep order here so the message log tells a linear story when the > user debugs a failure." Das Argument ist legitim für Debug-Ergonomie, kostet aber bei multi-Read- Plans linear Zeit. Mission mit 5 `read_*`-Tools: 5× LLM-Latency statt 1×. ### Vorschlag Claude Codes `gW5`-Regel direkt übernehmen: 1. **Parallelisieren** wenn alle `toolCalls` einer Round `policyHint: 'read'` haben. 2. **Serialisieren** sobald eine davon `write`/`destructive` ist. 3. **Harte Grenze 10 parallel** — bei mehr: in Batches à 10. ```ts // packages/shared-ai/src/planner/loop.ts (patch) const allRead = calls.every(c => getPolicyHint(c.name) === 'read'); if (allRead && calls.length > 1) { const results = await Promise.all( calls.slice(0, 10).map(call => onToolCall(call)) ); // … append to messages in source order, not completion order } else { for (const call of calls) { /* sequential */ } } ``` Wichtig: Reihenfolge in `messages` bleibt **Source-Order**, nicht Completion-Order. Das erhält die Debug-Lesbarkeit, die der bisherige Kommentar schützen wollte — wir verlieren also nichts, gewinnen aber Wanduhr-Zeit. ### Aufwand ~2h. Die Information (`policyHint`) existiert bereits in der Registry. ### Voraussetzung Verbesserung 1 (Policy-Gate) sollte vorher laufen, damit `policyHint` an der Loop-Grenze autoritativ ist. --- ## 8. Verbesserung 5 — Sub-Agent-Pattern `I2A`-Style ### Problem Der Plan sieht den Persona-Runner als **eigenes Service** auf :3070 vor ([`docs/plans/mana-mcp-and-personas.md`](../plans/mana-mcp-and-personas.md)). Das ist für Deployment-Isolation sinnvoll, aber es **ist nicht** das Claude-Code-Pattern. Claude Codes `I2A` ist *in-process*: - Fresh `messages[]` (kein Parent-History-Leak) - eigenes Token-Budget - eigene Tool-Permissions (restriktiver) - Parent kriegt **nur die finale Summary** zurück, nicht die Zwischenschritte - Rekursions-Grenze: 1 Level ### Vorschlag **Zwei-Schichten-Modell**: **(a) In-Process Sub-Loop** in `@mana/shared-ai`: ```ts // packages/shared-ai/src/planner/sub-agent.ts (neu) export async function runSubAgent(opts: { readonly parentLoop: { messages: readonly ChatMessage[]; spec: ToolSpec }; readonly task: string; readonly allowedTools: readonly string[]; // Whitelist, restriktiver als Parent readonly maxRounds?: number; // Default 3 readonly llm: LlmClient; readonly onToolCall: (call: ToolCallRequest) => Promise; }): Promise<{ summary: string; usage: TokenUsage }>; ``` Wird vom `Task`-ähnlichen Tool in der Registry aufgerufen. Rekursion wird über einen Depth-Counter im `ToolContext` verhindert (`ctx.subAgentDepth >= 1 → error`). **(b) Persona-Runner als Out-of-Process Orchestrator** für Langläufer — der bleibt, wie im Plan, ein eigener Service. Aber: er ruft intern denselben `runSubAgent`-Code, nur mit höherem Round-Budget und Persona-spezifischen System-Prompt. ### Warum zweistufig In-Process-Sub-Agents sind für **Context-Laundering** da (dirty Recherche- Kontext vom Parent fernhalten). Der Persona-Runner ist für **Langzeit- Lifecycles** (eine Persona lebt über mehrere Wochen). Beides braucht dasselbe primitive `runSubAgent`, aber andere Deployment-Modelle. ### Aufwand ~1 Woche. --- ## 9. Verbesserung 6 — Haiku-Tier für Background-Tasks ### Problem Claude Code nutzt Haiku für hochfrequente Nebencalls: - Quota-Check - Topic-Detection - Session-Summarization - Command-Injection-Detection - Auto-Compact-Fallback Bei uns geht **jeder** Call an `mana-llm` mit dem Default-Modell — das ist für Routing-Entscheidungen ("ist dieser User-Input eine Frage oder eine Mission?") overkill und teuer. ### Vorschlag `@mana/shared-ai` bekommt einen `TieredLlmClient`: ```ts // packages/shared-ai/src/planner/tiered-client.ts (neu) export function createTieredLlmClient(baseUrl: string): { primary: LlmClient; // für runPlannerLoop fast: LlmClient; // für Classification, Summarization, Guard }; ``` Konkrete Einsätze: - **`compactIterations`** (§6) → `fast` statt `primary`. Spart 80 % Kosten beim Kompressor. - **Mission-Trigger-Klassifikation** statt Regex (heute [`tick.ts:73-82`](../../services/mana-ai/src/cron/tick.ts#L73)): statt `DEEP_RESEARCH_TRIGGER` als Regex ein Haiku-Call „Ist dieses Mission- Objective Deep Research?" — robuster und überrascht nicht bei neuen Formulierungen. - **Reminder-Producer** (§5): Der Token-Budget-Reminder wird via `fast` formuliert statt hartkodiert — variiert die Phrase pro Runde (weniger Prompt-Staleness). - **Command-Injection-Check** für Freitext-Tool-Args (in §4 erwähnt) → `fast`. ### Modell-Mapping in mana-llm Wir müssen `mana-llm` einen `tier: 'primary' | 'fast'` Request-Parameter geben, der dann intern auf ein billigeres Modell routet (z. B. Ollama `llama3.1:8b` lokal für `fast`, Claude/Gemini-primary über Cloud für `primary`). ### Aufwand ~3 Tage, fast alles in `mana-llm`. --- ## 10. Verbesserung 7 — Async-Steering-Bus `h2A`-Style ### Problem Unser Mission-Runner tickt alle 60 Sekunden ([`tick.ts:102`](../../services/mana-ai/src/cron/tick.ts#L102)). Wenn der User mid-Mission etwas ändert (neues Objective, Mission pausieren, neuen Kontext hinzufügen), wird das erst im **nächsten** Tick sichtbar. Claude Codes `h2A` ermöglicht User-Interjections *während* ein Tool läuft. Das ist für uns **nur teilweise** relevant — Missions sind explizit als Background-Jobs konzipiert — aber es gibt einen konkreten Use-Case: ### Konkreter Use-Case: Companion-Chat im Frontend Die Webapp hat einen Companion-Chat (unified mana app). Der läuft interaktiv. Heute nutzt er vermutlich ([`packages/shared-ai/src/planner/loop.ts`](../../packages/shared-ai/src/planner/loop.ts)) direkt — also dieselbe sequenzielle Loop. **Vorschlag:** `runPlannerLoop` bekommt einen optionalen `AbortSignal` und einen `InterruptChannel`: ```ts export async function runPlannerLoop(opts: { // … bestehend … readonly signal?: AbortSignal; readonly interruptChannel?: { readonly take: () => ChatMessage | null; // non-blocking pull }; }): Promise; ``` Vor jedem nächsten LLM-Call: `const msg = interruptChannel?.take()` — falls vorhanden, als `user`-Message einfügen statt die Loop stumpf weiterlaufen zu lassen. ### Aufwand ~1 Tag. ### Ausdrücklich nicht tun `h2A` **nicht** für `mana-ai`-Background-Missions einbauen. Der Tick- Ansatz ist für Server-side-Missions korrekt — User-Interjections kommen dort über den normalen Sync-Flow (Mission-Update → nächster Tick sieht es). --- ## 11. Verbesserung 8 — Deprecated-Tool-Training ### Problem Wir haben aktuell 59+ Tools in der Registry/Shared-AI. Nicht alle sind gleich sinnvoll für LLMs zum Planen — manche sind redundant (`notes.create` vs. `notes.append_to_note` vs. `notes.update_note`), manche werden praktisch nie genutzt. Claude Codes **BatchTool-Deprecation** ist instruktiv: Anthropic hat das Tool rausgenommen, weil das Modell selbst gelernt hat, mehrere `tool_use`- Blocks pro Turn zu senden — das Feature war wegtrainiert. ### Vorschlag Einen monatlichen **Tool-Usage-Audit**: - Metrik `mana_ai_tool_invocations_total{tool}` aus bereits existierenden Metrics - Report aller Tools unter Top-50-Percentile-Calls → Kandidat für Deprecation - Alternative: `mcp-adapter.ts` loggt den **vom Modell geforderten aber erfolglosen** Tool-Call — daraus wird sichtbar, welche Tools das Modell erfindet, weil der Name „intuitiv" wäre (z. B. `notes.delete` wenn wir nur `notes.archive` haben). Das ist weniger eine Code-Änderung und mehr ein **Prozess**: alle 6 Wochen einen 1-Stunden-Review, Tools konsolidieren. ### Aufwand 0 für die Infra (Metrics sind da). 1h pro Audit-Zyklus. --- ## 12. Roadmap und Priorisierung ### M1 (2 Wochen) | # | Verbesserung | Aufwand | Abhängigkeit | |---|------------------------------------|---------|--------------------| | 1 | Permission-Gateway (§4) | 1 Tag | — | | 2 | Reminder-Injection Loop-API (§5) | 4 h | — | | 3 | Parallel-Execution für Reads (§7) | 2 h | §4 (policyHint) | | 4 | Async-Steering im Companion (§10) | 1 Tag | — | **M1-Outcome:** Sicherer MCP-Gateway, qualitativ bessere Mission-Planung durch Reminders, schnellere Multi-Read-Plans, Companion-Chat abbruchbar. ### M2 (3-4 Wochen) | # | Verbesserung | Aufwand | Abhängigkeit | |---|--------------------------------------|----------|---------------| | 5 | Context-Compressor `wU2` (§6) | 3-5 Tage | §9 | | 6 | Haiku-Tier in `mana-llm` (§9) | 3 Tage | — | | 7 | Reminder-Producer Library (§5) | 2 Tage | M1 #2 | **M2-Outcome:** Deep-Research-Missions skalieren, Background-Calls 80 % billiger, Reminder-Channel in Produktion. ### M3 (Persona-Runner) | # | Verbesserung | Aufwand | Abhängigkeit | |---|--------------------------------------|-----------|---------------| | 8 | In-Process `runSubAgent` (§8) | 1 Woche | M1 #1, M2 #5 | | 9 | Persona-Runner nutzt `runSubAgent` | 2 Wochen | M3 #8 | **M3-Outcome:** Sub-Agent-Pattern einheitlich, Persona-Runner kann komplexe Multi-Step-Personas orchestrieren, ohne Parent-Context zu verseuchen. ### Ongoing | # | Verbesserung | Aufwand | |---|--------------------------------------|---------------------| | 10 | Tool-Usage-Audit (§11) | 1h alle 6 Wochen | --- ## 13. Explizit nicht übernehmen Nicht jedes Claude-Code-Pattern macht für uns Sinn: - **File-Freshness-Tracking** — wir editieren keine Dateien im Agent-Kontext. Das Äquivalent wäre „Sync-Freshness-Tracking", das aber schon durch `mana_sync` LWW-Semantik adressiert ist. - **`BatchTool` einführen** — das Claude-Code-Pattern ist, `BatchTool` zu *deprecaten*, weil das Modell nativ parallele `tool_use`-Blocks sendet. Wir sollten das direkt als Endzustand adoptieren (§7), nicht über ein Batch-Zwischenstadium gehen. - **yoga.wasm / Ink** — die Mana-Webapp ist SvelteKit, kein Terminal-UI. Das UI-Layer-Muster ist für uns irrelevant. - **`--bypassPermissions`-Mode** — für ein Multi-User-Produkt mit Zero-Knowledge-Option darf es kein Opt-Out aus der Policy geben. - **Der Haiku-Quota-Ping** — unser Billing läuft über `mana-credits`, wir sehen Quota deterministisch vor dem Call, nicht probabilistisch. --- ## Related - [`claude-code-architecture.md`](./claude-code-architecture.md) — Technische Grundlage dieses Berichts - [`docs/plans/mana-mcp-and-personas.md`](../plans/mana-mcp-and-personas.md) — Ongoing-Plan für mana-mcp + persona-runner - [`docs/architecture/COMPANION_BRAIN_ARCHITECTURE.md`](../architecture/COMPANION_BRAIN_ARCHITECTURE.md) §20-22 — Agent-Design der Webapp - [`docs/reports/ai-agent-architecture-comparison.md`](./ai-agent-architecture-comparison.md) — Weiterer externer Vergleich