Turn Context Investigation & Unified Tool Design

Details

Raw Data

{
  "id": "d0217105-937b-4bd6-88b5-4029a2f32a49",
  "type": "general",
  "status": "completed",
  "title": "Turn Context Investigation & Unified Tool Design",
  "description": "Analysis of why Claude makes 6+ tool calls at turn start and proposal for unified context injection",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:'Consolas','Monaco',monospace;\">\n<h2 style=\"font-family:sans-serif;color:#fff;margin:0 0 16px 0;\">Turn Context Investigation</h2>\n\n<h3 style=\"color:#61afef;margin:20px 0 12px 0;\">Problem Observed</h3>\n<p style=\"line-height:1.6;\">From the screenshot, Claude is making <span style=\"color:#e5c07b;font-weight:bold;\">6 separate MCP tool calls</span> at turn start:</p>\n\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.8;color:#e0e0e0;\">\n<span style=\"color:#e06c75;\">1.</span> <span style=\"color:#98c379;\">konui_get_recent_kontasks</span>\n<span style=\"color:#e06c75;\">2.</span> <span style=\"color:#98c379;\">konui_get_backlog</span>\n<span style=\"color:#e06c75;\">3.</span> <span style=\"color:#98c379;\">konui_get_active_flows</span>\n<span style=\"color:#e06c75;\">4.</span> <span style=\"color:#56b6c2;\">Read /konnectvol/gv/VIBE.md</span>  <span style=\"color:#7f848e;\"># 558+ lines!</span>\n<span style=\"color:#e06c75;\">5.</span> <span style=\"color:#98c379;\">konui_get_decision_stats</span>\n<span style=\"color:#e06c75;\">6.</span> <span style=\"color:#98c379;\">konui_list_decisions</span>\n</pre>\n\n<h3 style=\"color:#61afef;margin:20px 0 12px 0;\">Root Cause</h3>\n<p style=\"line-height:1.6;\">CLAUDE.md instructs Claude to call multiple tools at turn start:</p>\n\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;font-size:0.85em;\">\n<span style=\"color:#7f848e;\">// From CLAUDE.md \"CRITICAL: Turn Start Behaviors\"</span>\n<span style=\"color:#c678dd;\">await</span> Promise.all([\n  <span style=\"color:#98c379;\">konui_get_recent_kontasks</span>({ count: 3 }),\n  <span style=\"color:#98c379;\">konui_suggest_matching_flows</span>({ prompt, limit: 3 }),\n]);\n<span style=\"color:#c678dd;\">await</span> <span style=\"color:#98c379;\">konui_get_or_create_flow</span>({ sessionId, prompt });\n</pre>\n\n<p style=\"line-height:1.6;margin-top:12px;\">But Claude interprets this <em>liberally</em> and adds more calls to \"help\" the user. The prompt \"Help me decide what to work on next\" + RECENT WORK hints triggered Claude to call backlog, flows, decisions, and read VIBE.md directly.</p>\n\n<h3 style=\"color:#61afef;margin:20px 0 12px 0;\">Impact</h3>\n<table style=\"width:100%;border-collapse:collapse;margin:12px 0;\">\n<tr style=\"background:#2d2d2d;\">\n<th style=\"text-align:left;padding:8px;border:1px solid #444;\">Metric</th>\n<th style=\"text-align:left;padding:8px;border:1px solid #444;\">Current</th>\n<th style=\"text-align:left;padding:8px;border:1px solid #444;\">Ideal</th>\n</tr>\n<tr>\n<td style=\"padding:8px;border:1px solid #444;\">Tool calls at turn start</td>\n<td style=\"padding:8px;border:1px solid #444;color:#e06c75;\">6+</td>\n<td style=\"padding:8px;border:1px solid #444;color:#98c379;\">1</td>\n</tr>\n<tr>\n<td style=\"padding:8px;border:1px solid #444;\">Tokens consumed</td>\n<td style=\"padding:8px;border:1px solid #444;color:#e06c75;\">~3,000+</td>\n<td style=\"padding:8px;border:1px solid #444;color:#98c379;\">~500</td>\n</tr>\n<tr>\n<td style=\"padding:8px;border:1px solid #444;\">Turn start latency</td>\n<td style=\"padding:8px;border:1px solid #444;color:#e06c75;\">5-10s</td>\n<td style=\"padding:8px;border:1px solid #444;color:#98c379;\">&lt;1s</td>\n</tr>\n</table>\n\n<h3 style=\"color:#61afef;margin:20px 0 12px 0;\">Proposed Solutions</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin:12px 0;border-left:3px solid #22c55e;\">\n<h4 style=\"color:#98c379;margin:0 0 8px 0;\">Option A: Unified MCP Tool (Recommended)</h4>\n<p style=\"margin:0;line-height:1.6;\">Create <code style=\"background:#3d3d3d;padding:2px 6px;border-radius:4px;\">konui_get_turn_context</code> that returns <strong>ALL</strong> context in one call:</p>\n<pre style=\"background:#1e1e1e;padding:12px;border-radius:4px;margin-top:12px;font-size:0.85em;\">\n{\n  <span style=\"color:#98c379;\">\"recentKontasks\"</span>: [...],      <span style=\"color:#7f848e;\">// Last 3 kontasks (compact)</span>\n  <span style=\"color:#98c379;\">\"activeFlow\"</span>: {...},          <span style=\"color:#7f848e;\">// Current/matched flow</span>\n  <span style=\"color:#98c379;\">\"approvedTasks\"</span>: [...],      <span style=\"color:#7f848e;\">// Pending approvals (if any)</span>\n  <span style=\"color:#98c379;\">\"backlogHints\"</span>: [...],       <span style=\"color:#7f848e;\">// Top 3 backlog items</span>\n  <span style=\"color:#98c379;\">\"sessionId\"</span>: \"ses_...\",\n  <span style=\"color:#98c379;\">\"flowId\"</span>: \"flow_...\"         <span style=\"color:#7f848e;\">// Auto-created if needed</span>\n}\n</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin:12px 0;border-left:3px solid #3b82f6;\">\n<h4 style=\"color:#61afef;margin:0 0 8px 0;\">Option B: Pre-Prompt Hook Injection</h4>\n<p style=\"margin:0;line-height:1.6;\">Inject context <em>before</em> Claude even sees the prompt:</p>\n<pre style=\"background:#1e1e1e;padding:12px;border-radius:4px;margin-top:12px;font-size:0.85em;\">\n<span style=\"color:#7f848e;\">// konui router wraps prompt with pre-computed context</span>\n<span style=\"color:#c678dd;\">const</span> context = <span style=\"color:#c678dd;\">await</span> <span style=\"color:#61afef;\">getTurnContext</span>(sessionId, prompt);\n<span style=\"color:#c678dd;\">const</span> wrappedPrompt = <span style=\"color:#98c379;\">`\n&lt;turn-context&gt;\n${</span>JSON.stringify(context)<span style=\"color:#98c379;\">}\n&lt;/turn-context&gt;\n\n${</span>userPrompt<span style=\"color:#98c379;\">}`</span>;\n</pre>\n<p style=\"margin:8px 0 0 0;color:#7f848e;font-size:0.9em;\">✓ Zero tool calls at turn start<br/>✓ Context always present<br/>✗ Adds to every prompt (even when not needed)</p>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin:12px 0;border-left:3px solid #8b5cf6;\">\n<h4 style=\"color:#c678dd;margin:0 0 8px 0;\">Option C: Hybrid (Best of Both)</h4>\n<p style=\"margin:0;line-height:1.6;\">Inject <em>lightweight</em> context in prompt, Claude calls for more if needed:</p>\n<pre style=\"background:#1e1e1e;padding:12px;border-radius:4px;margin-top:12px;font-size:0.85em;\">\n<span style=\"color:#7f848e;\">// Injected in prompt (minimal)</span>\n&lt;turn-context&gt;\n  session: ses_abc123\n  flow: flow_xyz (\"Fix auth bug\")\n  recent: [\"Schema refactor\", \"Type fixes\"]\n  approvals: 0 pending\n&lt;/turn-context&gt;\n\n<span style=\"color:#7f848e;\">// If Claude needs more, ONE tool call:</span>\n<span style=\"color:#c678dd;\">await</span> <span style=\"color:#98c379;\">konui_get_turn_context</span>({ full: true });\n</pre>\n</div>\n\n<h3 style=\"color:#61afef;margin:20px 0 12px 0;\">Recommended Approach</h3>\n<p style=\"line-height:1.6;\"><strong>Option C (Hybrid)</strong> is the most efficient:</p>\n<ol style=\"margin:12px 0;padding-left:24px;line-height:1.8;\">\n<li>Pre-inject <em>essential</em> context (session, flow, 3-line summary)</li>\n<li>Create <code style=\"background:#3d3d3d;padding:2px 6px;border-radius:4px;\">konui_get_turn_context</code> for full details when needed</li>\n<li>Update CLAUDE.md to <em>remove</em> turn-start tool call instructions</li>\n<li>Claude naturally uses pre-injected context for most tasks</li>\n</ol>\n\n<h3 style=\"color:#61afef;margin:20px 0 12px 0;\">Implementation Steps</h3>\n<ol style=\"margin:12px 0;padding-left:24px;line-height:1.8;\">\n<li><strong>Add <code>getTurnContext()</code></strong> in <code>konui/src/session-context.ts</code></li>\n<li><strong>Modify prompt wrapper</strong> in <code>konui/src/router.ts</code> to inject minimal context</li>\n<li><strong>Create <code>konui_get_turn_context</code></strong> MCP tool for full details</li>\n<li><strong>Update CLAUDE.md</strong> to remove turn-start tool requirements</li>\n<li><strong>Test</strong> that Claude no longer makes 6+ calls at start</li>\n</ol>\n\n<p style=\"margin-top:20px;padding:12px;background:rgba(34,197,94,0.1);border-radius:6px;border:1px solid rgba(34,197,94,0.3);\">\n<strong style=\"color:#22c55e;\">Estimated Impact:</strong> 6+ tool calls → 0-1 calls at turn start. ~80% token reduction for context retrieval.\n</p>\n\n</div>",
    "requestedAt": "2026-01-09T12:55:00.000Z",
    "requestId": "a2ccc84c-e8eb-419c-bfe0-15675c3de05a",
    "choices": [
      {
        "label": "Implement Option C",
        "value": "Implement the hybrid approach: add pre-prompt context injection with minimal context, create konui_get_turn_context MCP tool for full details, and update CLAUDE.md",
        "primary": true
      },
      {
        "label": "Implement Option A",
        "value": "Implement the unified MCP tool konui_get_turn_context that returns all context in one call, then update CLAUDE.md to use only this tool"
      },
      {
        "label": "Explore further",
        "value": "I want to explore this more - show me the current prompt wrapper code and how context injection would work"
      },
      {
        "label": "Different approach",
        "value": "I have a different idea for solving the turn context problem"
      }
    ],
    "turnTiming": {
      "totalMs": 141643,
      "ttfeMs": 242,
      "thinkingMs": 141396,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 100,
      "toolsPct": 0,
      "ttfePct": 0
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T12:56:40.099Z",
  "updatedAt": "2026-01-09T12:56:47.371Z",
  "requestId": "a2ccc84c-e8eb-419c-bfe0-15675c3de05a",
  "scope": "vibetools",
  "tags": [
    "kontasks",
    "flows",
    "context",
    "performance"
  ],
  "sessionId": "ses_d3abe491-395",
  "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
  "flowLinks": [
    {
      "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
      "edgeType": "evidence",
      "createdAt": "2026-01-09T12:56:40.099Z"
    }
  ],
  "targetUser": "claude"
}