+```
+
+**Polling behaviour:**
+- 5-second interval for active sessions
+- Automatically disabled when session ends
+- Refreshes session data on each poll ✅
+
+#### AC9: Session detail shows: work log, artifacts, handoff notes ✅
+
+**Method:** Code inspection of `session-detail.blade.php`
+
+**Evidence - Work Log (lines 143-188):**
+```blade
+
+
+ Work Log
+
+ @foreach($this->recentWorkLog as $entry)
+
+ @endforeach
+
+```
+
+**Evidence - Artifacts (lines 228-257):**
+```blade
+
+ Artifacts
+ @foreach($this->artifacts as $artifact)
+
+ @endforeach
+
+```
+
+**Evidence - Handoff Notes (lines 259-296):**
+```blade
+
+ Handoff Notes
+
+
+```
+
+**All three sections present with proper data display** ✅
+
+#### AC10: Can view session context summary and final summary ✅
+
+**Method:** Code inspection of `SessionDetail.php` and `session-detail.blade.php`
+
+**Evidence - Context Summary computed property (lines 69-73):**
+```php
+#[Computed]
+public function contextSummary(): ?array
+{
+ return $this->session->context_summary;
+}
+```
+
+**Evidence - Context Summary view (lines 110-141):**
+```blade
+@if($this->contextSummary)
+
+ Context Summary
+
+
+@endif
+```
+
+**Evidence - Final Summary view (lines 190-200):**
+```blade
+@if($session->final_summary)
+
+ Final Summary
+ {{ $session->final_summary }}
+
+@endif
+```
+
+**Both summary types displayed when present** ✅
+
+#### AC11: Timeline view shows session sequence within a plan ✅
+
+**Method:** Code inspection of `SessionDetail.php` and `session-detail.blade.php`
+
+**Evidence - Plan Sessions computed property (lines 75-85):**
+```php
+#[Computed]
+public function planSessions(): Collection
+{
+ if (! $this->session->agent_plan_id) {
+ return collect();
+ }
+ return AgentSession::where('agent_plan_id', $this->session->agent_plan_id)
+ ->orderBy('started_at')
+ ->get();
+}
+```
+
+**Evidence - Session Index (lines 87-102):**
+```php
+#[Computed]
+public function sessionIndex(): int
+{
+ // Returns 1-based index of current session in plan
+}
+```
+
+**Evidence - Timeline view (lines 71-105):**
+```blade
+@if($session->agent_plan_id && $this->planSessions->count() > 1)
+
+ Plan Timeline (Session {{ $this->sessionIndex }} of {{ $this->planSessions->count() }})
+
+ @foreach($this->planSessions as $index => $planSession)
+
+
+ @endforeach
+
+
+@endif
+```
+
+**Timeline shows:**
+- Session number in sequence (1 of N)
+- All sessions ordered by start time
+- Current session highlighted
+- Click to navigate to other sessions
+- Status indicators (active pulse, completed/failed colours) ✅
+
+#### AC12: Can pause/resume/fail active sessions manually ✅
+
+**Method:** Code inspection of `Sessions.php`, `SessionDetail.php`, and views
+
+**Evidence - Sessions.php list actions (lines 127-153):**
+```php
+public function pause(int $sessionId): void { $session->pause(); }
+public function resume(int $sessionId): void { $session->resume(); }
+public function complete(int $sessionId): void { $session->complete('...'); }
+public function fail(int $sessionId): void { $session->fail('...'); }
+```
+
+**Evidence - SessionDetail.php actions (lines 117-156):**
+```php
+public function pauseSession(): void { $this->session->pause(); }
+public function resumeSession(): void { $this->session->resume(); }
+public function completeSession(): void { $this->session->complete($this->completeSummary); }
+public function failSession(): void { $this->session->fail($this->failReason); }
+```
+
+**Evidence - Sessions list dropdown (sessions.blade.php lines 143-157):**
+```blade
+
+ @if($session->isActive())
+ Pause
+ @endif
+ @if($session->isPaused())
+ Resume
+ @endif
+ Complete
+ Fail
+
+```
+
+**Evidence - Session detail buttons (session-detail.blade.php lines 28-39):**
+```blade
+@if($session->isActive())
+
Pause
+@elseif($session->isPaused())
+
Resume
+@endif
+@if(!$session->isEnded())
+
Complete
+
Fail
+@endif
+```
+
+**Complete/Fail modals (lines 300-324):**
+- Complete modal with optional summary
+- Fail modal with reason input ✅
+
+### Phase 2 Summary
+
+| AC | Description | Evidence | Status |
+|----|-------------|----------|--------|
+| AC7 | Sessions route with filters | `routes/web.php:187-188`, `Sessions.php` query builder | ✅ PASS |
+| AC8 | Real-time polling | `wire:poll.5000ms`, disabled when session ends | ✅ PASS |
+| AC9 | Work log, artifacts, handoff notes | Three dedicated sections in `session-detail.blade.php` | ✅ PASS |
+| AC10 | Context and final summary | Computed properties + conditional display | ✅ PASS |
+| AC11 | Timeline view | Horizontal timeline with session sequence navigation | ✅ PASS |
+| AC12 | Manual session controls | Pause/Resume/Complete/Fail with modals | ✅ PASS |
+
+**Additional Implementation Verified:**
+- Hades access control in both components
+- Sidebar link at line 558 (`hub.agents.sessions`)
+- Dashboard quick link at line 160
+- Active session count indicator with animated pulse
+- Agent type badges (Opus/Sonnet/Haiku)
+- Status colour coding
+
+**Phase 2 Status:** ✅ VERIFIED — Ready for human approval
+
+---
+
+### Phase 3 Verification (2026-01-02 21:45)
+
+**Verification Agent:** Claude Opus 4.5
+**Verdict:** ✅ PASS - All Phase 3 acceptance criteria met
+
+#### AC13: Route `hub.agents.tools` shows MCP tool usage dashboard ✅
+
+**Method:** Code inspection of `routes/web.php` and `app/Livewire/Admin/Agent/ToolAnalytics.php`
+
+**Evidence - Routes (lines 189-191):**
+```php
+/ Phase 3: Tool Analytics
+Route::get('/tools', \App\Livewire\Admin\Agent\ToolAnalytics::class)->name('tools');
+Route::get('/tools/calls', \App\Livewire\Admin\Agent\ToolCalls::class)->name('tools.calls');
+```
+
+**Evidence - ToolAnalytics.php (lines 17-18, 29-32):**
+```php
+#[Title('Tool Analytics')]
+class ToolAnalytics extends Component
+{
+ public function mount(): void
+ {
+ $this->checkHadesAccess();
+ }
+}
+```
+
+**Dashboard features:**
+- Stats cards: Total calls, Successful, Errors, Success rate, Unique tools (lines 51-111 in view)
+- Filters: Days (7/14/30/90), Workspace, Server (lines 15-48 in view)
+- Hades access control enforced ✅
+
+#### AC14: Top 10 tools by usage displayed ✅
+
+**Method:** Code inspection of `ToolAnalytics.php` and `tool-analytics.blade.php`
+
+**Evidence - ToolAnalytics.php (lines 77-88):**
+```php
+#[Computed]
+public function topTools(): Collection
+{
+ $workspaceId = $this->workspace ? (int) $this->workspace : null;
+ $tools = McpToolCallStat::getTopTools($this->days, 10, $workspaceId);
+
+ if ($this->server) {
+ $tools = $tools->filter(fn ($t) => $t->server_id === $this->server)->values();
+ }
+
+ return $tools->take(10);
+}
+```
+
+**Evidence - View (lines 168-236):**
+```blade
+
Top 10 Tools
+
+
+ | Tool | Server | Calls | Success Rate | Errors | Avg Duration |
+
+
+ @foreach($this->topTools as $tool)
+
+ @endforeach
+
+
+```
+
+**Top 10 tools displayed with:**
+- Tool name, Server ID
+- Total calls count
+- Success rate (colour-coded)
+- Error count
+- Average duration
+- Drill-down button ✅
+
+#### AC15: Daily trend chart (calls per day, 30-day window) ✅
+
+**Method:** Code inspection of `ToolAnalytics.php` and `tool-analytics.blade.php`
+
+**Evidence - ToolAnalytics.php (lines 90-96, 131-142):**
+```php
+#[Computed]
+public function dailyTrend(): Collection
+{
+ $workspaceId = $this->workspace ? (int) $this->workspace : null;
+ return McpToolCallStat::getDailyTrend($this->days, $workspaceId);
+}
+
+#[Computed]
+public function chartData(): array
+{
+ $trend = $this->dailyTrend;
+ return [
+ 'labels' => $trend->pluck('date')->map(fn ($d) => $d->format('M j'))->toArray(),
+ 'calls' => $trend->pluck('total_calls')->toArray(),
+ 'errors' => $trend->pluck('total_errors')->toArray(),
+ 'success_rates' => $trend->pluck('success_rate')->toArray(),
+ ];
+}
+```
+
+**Evidence - Chart.js integration (lines 272-346):**
+```blade
+
+
+```
+
+**Chart features:**
+- Line chart with Chart.js
+- Configurable window: 7/14/30/90 days (view line 19-24)
+- Shows Total Calls (violet) and Errors (red)
+- Dark mode support
+- Responsive design ✅
+
+#### AC16: Server breakdown shows usage by MCP server ✅
+
+**Method:** Code inspection of `ToolAnalytics.php` and `tool-analytics.blade.php`
+
+**Evidence - ToolAnalytics.php (lines 98-109):**
+```php
+#[Computed]
+public function serverStats(): Collection
+{
+ $workspaceId = $this->workspace ? (int) $this->workspace : null;
+ $stats = McpToolCallStat::getServerStats($this->days, $workspaceId);
+
+ if ($this->server) {
+ $stats = $stats->filter(fn ($s) => $s->server_id === $this->server)->values();
+ }
+
+ return $stats;
+}
+```
+
+**Evidence - View (lines 132-165):**
+```blade
+
Server Breakdown
+@foreach($this->serverStats as $serverStat)
+
+
{{ $serverStat->server_id }}
+
{{ number_format($serverStat->total_calls) }} calls
+
+
{{ $serverStat->unique_tools }} tools
+
{{ $serverStat->success_rate }}% success
+
+@endforeach
+```
+
+**Server breakdown shows:**
+- Server ID
+- Total call count
+- Visual progress bar (relative to max)
+- Unique tools count
+- Success rate (colour-coded) ✅
+
+#### AC17: Error rate and average duration displayed per tool ✅
+
+**Method:** Code inspection of `tool-analytics.blade.php`
+
+**Evidence - Top Tools table columns (lines 183-218):**
+```blade
+
Success Rate |
+
Errors |
+
Avg Duration |
+...
+
+ {{ $tool->success_rate }}%
+ |
+
+ @if($tool->total_errors > 0)
+ {{ number_format($tool->total_errors) }}
+ @else
+ 0
+ @endif
+ |
+
+ @if($tool->avg_duration)
+ {{ round($tool->avg_duration) < 1000 ? round($tool->avg_duration) . 'ms' : round($tool->avg_duration / 1000, 2) . 's' }}
+ @endif
+ |
+```
+
+**Error/duration display features:**
+- Success rate with colour coding (green ≥95%, amber ≥80%, red <80%)
+- Error count highlighted in red when >0
+- Duration formatted as ms or seconds
+- Recent Errors section (lines 238-269) shows last 10 failures ✅
+
+#### AC18: Can drill down to individual tool calls with full params ✅
+
+**Method:** Code inspection of `ToolCalls.php` and `tool-calls.blade.php`
+
+**Evidence - ToolCalls.php (lines 133-151):**
+```php
+#[Computed]
+public function selectedCall(): ?McpToolCall
+{
+ if (! $this->selectedCallId) {
+ return null;
+ }
+ return McpToolCall::with('workspace')->find($this->selectedCallId);
+}
+
+public function viewCall(int $id): void
+{
+ $this->selectedCallId = $id;
+}
+
+public function closeCallDetail(): void
+{
+ $this->selectedCallId = null;
+}
+```
+
+**Evidence - View modal (lines 155-244):**
+```blade
+@if($selectedCall)
+
+ {{ $selectedCall->tool_name }}
+
+
+
+
+ {{-- Input Parameters --}}
+ @if($selectedCall->input_params && count($selectedCall->input_params) > 0)
+
+
{{ json_encode($selectedCall->input_params, JSON_PRETTY_PRINT) }}
+
+ Code: {{ $selectedCall->error_code }}
+ {{ $selectedCall->error_message }}
+
+ @endif
+
+ {{-- Result Summary --}}
+ @if($selectedCall->result_summary && count($selectedCall->result_summary) > 0)
+ {{ json_encode($selectedCall->result_summary, JSON_PRETTY_PRINT) }}
+ @endif
+
+@endif
+```
+
+**Drill-down features:**
+- Modal with full tool call details
+- Input parameters (JSON pretty-printed)
+- Result summary (JSON pretty-printed)
+- Error details (code + message) for failed calls
+- Metadata: duration, agent type, workspace, timestamp
+- Session and Plan links for traceability
+- Filters: server, tool, status, workspace, agent type
+- Pagination with 25 per page ✅
+
+### Phase 3 Summary
+
+| AC | Description | Evidence | Status |
+|----|-------------|----------|--------|
+| AC13 | Tool usage dashboard route | `routes/web.php:190`, `ToolAnalytics.php` with Hades auth | ✅ PASS |
+| AC14 | Top 10 tools by usage | `topTools()` computed, table with 6 columns | ✅ PASS |
+| AC15 | Daily trend chart | Chart.js line chart, configurable 7-90 days | ✅ PASS |
+| AC16 | Server breakdown | `serverStats()` computed, progress bars, success rates | ✅ PASS |
+| AC17 | Error rate and duration | Table columns + colour-coded success rate | ✅ PASS |
+| AC18 | Drill-down to tool calls | Modal with input_params, result_summary, error_details | ✅ PASS |
+
+**Additional Implementation Verified:**
+- Hades access control in both components
+- Sidebar link at `hub.agents.tools`
+- Dashboard quick link to Tool Analytics
+- Drill-down links from Top Tools table
+- Recent Errors section in dashboard
+- Comprehensive filtering in ToolCalls
+- Pagination with proper links
+
+**Phase 3 Status:** ✅ VERIFIED — Ready for human approval
+
+---
+
+### Phase 3 Implementation Notes (2026-01-02 21:30)
+
+**Implementation Agent:** Claude Opus 4.5
+
+**Routes Added (`routes/web.php`):**
+- `hub.agents.tools` → ToolAnalytics dashboard
+- `hub.agents.tools.calls` → ToolCalls drill-down list
+
+**Livewire Components Created:**
+- `app/Livewire/Admin/Agent/ToolAnalytics.php` - Dashboard with stats, charts, filters
+- `app/Livewire/Admin/Agent/ToolCalls.php` - Paginated call list with modal detail
+
+**Views Created:**
+- `resources/views/admin/livewire/agent/tool-analytics.blade.php`
+- `resources/views/admin/livewire/agent/tool-calls.blade.php`
+
+**Phase 5:** Not yet implemented (commented out in routes)
+
+---
+
+### Phase 4 Implementation Notes (2026-01-02 22:30)
+
+**Implementation Agent:** Claude Opus 4.5
+
+**Route Added (`routes/web.php`):**
+- `hub.agents.api-keys` → ApiKeys management
+
+**Model Created:**
+- `app/Models/Agent/AgentApiKey.php`
+ - Key generation with `ak_` prefix + 32 random chars
+ - SHA-256 hashing for storage
+ - Permission constants: `PERM_PLANS_READ`, `PERM_PLANS_WRITE`, `PERM_PHASES_WRITE`, `PERM_SESSIONS_READ`, `PERM_SESSIONS_WRITE`, `PERM_TOOLS_READ`, `PERM_TEMPLATES_READ`, `PERM_TEMPLATES_INSTANTIATE`
+ - Status helpers: `isActive()`, `isRevoked()`, `isExpired()`
+ - Scopes: `active()`, `revoked()`, `expired()`, `forWorkspace()`
+
+**Migration Created:**
+- `database/migrations/2026_01_02_220000_create_agent_api_keys_table.php`
+ - Creates `agent_api_keys` table with key, permissions (JSON), rate_limit, call_count, timestamps
+ - Adds `agent_api_key_id` foreign key to `agent_sessions` and `mcp_tool_calls`
+
+**Service Created:**
+- `app/Services/Agent/AgentApiKeyService.php`
+ - `create()` — Generate new key with permissions and rate limit
+ - `validate()` — Validate plaintext key and return model
+ - `checkPermission()`, `checkPermissions()` — Verify access
+ - `recordUsage()` — Increment call count and cache for rate limiting
+ - `isRateLimited()`, `getRateLimitStatus()` — Rate limiting helpers
+ - `authenticate()` — Full auth flow returning structured result
+ - `revoke()`, `updatePermissions()`, `updateRateLimit()`
+
+**Livewire Component Created:**
+- `app/Livewire/Admin/Agent/ApiKeys.php`
+ - Stats: total, active, revoked, total calls
+ - Filters: workspace, status
+ - Create modal: name, workspace, permissions, rate limit, expiry
+ - Created key modal: shows plaintext key ONCE
+ - Edit modal: update permissions and rate limit
+ - Revoke action with immediate effect
+
+**View Created:**
+- `resources/views/admin/livewire/agent/api-keys.blade.php`
+
+**Sidebar Updated:**
+- Added API Keys link to Agents submenu
+
+**Phase 4 Status:** ✅ COMPLETE — Ready for verification
+
+---
+
+### Phase 4 Verification (2026-01-02 23:15)
+
+**Verification Agent:** Claude Opus 4.5
+**Verdict:** ✅ PASS - All Phase 4 acceptance criteria met
+
+#### AC19: Route `hub.agents.api-keys` manages agent API access ✅
+
+**Method:** Code inspection of `routes/web.php` and `app/Livewire/Admin/Agent/ApiKeys.php`
+
+**Evidence - Route (routes/web.php line 193):**
+```php
+Route::get('/api-keys', \App\Livewire\Admin\Agent\ApiKeys::class)->name('api-keys');
+```
+
+**Evidence - Sidebar link (sidebar.blade.php line 568):**
+```blade
+
API Keys
+```
+
+**Evidence - Hades access control (ApiKeys.php lines 49-55):**
+```php
+public function mount(): void
+{
+ $this->checkHadesAccess();
+}
+
+private function checkHadesAccess(): void
+{
+ if (! auth()->user()?->isHades()) {
+ abort(403, 'Hades access required');
+ }
+}
+```
+
+**Route exists and is accessible only to Hades users** ✅
+
+#### AC20: Can create API keys scoped to workspace ✅
+
+**Method:** Code inspection of `ApiKeys.php` and `api-keys.blade.php`
+
+**Evidence - ApiKeys.php createKey() (lines 89-116):**
+```php
+public function createKey(): void
+{
+ $this->validate([
+ 'newKeyName' => 'required|string|max:255',
+ 'newKeyWorkspace' => 'required|exists:workspaces,id',
+ 'newKeyPermissions' => 'array',
+ 'newKeyRateLimit' => 'required|integer|min:1|max:10000',
+ ]);
+
+ $key = $this->apiKeyService->create(
+ workspace: (int) $this->newKeyWorkspace,
+ name: $this->newKeyName,
+ permissions: $this->newKeyPermissions,
+ rateLimit: $this->newKeyRateLimit,
+ expiresAt: $this->newKeyExpiry ? Carbon::parse($this->newKeyExpiry) : null
+ );
+
+ $this->createdKey = $key->plainTextKey;
+ // ...
+}
+```
+
+**Evidence - View workspace dropdown (api-keys.blade.php lines 211-221):**
+```blade
+
+ Select workspace...
+ @foreach($this->workspaces as $ws)
+ {{ $ws->name }}
+ @endforeach
+
+```
+
+**Evidence - AgentApiKey model (lines 113-118):**
+```php
+public function scopeForWorkspace($query, Workspace|int $workspace)
+{
+ $workspaceId = $workspace instanceof Workspace ? $workspace->id : $workspace;
+ return $query->where('workspace_id', $workspaceId);
+}
+```
+
+**Keys are scoped to workspace via foreign key and workspace selector** ✅
+
+#### AC21: Keys have configurable permissions (read plans, write plans, execute tools) ✅
+
+**Method:** Code inspection of `AgentApiKey.php` and view
+
+**Evidence - Permission constants (AgentApiKey.php lines 63-78):**
+```php
+public const PERM_PLANS_READ = 'plans.read';
+public const PERM_PLANS_WRITE = 'plans.write';
+public const PERM_PHASES_WRITE = 'phases.write';
+public const PERM_SESSIONS_READ = 'sessions.read';
+public const PERM_SESSIONS_WRITE = 'sessions.write';
+public const PERM_TOOLS_READ = 'tools.read';
+public const PERM_TEMPLATES_READ = 'templates.read';
+public const PERM_TEMPLATES_INSTANTIATE = 'templates.instantiate';
+```
+
+**Evidence - availablePermissions() (lines 83-95):**
+```php
+public static function availablePermissions(): array
+{
+ return [
+ self::PERM_PLANS_READ => 'List and view plans',
+ self::PERM_PLANS_WRITE => 'Create, update, archive plans',
+ self::PERM_PHASES_WRITE => 'Update phase status, add/complete tasks',
+ self::PERM_SESSIONS_READ => 'List and view sessions',
+ self::PERM_SESSIONS_WRITE => 'Start, update, complete sessions',
+ self::PERM_TOOLS_READ => 'View tool analytics',
+ self::PERM_TEMPLATES_READ => 'List and view templates',
+ self::PERM_TEMPLATES_INSTANTIATE => 'Create plans from templates',
+ ];
+}
+```
+
+**Evidence - View permission checkboxes (api-keys.blade.php lines 227-237):**
+```blade
+
+ @foreach(\Mod\Agentic\Models\AgentApiKey::availablePermissions() as $perm => $description)
+
+ @endforeach
+
+```
+
+**Evidence - Permission helpers (AgentApiKey.php lines 195-220):**
+```php
+public function hasPermission(string $permission): bool
+public function hasAnyPermission(array $permissions): bool
+public function hasAllPermissions(array $permissions): bool
+```
+
+**8 configurable permissions with checkboxes in create/edit modals** ✅
+
+#### AC22: Key usage tracking (last used, call count) ✅
+
+**Method:** Code inspection of model, service, and view
+
+**Evidence - Migration fields (migration lines 24-25):**
+```php
+$table->unsignedBigInteger('call_count')->default(0);
+$table->timestamp('last_used_at')->nullable();
+```
+
+**Evidence - AgentApiKey recordUsage() (lines 230-236):**
+```php
+public function recordUsage(): self
+{
+ $this->increment('call_count');
+ $this->update(['last_used_at' => now()]);
+ return $this;
+}
+```
+
+**Evidence - AgentApiKeyService recordUsage() (lines 79-91):**
+```php
+public function recordUsage(AgentApiKey $key): void
+{
+ $key->recordUsage();
+ // Increment rate limit counter in cache
+ $cacheKey = $this->getRateLimitCacheKey($key);
+ Cache::increment($cacheKey);
+ // ...
+}
+```
+
+**Evidence - View table columns (api-keys.blade.php lines 106-118):**
+```blade
+
{{ number_format($key->call_count) }} |
+
{{ $key->getLastUsedForHumans() }} |
+```
+
+**Evidence - Stats card (api-keys.blade.php lines 54-59):**
+```blade
+
{{ number_format($this->stats['total_calls']) }}
+
Total Calls
+```
+
+**Usage tracked via call_count + last_used_at, displayed in table and stats** ✅
+
+#### AC23: Can revoke keys immediately ✅
+
+**Method:** Code inspection of service, model, and Livewire component
+
+**Evidence - AgentApiKey revoke() (lines 223-228):**
+```php
+public function revoke(): self
+{
+ $this->update(['revoked_at' => now()]);
+ return $this;
+}
+```
+
+**Evidence - AgentApiKeyService revoke() (lines 129-135):**
+```php
+public function revoke(AgentApiKey $key): void
+{
+ $key->revoke();
+ // Clear rate limit cache
+ Cache::forget($this->getRateLimitCacheKey($key));
+}
+```
+
+**Evidence - ApiKeys.php revokeKey() (lines 118-128):**
+```php
+public function revokeKey(int $keyId): void
+{
+ $key = AgentApiKey::findOrFail($keyId);
+ $this->apiKeyService->revoke($key);
+ Flux::toast(
+ heading: 'API Key Revoked',
+ text: "Key '{$key->name}' has been revoked and can no longer be used.",
+ variant: 'warning',
+ );
+}
+```
+
+**Evidence - View revoke button (api-keys.blade.php line 133):**
+```blade
+
+ Revoke Key
+
+```
+
+**Evidence - isRevoked helper (AgentApiKey.php lines 184-187):**
+```php
+public function isRevoked(): bool
+{
+ return $this->revoked_at !== null;
+}
+```
+
+**Revocation sets revoked_at timestamp, clears cache, shows confirmation** ✅
+
+#### AC24: Rate limiting configuration per key ✅
+
+**Method:** Code inspection of model, service, and view
+
+**Evidence - Migration field (line 23):**
+```php
+$table->integer('rate_limit')->default(100); // Calls per minute
+```
+
+**Evidence - AgentApiKeyService rate limiting (lines 96-124):**
+```php
+public function isRateLimited(AgentApiKey $key): bool
+{
+ $cacheKey = $this->getRateLimitCacheKey($key);
+ $currentCalls = (int) Cache::get($cacheKey, 0);
+ return $currentCalls >= $key->rate_limit;
+}
+
+public function getRateLimitStatus(AgentApiKey $key): array
+{
+ $cacheKey = $this->getRateLimitCacheKey($key);
+ $currentCalls = (int) Cache::get($cacheKey, 0);
+ $remaining = max(0, $key->rate_limit - $currentCalls);
+ // ...
+ return [
+ 'limit' => $key->rate_limit,
+ 'remaining' => $remaining,
+ 'reset_in_seconds' => max(0, $ttl),
+ 'used' => $currentCalls,
+ ];
+}
+```
+
+**Evidence - authenticate() rate limiting check (lines 253-262):**
+```php
+if ($this->isRateLimited($key)) {
+ $status = $this->getRateLimitStatus($key);
+ return [
+ 'success' => false,
+ 'error' => 'rate_limited',
+ 'message' => 'Rate limit exceeded',
+ 'rate_limit' => $status,
+ ];
+}
+```
+
+**Evidence - View rate limit input (api-keys.blade.php lines 239-241):**
+```blade
+
+```
+
+**Evidence - Table column (api-keys.blade.php line 102):**
+```blade
+
{{ $key->rate_limit }}/min |
+```
+
+**Evidence - Edit modal rate limit (api-keys.blade.php lines 334-336):**
+```blade
+
+```
+
+**Rate limit configurable 1-10000 calls/min, enforced via Cache with 60s window** ✅
+
+### Phase 4 Summary
+
+| AC | Description | Evidence | Status |
+|----|-------------|----------|--------|
+| AC19 | Route manages API access | `routes/web.php:193`, Hades auth, sidebar link | ✅ PASS |
+| AC20 | Keys scoped to workspace | `workspace_id` FK, workspace dropdown in create modal | ✅ PASS |
+| AC21 | Configurable permissions | 8 permissions with checkboxes, `hasPermission()` helpers | ✅ PASS |
+| AC22 | Usage tracking | `call_count` + `last_used_at` fields, displayed in UI | ✅ PASS |
+| AC23 | Immediate revocation | `revoke()` sets timestamp, clears cache, confirmation dialog | ✅ PASS |
+| AC24 | Rate limiting per key | Configurable 1-10000/min, Cache-based enforcement | ✅ PASS |
+
+**Additional Implementation Verified:**
+- Hades access control in component
+- Sidebar link at line 568
+- Stats cards: total, active, revoked, total calls
+- Create modal shows plaintext key ONCE
+- Edit modal for permissions and rate limit updates
+- Key expiry support (optional)
+- Filter by workspace and status (active/revoked/expired)
+- Foreign keys added to `agent_sessions` and `mcp_tool_calls` for tracking
+
+**Phase 4 Status:** ✅ VERIFIED — Ready for human approval
+
+---
+
+### Phase 5 Implementation Notes (2026-01-02 23:45)
+
+**Implementation Agent:** Claude Opus 4.5
+
+**Route Added (`routes/web.php`):**
+- `hub.agents.templates` → Templates browser
+
+**Livewire Component Created:**
+- `app/Livewire/Admin/Agent/Templates.php`
+ - Uses existing `PlanTemplateService` for all template operations
+ - Template listing with category filter and search
+ - Preview modal showing phases, tasks, variables, guidelines
+ - Create plan modal with variable inputs and workspace selection
+ - YAML import modal with file upload, validation, and preview
+ - Delete template functionality
+
+**View Created:**
+- `resources/views/admin/livewire/agent/templates.blade.php`
+ - Stats cards: total templates, categories, total phases, with variables
+ - Grid layout for template cards
+ - Category colour coding
+ - Preview modal with full template details
+ - Create modal with variable input fields
+ - Import modal with drag-drop file upload
+
+**Sidebar Updated:**
+- Added Templates link to Agents submenu
+
+**Dashboard Updated:**
+- Templates quick link now active (was "Coming soon")
+
+**Existing Templates (5):**
+- `bug-fix.yaml` - Bug fix workflow
+- `code-review.yaml` - Code review process
+- `feature-port.yaml` - Feature porting
+- `new-feature.yaml` - New feature development
+- `refactor.yaml` - Code refactoring
+
+**Phase 5 Status:** ✅ COMPLETE — Ready for verification
+
+---
+
+### Phase 5 Verification (2026-01-02 23:45)
+
+**Verification Agent:** Claude Opus 4.5
+**Verdict:** ✅ PASS - All Phase 5 acceptance criteria met
+
+#### AC25: Route `hub.agents.templates` lists available plan templates ✅
+
+**Method:** Code inspection of `routes/web.php` and `app/Livewire/Admin/Agent/Templates.php`
+
+**Evidence - Route (routes/web.php line 195):**
+```php
+Route::get('/templates', \App\Livewire\Admin\Agent\Templates::class)->name('templates');
+```
+
+**Evidence - Sidebar link (sidebar.blade.php lines 573-574):**
+```blade
+
+ Templates
+```
+
+**Evidence - Templates.php templates() computed property (lines 76-93):**
+```php
+#[Computed]
+public function templates(): Collection
+{
+ $templates = $this->templateService->list();
+
+ if ($this->category) {
+ $templates = $templates->filter(fn ($t) => $t['category'] === $this->category);
+ }
+
+ if ($this->search) {
+ $search = strtolower($this->search);
+ $templates = $templates->filter(fn ($t) => ...);
+ }
+
+ return $templates->values();
+}
+```
+
+**Evidence - View grid (templates.blade.php lines 60-149):**
+```blade
+
+ @foreach($this->templates as $template)
+
+
+
+ @endforeach
+
+```
+
+**5 templates available:** bug-fix, code-review, feature-port, new-feature, refactor ✅
+
+#### AC26: Template preview shows phases and variables ✅
+
+**Method:** Code inspection of `Templates.php` and `templates.blade.php`
+
+**Evidence - previewTemplate() computed property (Templates.php lines 107-115):**
+```php
+#[Computed]
+public function previewTemplate(): ?array
+{
+ if (! $this->previewSlug) {
+ return null;
+ }
+ return $this->templateService->previewTemplate($this->previewSlug, []);
+}
+```
+
+**Evidence - Preview modal phases (templates.blade.php lines 207-235):**
+```blade
+Phases ({{ count($this->previewTemplate['phases']) }})
+
+ @foreach($this->previewTemplate['phases'] as $index => $phase)
+
+
{{ $phase['order'] }}
+
{{ $phase['name'] }}
+ @if(!empty($phase['tasks']))
+
+ @foreach($phase['tasks'] as $task)
+ - {{ is_array($task) ? $task['name'] : $task }}
+ @endforeach
+
+ @endif
+
+ @endforeach
+
+
+ | Variable | Description | Default | Required |
|---|
+
+
+ @foreach($variables as $name => $config)
+
+ | {{ $name }} |
+ {{ $config['description'] ?? '-' }} |
+ {{ $config['default'] ?? '-' }} |
+ {{ $config['required'] ? 'Yes' : 'No' }} |
+
+ @endforeach
+
+
+@endif
+```
+
+**Preview shows:** Phases with order/name/tasks, Variables with name/description/default/required, Guidelines ✅
+
+#### AC27: Can create new plan from template with variable input ✅
+
+**Method:** Code inspection of `Templates.php` and `templates.blade.php`
+
+**Evidence - openCreateModal() (Templates.php lines 162-188):**
+```php
+public function openCreateModal(string $slug): void
+{
+ $template = $this->templateService->get($slug);
+ $this->createTemplateSlug = $slug;
+ $this->createTitle = $template['name'];
+ $this->createWorkspaceId = $this->workspaces->first()?->id ?? 0;
+
+ // Initialise variables with defaults
+ $this->createVariables = [];
+ foreach ($template['variables'] ?? [] as $name => $config) {
+ $this->createVariables[$name] = $config['default'] ?? '';
+ }
+ $this->showCreateModal = true;
+}
+```
+
+**Evidence - createPlan() (Templates.php lines 198-272):**
+```php
+public function createPlan(): void
+{
+ // Validate required variables
+ $this->validate([
+ 'createWorkspaceId' => 'required|exists:workspaces,id',
+ 'createTitle' => 'required|string|max:255',
+ ]);
+
+ // Add variable validation
+ foreach ($template['variables'] ?? [] as $name => $config) {
+ if ($config['required'] ?? false) {
+ $rules["createVariables.{$name}"] = 'required|string';
+ }
+ }
+
+ // Create the plan via service
+ $plan = $this->templateService->createPlan(
+ $this->createTemplateSlug,
+ $this->createVariables,
+ ['title' => $this->createTitle, 'activate' => $this->createActivate],
+ $workspace
+ );
+
+ // Redirect to new plan
+ $this->redirect(route('hub.agents.plans.show', $plan->slug), navigate: true);
+}
+```
+
+**Evidence - Create modal with variable inputs (templates.blade.php lines 319-341):**
+```blade
+@if(!empty($this->createTemplate['variables']))
+
Template Variables
+
+ @foreach($this->createTemplate['variables'] as $name => $config)
+
+ @endforeach
+
+@endif
+```
+
+**Create plan features:** Plan title, Workspace selection, Variable inputs, Activate immediately option, Live preview ✅
+
+#### AC28: Template categories displayed for organisation ✅
+
+**Method:** Code inspection of `Templates.php`, `PlanTemplateService.php`, and view
+
+**Evidence - categories() computed property (Templates.php lines 95-99):**
+```php
+#[Computed]
+public function categories(): Collection
+{
+ return $this->templateService->getCategories();
+}
+```
+
+**Evidence - PlanTemplateService getCategories() (lines 319-326):**
+```php
+public function getCategories(): Collection
+{
+ return $this->list()
+ ->pluck('category')
+ ->unique()
+ ->sort()
+ ->values();
+}
+```
+
+**Evidence - Category filter dropdown (templates.blade.php lines 45-50):**
+```blade
+
+ All Categories
+ @foreach($this->categories as $cat)
+ {{ ucfirst($cat) }}
+ @endforeach
+
+```
+
+**Evidence - Category badge in template cards (templates.blade.php lines 69-71):**
+```blade
+
+ {{ ucfirst($template['category']) }}
+
+```
+
+**Evidence - Category colour coding (Templates.php lines 436-446):**
+```php
+public function getCategoryColor(string $category): string
+{
+ return match ($category) {
+ 'development' => 'bg-blue-100 text-blue-700 ...',
+ 'maintenance' => 'bg-green-100 text-green-700 ...',
+ 'review' => 'bg-amber-100 text-amber-700 ...',
+ 'migration' => 'bg-purple-100 text-purple-700 ...',
+ 'custom' => 'bg-zinc-100 text-zinc-700 ...',
+ default => 'bg-violet-100 text-violet-700 ...',
+ };
+}
+```
+
+**Category features:** Filter dropdown, Colour-coded badges, Stats showing category count ✅
+
+#### AC29: Can import custom templates (YAML upload) ✅
+
+**Method:** Code inspection of `Templates.php` and `templates.blade.php`
+
+**Evidence - Import modal state (Templates.php lines 53-62):**
+```php
+public bool $showImportModal = false;
+public ?UploadedFile $importFile = null;
+public string $importFileName = '';
+public ?array $importPreview = null;
+public ?string $importError = null;
+```
+
+**Evidence - updatedImportFile() validation (Templates.php lines 293-351):**
+```php
+public function updatedImportFile(): void
+{
+ $content = file_get_contents($this->importFile->getRealPath());
+ $parsed = Yaml::parse($content);
+
+ // Validate basic structure
+ if (! is_array($parsed)) {
+ $this->importError = 'Invalid YAML format: expected an object.';
+ return;
+ }
+ if (! isset($parsed['name'])) {
+ $this->importError = 'Template must have a "name" field.';
+ return;
+ }
+ if (! isset($parsed['phases']) || ! is_array($parsed['phases'])) {
+ $this->importError = 'Template must have a "phases" array.';
+ return;
+ }
+
+ // Build preview
+ $this->importPreview = [
+ 'name' => $parsed['name'],
+ 'description' => $parsed['description'] ?? null,
+ 'category' => $parsed['category'] ?? 'custom',
+ 'phases_count' => count($parsed['phases']),
+ 'variables_count' => count($parsed['variables'] ?? []),
+ ];
+}
+```
+
+**Evidence - importTemplate() save (Templates.php lines 353-397):**
+```php
+public function importTemplate(): void
+{
+ $this->validate([
+ 'importFileName' => 'required|string|regex:/^[a-z0-9-]+$/|max:64',
+ ]);
+
+ $content = file_get_contents($this->importFile->getRealPath());
+ $targetPath = resource_path("plan-templates/{$this->importFileName}.yaml");
+
+ // Check for existing file
+ if (File::exists($targetPath)) {
+ $this->importError = 'A template with this filename already exists.';
+ return;
+ }
+
+ // Save the file
+ File::put($targetPath, $content);
+
+ Flux::toast(heading: 'Template Imported', ...);
+}
+```
+
+**Evidence - Import modal with file upload (templates.blade.php lines 381-476):**
+```blade
+
+ Import Template
+
+ {{-- File Upload --}}
+
+
+
+
+ {{-- Preview --}}
+ @if($importPreview)
+
+ - Name:
- {{ $importPreview['name'] }}
+ - Category:
- {{ $importPreview['category'] }}
+ - Phases:
- {{ $importPreview['phases_count'] }}
+ - Variables:
- {{ $importPreview['variables_count'] }}
+
+
+
+ @endif
+
+ Import Template
+
+```
+
+**Import features:** YAML file upload, Validation (structure, name, phases), Preview before import, Custom filename, Duplicate detection ✅
+
+### Phase 5 Summary
+
+| AC | Description | Evidence | Status |
+|----|-------------|----------|--------|
+| AC25 | Route lists templates | `routes/web.php:195`, `templates()` computed, grid layout | ✅ PASS |
+| AC26 | Preview shows phases/variables | `previewTemplate()`, modal with phases list + variables table | ✅ PASS |
+| AC27 | Create plan with variables | `createPlan()`, variable inputs in modal, validation | ✅ PASS |
+| AC28 | Categories displayed | `getCategories()`, filter dropdown, colour-coded badges | ✅ PASS |
+| AC29 | YAML import | `importTemplate()`, file upload, validation, preview | ✅ PASS |
+
+**Additional Implementation Verified:**
+- Hades access control in component (`checkHadesAccess()`)
+- Sidebar link at line 573
+- Dashboard quick link activated
+- Template deletion with confirmation
+- 5 templates available: bug-fix, code-review, feature-port, new-feature, refactor
+- Stats cards: total templates, categories, phases, with variables
+- Search functionality with debounce
+- Category colour coding for visual organisation
+
+**Phase 5 Status:** ✅ VERIFIED — Ready for human approval
+
+---
+
+## Implementation Hints (Added by Planning Agent)
+
+### Existing Code Reference
+
+**Agent models already exist** — don't recreate them:
+
+| Model | Location | Key Methods |
+|-------|----------|-------------|
+| `AgentPlan` | `app/Models/Agent/AgentPlan.php` | `getProgress()`, `getCurrentPhase()`, `activate()`, `complete()`, `archive()`, `toMcpContext()` |
+| `AgentPhase` | `app/Models/Agent/AgentPhase.php` | Status constants: `STATUS_PENDING`, `STATUS_IN_PROGRESS`, `STATUS_COMPLETED`, `STATUS_BLOCKED`, `STATUS_SKIPPED` |
+| `AgentSession` | `app/Models/Agent/AgentSession.php` | `start()`, `pause()`, `resume()`, `complete()`, `fail()`, `logAction()`, `prepareHandoff()`, `getDurationFormatted()` |
+| `McpToolCallStat` | `app/Models/Mcp/McpToolCallStat.php` | `getTopTools()`, `getDailyTrend()`, `getServerStats()` — these are ready-made for dashboards |
+
+### Hades Auth Pattern
+
+Follow existing pattern from other Hades-only components:
+
+```php
+// In mount() method
+public function mount(): void
+{
+ if (!auth()->user()?->isHades()) {
+ abort(403);
+ }
+ // ... rest of mount
+}
+```
+
+See examples: `PackageManager.php:21`, `FeatureManager.php:20`, `Platform.php:36`
+
+### Sidebar Integration
+
+Add to `resources/views/admin/components/sidebar.blade.php` **after line 376** (before the closing `` of the Hades section), using the existing pattern:
+
+```blade
+{{-- Agent Operations --}}
+
+
+
+
+
+
+```
+
+### Admin Layout Pattern
+
+Use existing admin layout:
+
+```php
+public function render()
+{
+ return view('admin.admin.agent.dashboard')
+ ->layout('admin.layouts.app', ['title' => 'Agent Dashboard']);
+}
+```
+
+### View Location
+
+Views go in `resources/views/admin/livewire/agent/` (matches other admin components)
+
+### Dashboard Queries (Ready to Use)
+
+```php
+// These methods already exist on McpToolCallStat
+$topTools = McpToolCallStat::getTopTools(days: 7, limit: 10);
+$dailyTrend = McpToolCallStat::getDailyTrend(days: 7);
+$serverStats = McpToolCallStat::getServerStats(days: 7);
+
+// AgentPlan queries
+$activePlans = AgentPlan::active()->with(['workspace', 'agentPhases'])->count();
+$activeSessions = AgentSession::active()->count();
+```
+
+### Routes Location
+
+Add after line 164 in `routes/web.php` (inside the hub group, after Commerce routes):
+
+```php
+// Check existing structure at lines 131-169 for context
+```
+
+---
+
+*This task creates the human interface for supervising AI agent operations.*
diff --git a/changelog/2026/jan/agentic-tasks-readme.md b/changelog/2026/jan/agentic-tasks-readme.md
new file mode 100644
index 0000000..0797800
--- /dev/null
+++ b/changelog/2026/jan/agentic-tasks-readme.md
@@ -0,0 +1,186 @@
+# Agentic Task System
+
+MCP-powered workspace for persistent work plans that survive context limits and enable multi-agent collaboration.
+
+## Why this exists
+
+- **Context persistence** - Work plans persist across Claude sessions, surviving context window limits
+- **Multi-agent collaboration** - Handoff support between different agents with shared state
+- **Checkpoint verification** - Phase gates ensure work is complete before progressing
+- **Structured planning** - Break complex tasks into phases with dependencies
+
+## Location
+
+```
+app/Models/Agent/AgentPlan.php
+app/Models/Agent/AgentPhase.php
+app/Models/Agent/AgentSession.php
+app/Models/Agent/WorkspaceState.php
+app/Console/Commands/Agent/McpAgentServerCommand.php
+```
+
+## Basic usage
+
+```bash
+# Create a new plan
+php artisan plan:create my-feature --title="Implement Feature X"
+
+# Import from markdown
+php artisan plan:create my-plan --import=PLAN.md --activate
+
+# List all plans
+php artisan plan:list
+php artisan plan:list --status=active
+
+# Show plan details
+php artisan plan:show my-plan
+php artisan plan:show my-plan --markdown
+
+# Check phase completion (checkpoint)
+php artisan plan:check my-plan
+php artisan plan:check my-plan 1 # Check specific phase
+
+# Manage phases
+php artisan plan:phase my-plan 1 --status=in_progress
+php artisan plan:phase my-plan 1 --add-task="Complete the migration"
+php artisan plan:phase my-plan 1 --complete-task=0
+```
+
+## Key methods
+
+### AgentPlan
+
+```php
+use Mod\Agentic\Models\AgentPlan;
+
+// Create a plan
+$plan = AgentPlan::create([
+ 'slug' => 'my-feature',
+ 'title' => 'Implement Feature X',
+ 'status' => AgentPlan::STATUS_ACTIVE,
+]);
+
+// Get current phase
+$phase = $plan->getCurrentPhase();
+// Returns: AgentPhase or null
+
+// Check completion
+$plan->checkAllPhasesComplete();
+// Returns: bool
+```
+
+### AgentPhase
+
+```php
+use Mod\Agentic\Models\AgentPhase;
+
+// Start a phase
+$phase->start();
+// Returns: self (status changed to in_progress)
+
+// Complete a phase (with transaction protection)
+$phase->complete();
+// Returns: self (status changed to completed, plan auto-completes if all done)
+
+// Check if phase can start (dependencies met)
+$phase->canStart();
+// Returns: bool
+```
+
+### WorkspaceState
+
+```php
+use Mod\Agentic\Models\WorkspaceState;
+
+// Store shared state
+WorkspaceState::setValue($plan, 'api_findings', ['endpoints' => 12]);
+
+// Retrieve state
+$value = WorkspaceState::getValue($plan, 'api_findings');
+// Returns: array or null
+```
+
+## Example: Checkpoint pattern
+
+The checkpoint pattern ensures agents verify previous work before progressing:
+
+```
+Agent: "Starting Phase 3"
+ ↓
+MCP: phase_check(plan_slug, phase=2)
+ ↓
+Returns: {
+ "complete": false,
+ "remaining_tasks": ["Task 2.4", "Task 2.5"],
+ "message": "Phase 2 not complete. 2 tasks remaining."
+}
+ ↓
+Agent: "Completing remaining Phase 2 tasks first..."
+```
+
+## Configuration
+
+MCP server configuration for Claude Code:
+
+```json
+{
+ "mcpServers": {
+ "hosthub-agent": {
+ "command": "php",
+ "args": ["artisan", "mcp:agent-server"],
+ "cwd": "/path/to/host.uk.com"
+ }
+ }
+}
+```
+
+## How it works
+
+```
+1. Plan created with phases (via CLI or MCP)
+2. Agent starts session and binds to plan
+3. Agent works through phases, logging actions
+4. Checkpoint verification before phase transitions
+5. Workspace state shared between agents
+6. Handoff notes preserved for context continuity
+```
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `plan_create` | Create new plan with phases |
+| `plan_get` | Get plan by slug with all phases |
+| `plan_list` | List plans (optionally filtered) |
+| `plan_update` | Update plan status/metadata |
+| `phase_update` | Update phase status |
+| `phase_check` | Verify phase completion |
+| `task_add` | Add task to a phase |
+| `task_complete` | Mark task done |
+| `session_start` | Begin agent session |
+| `session_log` | Log action to session |
+| `session_artifact` | Log file artifact |
+| `session_handoff` | Prepare for agent handoff |
+| `session_resume` | Resume from previous session |
+| `session_complete` | Mark session completed |
+| `state_set` | Store workspace state |
+| `state_get` | Retrieve workspace state |
+| `state_list` | List all state keys |
+| `state_delete` | Delete state key |
+
+## MCP Resources
+
+| URI | Purpose |
+|-----|---------|
+| `hosthub://plans` | List of all work plans |
+| `hosthub://plans/{slug}` | Full plan as markdown |
+| `hosthub://plans/{slug}/phase/{n}` | Phase tasks as checklist |
+| `hosthub://state/{plan}/{key}` | Specific state value |
+| `hosthub://sessions/{id}` | Session handoff context |
+
+## Related services
+
+- `Task` model - Simple task tracking (different purpose)
+- `ContentTask` model - Content generation tasks
+
+See also: `doc/dev-feat-docs/agentic-tasks/PORTING_PLAN.md` for implementation details.
diff --git a/changelog/2026/jan/code-review.md b/changelog/2026/jan/code-review.md
new file mode 100644
index 0000000..d32795e
--- /dev/null
+++ b/changelog/2026/jan/code-review.md
@@ -0,0 +1,107 @@
+# Agentic Module Review
+
+**Updated:** 2026-01-21 - OpenAI pricing, MCP token lookup, and Boot.php cleanup verified complete
+
+## Overview
+
+The Agentic module provides AI agent infrastructure for Host Hub, including:
+
+1. **Multi-provider AI abstraction** - Unified interface for Claude, Gemini, and OpenAI APIs
+2. **Agent work plans** - Structured task tracking with phases, dependencies, and progress
+3. **Session management** - Track agent work sessions for handoff and context recovery
+4. **API key management** - Workspace-scoped keys with permissions and rate limiting
+5. **Plan templates** - YAML-based reusable plan structures
+6. **Content generation pipeline** - Batch content generation with quality validation
+7. **Agent detection** - Identify AI agents from HTTP requests (Trees for Agents)
+8. **Admin dashboard** - Hades-only admin panel for monitoring agent operations
+
+## Production Readiness Score: 88/100 (was 85/100 - Additional improvements 2026-01-21)
+
+The module has solid foundational architecture. Critical issues fixed in Wave 2. All recommended improvements now implemented. OpenAI pricing, MCP token database lookup, and Boot.php cleanup completed.
+
+## Critical Issues (Must Fix)
+
+- [x] **Missing `agent_api_keys` table migration** - FIXED: Migration exists at `Migrations/2026_01_15_090000_create_agent_api_keys_table.php`.
+- [x] **Missing `tasks` table migration** - FIXED: Migration exists at `Migrations/2026_01_15_090001_create_tasks_table.php`. Task model updated with `BelongsToWorkspace` trait and `workspace_id` in fillable.
+- [x] **`AgenticResponse::estimateCost()` missing OpenAI pricing** - FIXED: Pricing array now includes GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-4, GPT-3.5-turbo, o1, o1-mini, and o1-preview models.
+- [x] **`AgentApiKey::getRecentCallCount()` is a stub** - FIXED: Now reads from cache key `agent_api_key_rate:{id}` which is incremented by `AgentApiKeyService::recordUsage()`.
+- [x] **`PlanCommand`/`TaskCommand` missing workspace scope** - FIXED: Both commands now require `--workspace=ID` option or authenticated user context. All queries scoped via `forWorkspace()` to prevent data leakage.
+
+## Recommended Improvements
+
+- [x] **Add retry logic to AI provider services** - FIXED: HasRetry trait added with exponential backoff for transient failures.
+- [x] **Stream parsing is fragile** - FIXED: HasStreamParsing trait added for robust chunked response handling.
+- [x] **ContentService uses hardcoded paths** - FIXED: `$batchPath`, `$promptPath`, `$draftsPath` now use config values.
+- [x] **AgentApiKeyService rate limit TTL is incorrect** - FIXED: Now uses `Cache::add()` with TTL to prevent race condition.
+- [x] **Missing validation on PlanTemplateService variable substitution** - FIXED: JSON escaping added to prevent data corruption from special characters.
+- [x] **Dashboard queries not optimised** - FIXED: `cacheWithLock` added to prevent cache stampede.
+- [x] **Add middleware for admin routes** - FIXED: RequireHades middleware now applied to `/hub/agents/*` routes.
+- [x] **Add request validation to ForAgentsController** - FIXED: Rate limiting and caching added.
+
+## Missing Features (Future)
+
+- [x] **MCP tool handlers commented out** - FIXED: `Boot::onMcpTools()` now has clean documentation explaining that agent tools are registered in Mcp module via AgentToolRegistry.
+- [x] **MCP token lookup not implemented** - FIXED: `AgentDetection::identifyFromMcpToken()` now supports opaque `ak_` prefix tokens with database lookup via `AgentApiKey::findByKey()`, plus structured `provider:model:secret` format.
+- [ ] **No tests for AgentApiKey model** - Unlike other models (AgentPlan, AgentPhase, AgentSession), AgentApiKey has no dedicated test file.
+- [ ] **No tests for AI provider services** - ClaudeService, GeminiService, OpenAIService have no unit tests.
+- [ ] **No tests for AgentApiKeyService** - Service has complex authentication logic but no tests.
+- [ ] **No tests for AgentDetection** - User-Agent pattern matching logic is untested.
+- [ ] **No tests for PlanTemplateService** - Variable substitution and plan creation untested.
+- [ ] **Missing admin panel tests for all Livewire components** - Only `UseCase/AdminPanelBasic.php` exists but may not execute (uses non-standard test syntax).
+- [ ] **GenerateCommand depends on Content module** - Uses `Mod\Content\Models\ContentBrief`, `Mod\Content\Jobs\GenerateContentJob`, etc. Should verify Content module is always loaded.
+
+## Test Coverage Assessment
+
+**Current test files:**
+- `Tests/Feature/AgentPlanTest.php` - 17 tests, good coverage of plan lifecycle
+- `Tests/Feature/AgentPhaseTest.php` - 17 tests, good coverage of phase operations
+- `Tests/Feature/AgentSessionTest.php` - 22 tests, thorough session tracking tests
+- `Tests/Feature/ContentServiceTest.php` - 4 tests, basic coverage using mocks
+- `Tests/UseCase/AdminPanelBasic.php` - UI acceptance tests (may not be functional)
+
+**Coverage gaps:**
+- No unit tests for any of the 11 services
+- No tests for 3 console commands
+- No tests for AgentApiKey model
+- No tests for Task model
+- No tests for admin Livewire components
+- No integration tests for AI provider APIs
+
+**Estimated coverage:** ~35% (models well-tested, services untested)
+
+## Security Concerns
+
+1. **API key stored as SHA-256 hash only** - No salt used in `AgentApiKey::generate()`. While SHA-256 is acceptable, using `password_hash()` with Argon2 would be more secure for credential storage.
+
+2. **Rate limiting bypass** - FIXED: `getRecentCallCount()` now reads from cache, making rate limiting functional when `AgentApiKeyService::recordUsage()` is called.
+
+3. **No input validation on plan/template variables** - `PlanTemplateService::substituteVariables()` uses regex replacement without sanitising input, potentially allowing injection.
+
+4. **Admin routes lack middleware** - FIXED: RequireHades middleware now applied to admin routes.
+
+5. **ForAgentsController exposes internal URLs** - Returns hardcoded URLs to MCP registry and documentation that could be enumerated by attackers.
+
+6. **TaskCommand uses FIELD() with unescaped values** - `orderByRaw("FIELD(priority, 'urgent', 'high', 'normal', 'low')")` - while current usage is safe (status/priority are validated), this pattern is SQL injection prone if extended.
+
+## Notes
+
+**Architecture:** Well-structured following the modular monolith pattern. Boot.php properly uses event listeners for lazy loading. Services are appropriately separated.
+
+**Code quality:** Consistent use of strict types, proper PHPDoc annotations, and Eloquent conventions. Factory pattern for test data is well implemented.
+
+**Dependencies on other modules:**
+- `Mod\Tenant` - Workspace model and BelongsToWorkspace trait
+- `Mod\Mcp` - McpToolCallStat for dashboard analytics
+- `Mod\Content` - ContentBrief, AIUsage, GenerateContentJob (in GenerateCommand)
+
+**Files reviewed:**
+- `/app/Mod/Agentic/Boot.php`
+- `/app/Mod/Agentic/config.php`
+- `/app/Mod/Agentic/Migrations/2026_01_15_100000_create_agentic_tables.php`
+- All 11 models in `/app/Mod/Agentic/Models/`
+- All 9 services in `/app/Mod/Agentic/Services/`
+- All 3 console commands in `/app/Mod/Agentic/Console/Commands/`
+- `/app/Mod/Agentic/Controllers/ForAgentsController.php`
+- `/app/Mod/Agentic/Routes/admin.php`
+- All 4 test files in `/app/Mod/Agentic/Tests/`
+- `/app/Mod/Agentic/View/Modal/Admin/Dashboard.php`
diff --git a/changelog/2026/jan/features.md b/changelog/2026/jan/features.md
new file mode 100644
index 0000000..5bdd1b6
--- /dev/null
+++ b/changelog/2026/jan/features.md
@@ -0,0 +1,72 @@
+# Core-Agentic - January 2026
+
+## Features Implemented
+
+### Agent Plans Admin UI (TASK-006)
+
+Complete admin interface for managing agent work plans.
+
+**Components:**
+- Plan list with status filters
+- Plan editor with phases
+- Phase management (add, edit, reorder)
+- Progress tracking
+- Session viewer
+
+**Files:**
+- `View/Modal/Admin/PlanManager.php`
+- `View/Modal/Admin/PlanEditor.php`
+- `View/Modal/Admin/PhaseEditor.php`
+
+---
+
+### Session Recovery/Replay
+
+Resume and replay agent sessions across context windows.
+
+**Methods:**
+- `getReplayContext()` - reconstruct session state
+- `createReplaySession()` - spawn continuation session
+- Checkpoint and decision tracking
+
+**MCP Tool:**
+- `session_replay` - replay tool for agents
+
+---
+
+### Agent API Keys
+
+Scoped API keys for agent authentication.
+
+**Features:**
+- Key generation with prefixes
+- Scope restrictions
+- Usage tracking
+- IP restrictions
+
+**Files:**
+- `Models/AgentApiKey.php`
+- `Services/AgentApiKeyService.php`
+- `Services/IpRestrictionService.php`
+
+---
+
+### MCP Usage Quotas
+
+Per-workspace usage limits for MCP operations.
+
+**Files:**
+- `Models/McpUsageQuota.php`
+- `Services/McpQuotaService.php`
+- Quota middleware
+- Entitlement feature integration
+
+---
+
+### Plan Templates
+
+Reusable plan templates for common workflows.
+
+**Files:**
+- `Services/PlanTemplateService.php`
+- Template MCP tools
diff --git a/composer.json b/composer.json
index 89a3dd6..15fe864 100644
--- a/composer.json
+++ b/composer.json
@@ -1,49 +1,50 @@
{
- "name": "host-uk/core-agentic",
- "description": "AI agent orchestration and MCP tools for Laravel",
- "keywords": [
- "ai",
- "agents",
- "mcp",
- "orchestration"
- ],
- "license": "EUPL-1.2",
- "require": {
- "php": "^8.2",
- "host-uk/core": "dev-main"
- },
- "require-dev": {
- "laravel/pint": "^1.18",
- "orchestra/testbench": "^9.0|^10.0",
- "pestphp/pest": "^3.0"
- },
- "autoload": {
- "psr-4": {
- "Core\\Agentic\\": ""
- }
- },
- "autoload-dev": {
- "psr-4": {
- "Core\\Agentic\\Tests\\": "Tests/"
- }
- },
- "extra": {
- "laravel": {
- "providers": [
- "Core\\Agentic\\Boot"
- ]
- }
- },
- "scripts": {
- "lint": "pint",
- "test": "pest"
- },
- "config": {
- "sort-packages": true,
- "allow-plugins": {
- "pestphp/pest-plugin": true
- }
- },
- "minimum-stability": "dev",
- "prefer-stable": true
+ "name": "host-uk/core-agentic",
+ "description": "AI agent orchestration and MCP tools for Laravel",
+ "keywords": [
+ "ai",
+ "agents",
+ "mcp",
+ "orchestration"
+ ],
+ "license": "EUPL-1.2",
+ "require": {
+ "php": "^8.2",
+ "host-uk/core": "dev-main"
+ },
+ "require-dev": {
+ "laravel/pint": "^1.18",
+ "orchestra/testbench": "^9.0|^10.0",
+ "pestphp/pest": "^3.0"
+ },
+ "autoload": {
+ "psr-4": {
+ "Core\\Mod\\Agentic\\": "",
+ "Core\\Service\\Agentic\\": "Service/"
+ }
+ },
+ "autoload-dev": {
+ "psr-4": {
+ "Core\\Mod\\Agentic\\Tests\\": "Tests/"
+ }
+ },
+ "extra": {
+ "laravel": {
+ "providers": [
+ "Core\\Mod\\Agentic\\Boot"
+ ]
+ }
+ },
+ "scripts": {
+ "lint": "pint",
+ "test": "pest"
+ },
+ "config": {
+ "sort-packages": true,
+ "allow-plugins": {
+ "pestphp/pest-plugin": true
+ }
+ },
+ "minimum-stability": "dev",
+ "prefer-stable": true
}
diff --git a/routes/admin.php b/routes/admin.php
index 3f7a9f2..9458774 100644
--- a/routes/admin.php
+++ b/routes/admin.php
@@ -17,19 +17,19 @@ Route::prefix('hub')->name('hub.')->group(function () {
->middleware(['auth', RequireHades::class])
->group(function () {
// Phase 1: Plan Dashboard
- Route::get('/', \Core\Agentic\View\Modal\Admin\Dashboard::class)->name('index');
- Route::get('/plans', \Core\Agentic\View\Modal\Admin\Plans::class)->name('plans');
- Route::get('/plans/{slug}', \Core\Agentic\View\Modal\Admin\PlanDetail::class)->name('plans.show');
+ Route::get('/', \Core\Mod\Agentic\View\Modal\Admin\Dashboard::class)->name('index');
+ Route::get('/plans', \Core\Mod\Agentic\View\Modal\Admin\Plans::class)->name('plans');
+ Route::get('/plans/{slug}', \Core\Mod\Agentic\View\Modal\Admin\PlanDetail::class)->name('plans.show');
// Phase 2: Session Monitor
- Route::get('/sessions', \Core\Agentic\View\Modal\Admin\Sessions::class)->name('sessions');
- Route::get('/sessions/{id}', \Core\Agentic\View\Modal\Admin\SessionDetail::class)->name('sessions.show');
+ Route::get('/sessions', \Core\Mod\Agentic\View\Modal\Admin\Sessions::class)->name('sessions');
+ Route::get('/sessions/{id}', \Core\Mod\Agentic\View\Modal\Admin\SessionDetail::class)->name('sessions.show');
// Phase 3: Tool Analytics
- Route::get('/tools', \Core\Agentic\View\Modal\Admin\ToolAnalytics::class)->name('tools');
- Route::get('/tools/calls', \Core\Agentic\View\Modal\Admin\ToolCalls::class)->name('tools.calls');
+ Route::get('/tools', \Core\Mod\Agentic\View\Modal\Admin\ToolAnalytics::class)->name('tools');
+ Route::get('/tools/calls', \Core\Mod\Agentic\View\Modal\Admin\ToolCalls::class)->name('tools.calls');
// Phase 4: API Key Management
- Route::get('/api-keys', \Core\Agentic\View\Modal\Admin\ApiKeys::class)->name('api-keys');
+ Route::get('/api-keys', \Core\Mod\Agentic\View\Modal\Admin\ApiKeys::class)->name('api-keys');
// Phase 5: Plan Templates
- Route::get('/templates', \Core\Agentic\View\Modal\Admin\Templates::class)->name('templates');
+ Route::get('/templates', \Core\Mod\Agentic\View\Modal\Admin\Templates::class)->name('templates');
});
});
diff --git a/tests/Feature/AgentPhaseTest.php b/tests/Feature/AgentPhaseTest.php
index 70a703e..695fa69 100644
--- a/tests/Feature/AgentPhaseTest.php
+++ b/tests/Feature/AgentPhaseTest.php
@@ -2,11 +2,11 @@
declare(strict_types=1);
-namespace Core\Agentic\Tests\Feature;
+namespace Core\Mod\Agentic\Tests\Feature;
use Illuminate\Foundation\Testing\RefreshDatabase;
-use Core\Agentic\Models\AgentPhase;
-use Core\Agentic\Models\AgentPlan;
+use Core\Mod\Agentic\Models\AgentPhase;
+use Core\Mod\Agentic\Models\AgentPlan;
use Core\Mod\Tenant\Models\Workspace;
use Tests\TestCase;
diff --git a/tests/Feature/AgentPlanTest.php b/tests/Feature/AgentPlanTest.php
index 11f0cb8..e761704 100644
--- a/tests/Feature/AgentPlanTest.php
+++ b/tests/Feature/AgentPlanTest.php
@@ -2,11 +2,11 @@
declare(strict_types=1);
-namespace Core\Agentic\Tests\Feature;
+namespace Core\Mod\Agentic\Tests\Feature;
use Illuminate\Foundation\Testing\RefreshDatabase;
-use Core\Agentic\Models\AgentPhase;
-use Core\Agentic\Models\AgentPlan;
+use Core\Mod\Agentic\Models\AgentPhase;
+use Core\Mod\Agentic\Models\AgentPlan;
use Core\Mod\Tenant\Models\Workspace;
use Tests\TestCase;
diff --git a/tests/Feature/AgentSessionTest.php b/tests/Feature/AgentSessionTest.php
index 83034d6..de04589 100644
--- a/tests/Feature/AgentSessionTest.php
+++ b/tests/Feature/AgentSessionTest.php
@@ -2,11 +2,11 @@
declare(strict_types=1);
-namespace Core\Agentic\Tests\Feature;
+namespace Core\Mod\Agentic\Tests\Feature;
use Illuminate\Foundation\Testing\RefreshDatabase;
-use Core\Agentic\Models\AgentPlan;
-use Core\Agentic\Models\AgentSession;
+use Core\Mod\Agentic\Models\AgentPlan;
+use Core\Mod\Agentic\Models\AgentSession;
use Core\Mod\Tenant\Models\Workspace;
use Tests\TestCase;
diff --git a/tests/Feature/ContentServiceTest.php b/tests/Feature/ContentServiceTest.php
index b80c027..ee2e572 100644
--- a/tests/Feature/ContentServiceTest.php
+++ b/tests/Feature/ContentServiceTest.php
@@ -1,8 +1,8 @@