diff --git a/Makefile b/Makefile
index a88ba22de..13fa26ca6 100644
--- a/Makefile
+++ b/Makefile
@@ -32,10 +32,20 @@ QUIET_REDIRECT := >/dev/null 2>&1
 endif
 
 # Image tags
-FRONTEND_IMAGE ?= vteam-frontend:latest
-BACKEND_IMAGE ?= vteam-backend:latest
-OPERATOR_IMAGE ?= vteam-operator:latest
-RUNNER_IMAGE ?= vteam-claude-runner:latest
+FRONTEND_IMAGE ?= vteam_frontend:latest
+BACKEND_IMAGE ?= vteam_backend:latest
+OPERATOR_IMAGE ?= vteam_operator:latest
+RUNNER_IMAGE ?= vteam_claude_runner:latest
+
+# Build metadata (captured at build time)
+GIT_COMMIT := $(shell git rev-parse HEAD 2>/dev/null || echo "unknown")
+GIT_COMMIT_SHORT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+GIT_REPO := $(shell git remote get-url origin 2>/dev/null || echo "local")
+GIT_DIRTY := $(shell git diff --quiet 2>/dev/null || echo "-dirty")
+GIT_VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+BUILD_DATE := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
+BUILD_USER := $(shell whoami)@$(shell hostname)
 
 # Colors for output
 COLOR_RESET := \033[0m
@@ -85,22 +95,54 @@ build-all: build-frontend build-backend build-operator build-runner ## Build all
 
 build-frontend: ## Build frontend image
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Building frontend with $(CONTAINER_ENGINE)..."
-	@cd components/frontend && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) -t $(FRONTEND_IMAGE) .
+	@echo "  Git: $(GIT_BRANCH)@$(GIT_COMMIT_SHORT)$(GIT_DIRTY)"
+	@cd components/frontend && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg GIT_BRANCH=$(GIT_BRANCH) \
+		--build-arg GIT_REPO=$(GIT_REPO) \
+		--build-arg GIT_VERSION=$(GIT_VERSION)$(GIT_DIRTY) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--build-arg BUILD_USER=$(BUILD_USER) \
+		-t $(FRONTEND_IMAGE) .
 	@echo "$(COLOR_GREEN)✓$(COLOR_RESET) Frontend built: $(FRONTEND_IMAGE)"
 
 build-backend: ## Build backend image
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Building backend with $(CONTAINER_ENGINE)..."
-	@cd components/backend && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) -t $(BACKEND_IMAGE) .
+	@echo "  Git: $(GIT_BRANCH)@$(GIT_COMMIT_SHORT)$(GIT_DIRTY)"
+	@cd components/backend && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg GIT_BRANCH=$(GIT_BRANCH) \
+		--build-arg GIT_REPO=$(GIT_REPO) \
+		--build-arg GIT_VERSION=$(GIT_VERSION)$(GIT_DIRTY) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--build-arg BUILD_USER=$(BUILD_USER) \
+		-t $(BACKEND_IMAGE) .
 	@echo "$(COLOR_GREEN)✓$(COLOR_RESET) Backend built: $(BACKEND_IMAGE)"
 
 build-operator: ## Build operator image
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Building operator with $(CONTAINER_ENGINE)..."
-	@cd components/operator && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) -t $(OPERATOR_IMAGE) .
+	@echo "  Git: $(GIT_BRANCH)@$(GIT_COMMIT_SHORT)$(GIT_DIRTY)"
+	@cd components/operator && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg GIT_BRANCH=$(GIT_BRANCH) \
+		--build-arg GIT_REPO=$(GIT_REPO) \
+		--build-arg GIT_VERSION=$(GIT_VERSION)$(GIT_DIRTY) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--build-arg BUILD_USER=$(BUILD_USER) \
+		-t $(OPERATOR_IMAGE) .
 	@echo "$(COLOR_GREEN)✓$(COLOR_RESET) Operator built: $(OPERATOR_IMAGE)"
 
 build-runner: ## Build Claude Code runner image
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Building runner with $(CONTAINER_ENGINE)..."
-	@cd components/runners && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) -t $(RUNNER_IMAGE) -f claude-code-runner/Dockerfile .
+	@echo "  Git: $(GIT_BRANCH)@$(GIT_COMMIT_SHORT)$(GIT_DIRTY)"
+	@cd components/runners && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg GIT_BRANCH=$(GIT_BRANCH) \
+		--build-arg GIT_REPO=$(GIT_REPO) \
+		--build-arg GIT_VERSION=$(GIT_VERSION)$(GIT_DIRTY) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--build-arg BUILD_USER=$(BUILD_USER) \
+		-t $(RUNNER_IMAGE) -f claude-code-runner/Dockerfile .
 	@echo "$(COLOR_GREEN)✓$(COLOR_RESET) Runner built: $(RUNNER_IMAGE)"
 
 ##@ Git Hooks
@@ -236,7 +278,15 @@ local-rebuild: ## Rebuild and reload all components
 
 local-reload-backend: ## Rebuild and reload backend only
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Rebuilding backend..."
-	@cd components/backend && $(CONTAINER_ENGINE) build -t $(BACKEND_IMAGE) . >/dev/null 2>&1
+	@echo "  Git: $(GIT_BRANCH)@$(GIT_COMMIT_SHORT)$(GIT_DIRTY)"
+	@cd components/backend && $(CONTAINER_ENGINE) build -t $(BACKEND_IMAGE) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg GIT_BRANCH=$(GIT_BRANCH) \
+		--build-arg GIT_REPO=$(GIT_REPO) \
+		--build-arg GIT_VERSION=$(GIT_VERSION)$(GIT_DIRTY) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--build-arg BUILD_USER=$(BUILD_USER) \
+		. >/dev/null 2>&1
 	@$(CONTAINER_ENGINE) tag $(BACKEND_IMAGE) localhost/$(BACKEND_IMAGE) 2>/dev/null || true
 	@$(CONTAINER_ENGINE) save -o /tmp/backend-reload.tar localhost/$(BACKEND_IMAGE)
 	@minikube image load /tmp/backend-reload.tar >/dev/null 2>&1
@@ -259,7 +309,15 @@ local-reload-backend: ## Rebuild and reload backend only
 
 local-reload-frontend: ## Rebuild and reload frontend only
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Rebuilding frontend..."
-	@cd components/frontend && $(CONTAINER_ENGINE) build -t $(FRONTEND_IMAGE) . >/dev/null 2>&1
+	@echo "  Git: $(GIT_BRANCH)@$(GIT_COMMIT_SHORT)$(GIT_DIRTY)"
+	@cd components/frontend && $(CONTAINER_ENGINE) build -t $(FRONTEND_IMAGE) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg GIT_BRANCH=$(GIT_BRANCH) \
+		--build-arg GIT_REPO=$(GIT_REPO) \
+		--build-arg GIT_VERSION=$(GIT_VERSION)$(GIT_DIRTY) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--build-arg BUILD_USER=$(BUILD_USER) \
+		. >/dev/null 2>&1
 	@$(CONTAINER_ENGINE) tag $(FRONTEND_IMAGE) localhost/$(FRONTEND_IMAGE) 2>/dev/null || true
 	@$(CONTAINER_ENGINE) save -o /tmp/frontend-reload.tar localhost/$(FRONTEND_IMAGE)
 	@minikube image load /tmp/frontend-reload.tar >/dev/null 2>&1
@@ -283,7 +341,15 @@ local-reload-frontend: ## Rebuild and reload frontend only
 
 local-reload-operator: ## Rebuild and reload operator only
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Rebuilding operator..."
-	@cd components/operator && $(CONTAINER_ENGINE) build -t $(OPERATOR_IMAGE) . >/dev/null 2>&1
+	@echo "  Git: $(GIT_BRANCH)@$(GIT_COMMIT_SHORT)$(GIT_DIRTY)"
+	@cd components/operator && $(CONTAINER_ENGINE) build -t $(OPERATOR_IMAGE) \
+		--build-arg GIT_COMMIT=$(GIT_COMMIT) \
+		--build-arg GIT_BRANCH=$(GIT_BRANCH) \
+		--build-arg GIT_REPO=$(GIT_REPO) \
+		--build-arg GIT_VERSION=$(GIT_VERSION)$(GIT_DIRTY) \
+		--build-arg BUILD_DATE=$(BUILD_DATE) \
+		--build-arg BUILD_USER=$(BUILD_USER) \
+		. >/dev/null 2>&1
 	@$(CONTAINER_ENGINE) tag $(OPERATOR_IMAGE) localhost/$(OPERATOR_IMAGE) 2>/dev/null || true
 	@$(CONTAINER_ENGINE) save -o /tmp/operator-reload.tar localhost/$(OPERATOR_IMAGE)
 	@minikube image load /tmp/operator-reload.tar >/dev/null 2>&1
diff --git a/components/backend/Dockerfile b/components/backend/Dockerfile
index e186bdfb2..27966fb60 100644
--- a/components/backend/Dockerfile
+++ b/components/backend/Dockerfile
@@ -1,6 +1,14 @@
 # Build stage
 FROM registry.access.redhat.com/ubi9/go-toolset:1.24 AS builder
 
+# Build arguments for metadata
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
 WORKDIR /app
 
 USER 0
@@ -14,21 +22,52 @@ RUN go mod download
 # Copy the source code
 COPY . .
 
-# Build the application (with flags to avoid segfault)
-RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o main .
+# Build the application with embedded version info
+# The -X flag injects build-time variables into the binary
+# This ensures git metadata is baked into the binary itself, not just ENV vars
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -ldflags="-s -w \
+    -X main.GitCommit=${GIT_COMMIT} \
+    -X main.GitBranch=${GIT_BRANCH} \
+    -X main.GitVersion=${GIT_VERSION} \
+    -X main.BuildDate=${BUILD_DATE}" \
+    -o main .
 
 # Final stage
 FROM registry.access.redhat.com/ubi9/ubi-minimal:latest
 
+# Build arguments (need to redeclare for final stage)
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
+# Add labels to force cache invalidation and provide metadata
+LABEL git.commit="${GIT_COMMIT}"
+LABEL git.branch="${GIT_BRANCH}"
+LABEL git.version="${GIT_VERSION}"
+LABEL build.date="${BUILD_DATE}"
+LABEL build.user="${BUILD_USER}"
+
 RUN microdnf install -y git && microdnf clean all
 WORKDIR /app
 
-# Copy the binary from builder stage
+# Copy the binary from builder stage (binary has metadata embedded via ldflags)
 COPY --from=builder /app/main .
 
 # Default agents directory
 ENV AGENTS_DIR=/app/agents
 
+# Build metadata as environment variables (fallback, primary source is embedded in binary)
+ENV GIT_COMMIT=${GIT_COMMIT}
+ENV GIT_BRANCH=${GIT_BRANCH}
+ENV GIT_REPO=${GIT_REPO}
+ENV GIT_VERSION=${GIT_VERSION}
+ENV BUILD_DATE=${BUILD_DATE}
+ENV BUILD_USER=${BUILD_USER}
+
 # Set executable permissions and make accessible to any user
 RUN chmod +x ./main && chmod 775 /app
 
diff --git a/components/backend/go.mod b/components/backend/go.mod
index d2abbabdb..2cf62958c 100644
--- a/components/backend/go.mod
+++ b/components/backend/go.mod
@@ -10,7 +10,6 @@ require (
 	github.com/gin-gonic/gin v1.10.1
 	github.com/golang-jwt/jwt/v5 v5.3.0
 	github.com/google/uuid v1.6.0
-	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674
 	github.com/joho/godotenv v1.5.1
 	github.com/onsi/ginkgo/v2 v2.27.3
 	github.com/onsi/gomega v1.38.3
diff --git a/components/backend/go.sum b/components/backend/go.sum
index 3c35fe618..d92b7491c 100644
--- a/components/backend/go.sum
+++ b/components/backend/go.sum
@@ -116,8 +116,6 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/googleapis/enterprise-certificate-proxy v0.3.2 h1:Vie5ybvEvT75RniqhfFxPRy3Bf7vr3h0cechB90XaQs=
 github.com/googleapis/enterprise-certificate-proxy v0.3.2/go.mod h1:VLSiSSBs/ksPL8kq3OBOQ6WRI2QnaFynd1DCjZ62+V0=
-github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=
-github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
diff --git a/components/backend/handlers/sessions.go b/components/backend/handlers/sessions.go
index 111d97bb3..0e359f930 100644
--- a/components/backend/handlers/sessions.go
+++ b/components/backend/handlers/sessions.go
@@ -41,7 +41,7 @@ var (
 	DynamicClient                     dynamic.Interface
 	GetGitHubToken                    func(context.Context, kubernetes.Interface, dynamic.Interface, string, string) (string, error)
 	DeriveRepoFolderFromURL           func(string) string
-	SendMessageToSession              func(string, string, map[string]interface{})
+	// LEGACY: SendMessageToSession removed - AG-UI server uses HTTP/SSE instead of WebSocket
 )
 
 const runnerTokenRefreshedAtAnnotation = "ambient-code.io/token-refreshed-at"
@@ -2065,6 +2065,10 @@ func StartSession(c *gin.Context) {
 
 	if spec, ok := updated.Object["spec"].(map[string]interface{}); ok {
 		session.Spec = parseSpec(spec)
+
+		// NOTE: INITIAL_PROMPT auto-execution handled by runner on startup
+		// Runner POSTs to /agui/run when ready, events flow through backend
+		// This works for both UI and headless/API usage
 	}
 
 	if status, ok := updated.Object["status"].(map[string]interface{}); ok {
@@ -3898,3 +3902,7 @@ func GitListBranchesSession(c *gin.Context) {
 	}
 	c.Data(resp.StatusCode, resp.Header.Get("Content-Type"), bodyBytes)
 }
+
+// NOTE: autoTriggerInitialPrompt removed - runner handles INITIAL_PROMPT auto-execution
+// Runner POSTs to backend's /agui/run when ready, events flow through middleware
+// See: components/runners/claude-code-runner/main.py auto_execute_initial_prompt()
diff --git a/components/backend/handlers/test_helpers_test.go b/components/backend/handlers/test_helpers_test.go
index 02f70c6c0..da4c616ce 100644
--- a/components/backend/handlers/test_helpers_test.go
+++ b/components/backend/handlers/test_helpers_test.go
@@ -51,9 +51,6 @@ func SetupHandlerDependencies(k8sUtils *test_utils.K8sTestUtils) {
 		}
 		return "repo"
 	}
-	SendMessageToSession = func(sessionID, userID string, message map[string]interface{}) {
-		// no-op in unit tests
-	}
 
 	logger.Log("Handler dependencies set up with fake clients")
 }
diff --git a/components/backend/main.go b/components/backend/main.go
index d9936ae5c..ac7b4465d 100644
--- a/components/backend/main.go
+++ b/components/backend/main.go
@@ -15,11 +15,43 @@ import (
 	"github.com/joho/godotenv"
 )
 
+// Build-time metadata (set via -ldflags -X during build)
+// These are embedded directly in the binary, so they're always accurate
+var (
+	GitCommit  = "unknown"
+	GitBranch  = "unknown"
+	GitVersion = "unknown"
+	BuildDate  = "unknown"
+)
+
+func logBuildInfo() {
+	log.Println("==============================================")
+	log.Println("Backend API - Build Information")
+	log.Println("==============================================")
+	log.Printf("Version:     %s", GitVersion)
+	log.Printf("Commit:      %s", GitCommit)
+	log.Printf("Branch:      %s", GitBranch)
+	log.Printf("Repository:  %s", getEnvOrDefault("GIT_REPO", "unknown"))
+	log.Printf("Built:       %s", BuildDate)
+	log.Printf("Built by:    %s", getEnvOrDefault("BUILD_USER", "unknown"))
+	log.Println("==============================================")
+}
+
+func getEnvOrDefault(key, defaultValue string) string {
+	if value := os.Getenv(key); value != "" {
+		return value
+	}
+	return defaultValue
+}
+
 func main() {
 	// Load environment from .env in development if present
 	_ = godotenv.Overload(".env.local")
 	_ = godotenv.Overload(".env")
 
+	// Log build information
+	logBuildInfo()
+
 	// Content service mode - minimal initialization, no K8s access needed
 	if os.Getenv("CONTENT_SERVICE_MODE") == "true" {
 		log.Println("Starting in CONTENT_SERVICE_MODE (no K8s client initialization)")
@@ -94,7 +126,7 @@ func main() {
 	handlers.DynamicClient = server.DynamicClient
 	handlers.GetGitHubToken = handlers.WrapGitHubTokenForRepo(git.GetGitHubToken)
 	handlers.DeriveRepoFolderFromURL = git.DeriveRepoFolderFromURL
-	handlers.SendMessageToSession = websocket.SendMessageToSession
+	// LEGACY: SendMessageToSession removed - AG-UI server uses HTTP/SSE instead of WebSocket
 
 	// Initialize repo handlers (default implementation already set in client_selection.go)
 	// GetK8sClientsForRequestRepoFunc uses getK8sClientsForRequestRepoDefault by default
diff --git a/components/backend/routes.go b/components/backend/routes.go
index 134026c55..a0231ac39 100644
--- a/components/backend/routes.go
+++ b/components/backend/routes.go
@@ -83,10 +83,14 @@ func registerRoutes(r *gin.Engine) {
 			// OAuth integration - requires user auth like all other session endpoints
 			projectGroup.GET("/agentic-sessions/:sessionName/oauth/:provider/url", handlers.GetOAuthURL)
 
-			projectGroup.GET("/sessions/:sessionId/ws", websocket.HandleSessionWebSocket)
-			projectGroup.GET("/sessions/:sessionId/messages", websocket.GetSessionMessagesWS)
-			// Removed: /messages/claude-format - Using SDK's built-in resume with persisted ~/.claude state
-			projectGroup.POST("/sessions/:sessionId/messages", websocket.PostSessionMessageWS)
+			// AG-UI Protocol endpoints (HttpAgent-compatible)
+			// See: https://docs.ag-ui.com/quickstart/introduction
+			// Runner is a FastAPI server - backend proxies requests and streams SSE responses
+			projectGroup.POST("/agentic-sessions/:sessionName/agui/run", websocket.HandleAGUIRunProxy)
+			projectGroup.POST("/agentic-sessions/:sessionName/agui/interrupt", websocket.HandleAGUIInterrupt)
+			projectGroup.GET("/agentic-sessions/:sessionName/agui/events", websocket.HandleAGUIEvents)
+			projectGroup.GET("/agentic-sessions/:sessionName/agui/history", websocket.HandleAGUIHistory)
+			projectGroup.GET("/agentic-sessions/:sessionName/agui/runs", websocket.HandleAGUIRuns)
 
 			projectGroup.GET("/permissions", handlers.ListProjectPermissions)
 			projectGroup.POST("/permissions", handlers.AddProjectPermission)
diff --git a/components/backend/types/agui.go b/components/backend/types/agui.go
new file mode 100644
index 000000000..4cb52d801
--- /dev/null
+++ b/components/backend/types/agui.go
@@ -0,0 +1,300 @@
+// Package types defines AG-UI protocol types for event streaming.
+// Reference: https://docs.ag-ui.com/concepts/events
+package types
+
+import "time"
+
+// AG-UI Event Types as defined in the protocol specification
+// See: https://docs.ag-ui.com/concepts/events
+const (
+	// Lifecycle events
+	EventTypeRunStarted  = "RUN_STARTED"
+	EventTypeRunFinished = "RUN_FINISHED"
+	EventTypeRunError    = "RUN_ERROR"
+
+	// Step events
+	EventTypeStepStarted  = "STEP_STARTED"
+	EventTypeStepFinished = "STEP_FINISHED"
+
+	// Text message events (streaming)
+	EventTypeTextMessageStart   = "TEXT_MESSAGE_START"
+	EventTypeTextMessageContent = "TEXT_MESSAGE_CONTENT"
+	EventTypeTextMessageEnd     = "TEXT_MESSAGE_END"
+
+	// Tool call events (streaming)
+	EventTypeToolCallStart = "TOOL_CALL_START"
+	EventTypeToolCallArgs  = "TOOL_CALL_ARGS"
+	EventTypeToolCallEnd   = "TOOL_CALL_END"
+
+	// State management events
+	EventTypeStateSnapshot = "STATE_SNAPSHOT"
+	EventTypStateDelta     = "STATE_DELTA"
+
+	// Message snapshot for restore/reconnect
+	EventTypeMessagesSnapshot = "MESSAGES_SNAPSHOT"
+
+	// Activity events (frontend-only durable UI)
+	EventTypeActivitySnapshot = "ACTIVITY_SNAPSHOT"
+	EventTypeActivityDelta    = "ACTIVITY_DELTA"
+
+	// Raw event for pass-through
+	EventTypeRaw = "RAW"
+)
+
+// AG-UI Message Roles
+// See: https://docs.ag-ui.com/concepts/messages
+const (
+	RoleUser      = "user"
+	RoleAssistant = "assistant"
+	RoleSystem    = "system"
+	RoleTool      = "tool"
+	RoleDeveloper = "developer"
+	RoleActivity  = "activity"
+)
+
+// BaseEvent is the common structure for all AG-UI events
+// See: https://docs.ag-ui.com/concepts/events#baseeventproperties
+type BaseEvent struct {
+	Type      string `json:"type"`
+	ThreadID  string `json:"threadId"`
+	RunID     string `json:"runId"`
+	Timestamp string `json:"timestamp"`
+	// Optional fields
+	MessageID   string `json:"messageId,omitempty"`
+	ParentRunID string `json:"parentRunId,omitempty"`
+}
+
+// RunAgentInput is the input format for starting an AG-UI run
+// See: https://docs.ag-ui.com/quickstart/introduction
+type RunAgentInput struct {
+	ThreadID    string                 `json:"threadId,omitempty"`
+	RunID       string                 `json:"runId,omitempty"`
+	ParentRunID string                 `json:"parentRunId,omitempty"`
+	Messages    []Message              `json:"messages,omitempty"`
+	State       map[string]interface{} `json:"state,omitempty"`
+	Tools       []ToolDefinition       `json:"tools,omitempty"`
+	Context     map[string]interface{} `json:"context,omitempty"`
+}
+
+// RunAgentOutput is the response after starting a run
+type RunAgentOutput struct {
+	ThreadID    string `json:"threadId"`
+	RunID       string `json:"runId"`
+	ParentRunID string `json:"parentRunId,omitempty"`
+	StreamURL   string `json:"streamUrl,omitempty"`
+}
+
+// Message represents an AG-UI message in the conversation
+// See: https://docs.ag-ui.com/concepts/messages
+type Message struct {
+	ID         string      `json:"id"`
+	Role       string      `json:"role"`
+	Content    string      `json:"content,omitempty"`
+	ToolCalls  []ToolCall  `json:"toolCalls,omitempty"`
+	ToolCallID string      `json:"toolCallId,omitempty"`
+	Name       string      `json:"name,omitempty"`
+	Timestamp  string      `json:"timestamp,omitempty"`
+	Metadata   interface{} `json:"metadata,omitempty"`
+}
+
+// ToolCall represents a tool call made by the assistant
+type ToolCall struct {
+	ID              string `json:"id"`
+	Name            string `json:"name"`
+	Args            string `json:"args"`
+	Type            string `json:"type,omitempty"`            // "function"
+	ParentToolUseID string `json:"parentToolUseId,omitempty"` // For hierarchical nesting
+	Result          string `json:"result,omitempty"`
+	Status          string `json:"status,omitempty"` // "pending", "running", "completed", "error"
+	Error           string `json:"error,omitempty"`
+	Duration        int64  `json:"duration,omitempty"` // milliseconds
+}
+
+// ToolDefinition describes an available tool
+type ToolDefinition struct {
+	Name        string                 `json:"name"`
+	Description string                 `json:"description,omitempty"`
+	Parameters  map[string]interface{} `json:"parameters,omitempty"`
+}
+
+// RunStartedEvent is emitted when a run begins
+type RunStartedEvent struct {
+	BaseEvent
+	Input *RunAgentInput `json:"input,omitempty"`
+}
+
+// RunFinishedEvent is emitted when a run completes successfully
+type RunFinishedEvent struct {
+	BaseEvent
+	Output interface{} `json:"output,omitempty"`
+}
+
+// RunErrorEvent is emitted when a run fails
+type RunErrorEvent struct {
+	BaseEvent
+	Error   string `json:"error"`
+	Code    string `json:"code,omitempty"`
+	Details string `json:"details,omitempty"`
+}
+
+// StepStartedEvent marks the beginning of a processing step
+type StepStartedEvent struct {
+	BaseEvent
+	StepID   string `json:"stepId"`
+	StepName string `json:"stepName"`
+}
+
+// StepFinishedEvent marks the completion of a processing step
+type StepFinishedEvent struct {
+	BaseEvent
+	StepID   string `json:"stepId"`
+	StepName string `json:"stepName"`
+	Duration int64  `json:"duration,omitempty"` // milliseconds
+}
+
+// TextMessageStartEvent begins a streaming text message
+type TextMessageStartEvent struct {
+	BaseEvent
+	Role string `json:"role"`
+}
+
+// TextMessageContentEvent contains a chunk of text content
+type TextMessageContentEvent struct {
+	BaseEvent
+	Delta string `json:"delta"`
+}
+
+// TextMessageEndEvent marks the end of a streaming text message
+type TextMessageEndEvent struct {
+	BaseEvent
+}
+
+// ToolCallStartEvent begins a streaming tool call
+type ToolCallStartEvent struct {
+	BaseEvent
+	ToolCallID      string `json:"toolCallId"`
+	ToolCallName    string `json:"toolCallName"`
+	ParentMessageID string `json:"parentMessageId,omitempty"`
+	ParentToolUseID string `json:"parentToolUseId,omitempty"`
+}
+
+// ToolCallArgsEvent contains a chunk of tool call arguments
+type ToolCallArgsEvent struct {
+	BaseEvent
+	ToolCallID string `json:"toolCallId"`
+	Delta      string `json:"delta"`
+}
+
+// ToolCallEndEvent marks the end of a streaming tool call
+type ToolCallEndEvent struct {
+	BaseEvent
+	ToolCallID string `json:"toolCallId"`
+	Result     string `json:"result,omitempty"`
+	Error      string `json:"error,omitempty"`
+	Duration   int64  `json:"duration,omitempty"` // milliseconds
+}
+
+// StateSnapshotEvent provides complete state for hydration
+type StateSnapshotEvent struct {
+	BaseEvent
+	State map[string]interface{} `json:"state"`
+}
+
+// StateDeltaEvent provides incremental state updates
+type StateDeltaEvent struct {
+	BaseEvent
+	Delta []StatePatch `json:"delta"`
+}
+
+// StatePatch represents a JSON Patch operation for state updates
+type StatePatch struct {
+	Op    string      `json:"op"`   // "add", "remove", "replace"
+	Path  string      `json:"path"` // JSON Pointer
+	Value interface{} `json:"value,omitempty"`
+}
+
+// MessagesSnapshotEvent provides complete message history for hydration
+type MessagesSnapshotEvent struct {
+	BaseEvent
+	Messages []Message `json:"messages"`
+}
+
+// ActivitySnapshotEvent provides complete activity UI state
+type ActivitySnapshotEvent struct {
+	BaseEvent
+	Activities []Activity `json:"activities"`
+}
+
+// ActivityDeltaEvent provides incremental activity updates
+type ActivityDeltaEvent struct {
+	BaseEvent
+	Delta []ActivityPatch `json:"delta"`
+}
+
+// Activity represents a durable frontend UI element
+type Activity struct {
+	ID       string                 `json:"id"`
+	Type     string                 `json:"type"`
+	Title    string                 `json:"title,omitempty"`
+	Status   string                 `json:"status,omitempty"` // "pending", "running", "completed", "error"
+	Progress float64                `json:"progress,omitempty"`
+	Data     map[string]interface{} `json:"data,omitempty"`
+}
+
+// ActivityPatch represents an update to an activity
+type ActivityPatch struct {
+	Op       string   `json:"op"` // "add", "update", "remove"
+	Activity Activity `json:"activity"`
+}
+
+// RawEvent allows pass-through of arbitrary data
+type RawEvent struct {
+	BaseEvent
+	Data interface{} `json:"data"`
+}
+
+// NewBaseEvent creates a new BaseEvent with current timestamp
+func NewBaseEvent(eventType, threadID, runID string) BaseEvent {
+	return BaseEvent{
+		Type:      eventType,
+		ThreadID:  threadID,
+		RunID:     runID,
+		Timestamp: time.Now().UTC().Format(time.RFC3339Nano),
+	}
+}
+
+// WithMessageID adds a message ID to the event
+func (e BaseEvent) WithMessageID(messageID string) BaseEvent {
+	e.MessageID = messageID
+	return e
+}
+
+// WithParentRunID adds a parent run ID to the event
+func (e BaseEvent) WithParentRunID(parentRunID string) BaseEvent {
+	e.ParentRunID = parentRunID
+	return e
+}
+
+// AGUIEventLog represents the persisted event log structure
+type AGUIEventLog struct {
+	ThreadID    string      `json:"threadId"`
+	RunID       string      `json:"runId"`
+	ParentRunID string      `json:"parentRunId,omitempty"`
+	Events      []BaseEvent `json:"events"`
+	CreatedAt   string      `json:"createdAt"`
+	UpdatedAt   string      `json:"updatedAt"`
+}
+
+// AGUIRunMetadata contains metadata about a run for indexing
+type AGUIRunMetadata struct {
+	ThreadID     string `json:"threadId"`
+	RunID        string `json:"runId"`
+	ParentRunID  string `json:"parentRunId,omitempty"`
+	SessionName  string `json:"sessionName"`
+	ProjectName  string `json:"projectName"`
+	StartedAt    string `json:"startedAt"`
+	FinishedAt   string `json:"finishedAt,omitempty"`
+	Status       string `json:"status"` // "running", "completed", "error"
+	EventCount   int    `json:"eventCount"`
+	RestartCount int    `json:"restartCount,omitempty"`
+}
diff --git a/components/backend/websocket/agui.go b/components/backend/websocket/agui.go
new file mode 100644
index 000000000..ce505e169
--- /dev/null
+++ b/components/backend/websocket/agui.go
@@ -0,0 +1,1048 @@
+// Package websocket provides AG-UI protocol endpoints for event streaming.
+// See: https://docs.ag-ui.com/quickstart/introduction
+package websocket
+
+import (
+	"ambient-code-backend/handlers"
+	"ambient-code-backend/types"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	authv1 "k8s.io/api/authorization/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// AG-UI run state tracking and storage
+var (
+	StateBaseDir string // Base directory for session state persistence (moved from hub.go)
+
+	aguiRuns   = make(map[string]*AGUIRunState) // runID -> state
+	aguiRunsMu sync.RWMutex
+
+	// Thread-level subscribers: sessionID -> channels for ALL runs in thread
+	threadSubscribers   = make(map[string]map[chan interface{}]bool)
+	threadSubscribersMu sync.RWMutex
+)
+
+// AGUIRunState tracks the state of an AG-UI run
+type AGUIRunState struct {
+	ThreadID     string
+	RunID        string
+	ParentRunID  string
+	SessionID    string // maps to our sessionName
+	ProjectName  string
+	Status       string // "running", "completed", "error"
+	StartedAt    time.Time
+	subscribers  map[chan *types.BaseEvent]bool
+	fullEventSub map[chan interface{}]bool // For full events with all fields
+	subscriberMu sync.RWMutex
+}
+
+// Subscribe adds a subscriber to this run's events
+func (r *AGUIRunState) Subscribe() chan *types.BaseEvent {
+	ch := make(chan *types.BaseEvent, 100)
+	r.subscriberMu.Lock()
+	r.subscribers[ch] = true
+	r.subscriberMu.Unlock()
+	return ch
+}
+
+// Unsubscribe removes a subscriber from this run's events
+func (r *AGUIRunState) Unsubscribe(ch chan *types.BaseEvent) {
+	r.subscriberMu.Lock()
+	delete(r.subscribers, ch)
+	close(ch)
+	r.subscriberMu.Unlock()
+}
+
+// Broadcast sends an event to all subscribers
+func (r *AGUIRunState) Broadcast(event *types.BaseEvent) {
+	r.subscriberMu.RLock()
+	defer r.subscriberMu.RUnlock()
+	for ch := range r.subscribers {
+		select {
+		case ch <- event:
+		default:
+			// Channel full, skip
+		}
+	}
+}
+
+// BroadcastFull broadcasts full event with all fields (not just BaseEvent)
+func (r *AGUIRunState) BroadcastFull(event interface{}) {
+	r.subscriberMu.RLock()
+	defer r.subscriberMu.RUnlock()
+
+	// Send to full event subscribers
+	for ch := range r.fullEventSub {
+		select {
+		case ch <- event:
+		default:
+			// Channel full, skip
+		}
+	}
+
+	// Also send BaseEvent to legacy subscribers
+	if baseEvent, ok := extractBaseEvent(event); ok {
+		for ch := range r.subscribers {
+			select {
+			case ch <- baseEvent:
+			default:
+				// Channel full, skip
+			}
+		}
+	}
+}
+
+// RouteAGUIEvent routes an AG-UI event directly from WebSocket to subscribers
+// This is the simplified flow - no SessionMessage wrapping, no translation needed
+func RouteAGUIEvent(sessionID string, event map[string]interface{}) {
+	eventType, ok := event["type"].(string)
+	if !ok {
+		log.Printf("AGUI: Event missing type field, skipping")
+		return
+	}
+
+	// Find active run for this session
+	var activeRunState *AGUIRunState
+	aguiRunsMu.RLock()
+	for _, state := range aguiRuns {
+		if state.SessionID == sessionID && state.Status == "running" {
+			activeRunState = state
+			break
+		}
+	}
+	aguiRunsMu.RUnlock()
+
+	// If no active run found, check if event has a runId we should create
+	if activeRunState == nil {
+		// Don't create lazy runs for terminal events - they should only apply to existing runs
+		if isTerminalEventType(eventType) {
+			go persistAGUIEventMap(sessionID, "", event)
+			return
+		}
+
+		eventRunID, ok := event["runId"].(string)
+		if ok && eventRunID != "" {
+			// Create run lazily from event's runId
+			threadID := sessionID
+			activeRunState = &AGUIRunState{
+				ThreadID:     threadID,
+				RunID:        eventRunID,
+				SessionID:    sessionID,
+				Status:       "running",
+				StartedAt:    time.Now(),
+				subscribers:  make(map[chan *types.BaseEvent]bool),
+				fullEventSub: make(map[chan interface{}]bool),
+			}
+			aguiRunsMu.Lock()
+			aguiRuns[eventRunID] = activeRunState
+			aguiRunsMu.Unlock()
+		} else {
+			go persistAGUIEventMap(sessionID, "", event)
+			return
+		}
+	}
+
+	threadID := activeRunState.ThreadID
+	runID := activeRunState.RunID
+
+	// CRITICAL: Use runId from event if present (event is source of truth)
+	// Don't use activeRunState.RunID which might be stale
+	if eventRunID, ok := event["runId"].(string); ok && eventRunID != "" {
+		runID = eventRunID
+	}
+	if eventThreadID, ok := event["threadId"].(string); ok && eventThreadID != "" {
+		threadID = eventThreadID
+	}
+
+	// Fill in missing IDs only if not present
+	if event["threadId"] == nil || event["threadId"] == "" {
+		event["threadId"] = threadID
+	}
+	if event["runId"] == nil || event["runId"] == "" {
+		event["runId"] = runID
+	}
+
+	// Broadcast to run-specific SSE subscribers
+	activeRunState.BroadcastFull(event)
+
+	// Also broadcast to thread-level subscribers (clients watching entire session)
+	threadSubscribersMu.RLock()
+	if subscribers, exists := threadSubscribers[sessionID]; exists {
+		for ch := range subscribers {
+			select {
+			case ch <- event:
+			default:
+			}
+		}
+	}
+	threadSubscribersMu.RUnlock()
+
+	// Persist the event (use runID from event, not activeRunState)
+	go persistAGUIEventMap(sessionID, runID, event)
+
+	// Check for terminal events - mark run as complete
+	if isTerminalEventType(eventType) {
+		activeRunState.Status = getTerminalStatusFromType(eventType)
+
+		// Schedule cleanup of run state (no need to compact async - we compact on SSE connect)
+		go scheduleRunCleanup(runID, 5*time.Minute)
+	}
+}
+
+// loadCompactedMessages loads pre-compacted messages from completed runs
+// NOTE: Removed loadCompactedMessages and compactAndPersistRun functions.
+// We now use "compact-on-read" strategy in streamThreadEvents.
+// This eliminates race conditions, dual-file complexity, and async compaction issues.
+
+// persistAGUIEventMap persists a map[string]interface{} event to disk
+func persistAGUIEventMap(sessionID, runID string, event map[string]interface{}) {
+	path := fmt.Sprintf("%s/sessions/%s/agui-events.jsonl", StateBaseDir, sessionID)
+	_ = ensureDir(fmt.Sprintf("%s/sessions/%s", StateBaseDir, sessionID))
+
+	data, err := json.Marshal(event)
+	if err != nil {
+		log.Printf("AGUI: failed to marshal event for persistence: %v", err)
+		return
+	}
+
+	f, err := openFileAppend(path)
+	if err != nil {
+		log.Printf("AGUI: failed to open event log: %v", err)
+		return
+	}
+	defer f.Close()
+
+	if _, err := f.Write(append(data, '\n')); err != nil {
+		log.Printf("AGUI: failed to write event: %v", err)
+		return
+	}
+
+}
+
+// isTerminalEventType checks if an event type indicates run completion
+func isTerminalEventType(eventType string) bool {
+	switch eventType {
+	case types.EventTypeRunFinished, types.EventTypeRunError:
+		return true
+	}
+	return false
+}
+
+// getTerminalStatusFromType returns the run status for a terminal event type
+func getTerminalStatusFromType(eventType string) string {
+	switch eventType {
+	case types.EventTypeRunFinished:
+		return "completed"
+	case types.EventTypeRunError:
+		return "error"
+	default:
+		return "completed"
+	}
+}
+
+// extractBaseEvent extracts the BaseEvent from any AG-UI event type
+func extractBaseEvent(event interface{}) (*types.BaseEvent, bool) {
+	switch e := event.(type) {
+	case *types.BaseEvent:
+		return e, true
+	case *types.TextMessageStartEvent:
+		return &e.BaseEvent, true
+	case *types.TextMessageContentEvent:
+		return &e.BaseEvent, true
+	case *types.TextMessageEndEvent:
+		return &e.BaseEvent, true
+	case *types.ToolCallStartEvent:
+		return &e.BaseEvent, true
+	case *types.ToolCallArgsEvent:
+		return &e.BaseEvent, true
+	case *types.ToolCallEndEvent:
+		return &e.BaseEvent, true
+	case *types.StepStartedEvent:
+		return &e.BaseEvent, true
+	case *types.StepFinishedEvent:
+		return &e.BaseEvent, true
+	case *types.RunStartedEvent:
+		return &e.BaseEvent, true
+	case *types.RunFinishedEvent:
+		return &e.BaseEvent, true
+	case *types.RunErrorEvent:
+		return &e.BaseEvent, true
+	case *types.StateSnapshotEvent:
+		return &e.BaseEvent, true
+	case *types.StateDeltaEvent:
+		return &e.BaseEvent, true
+	case *types.MessagesSnapshotEvent:
+		return &e.BaseEvent, true
+	case *types.ActivitySnapshotEvent:
+		return &e.BaseEvent, true
+	case *types.ActivityDeltaEvent:
+		return &e.BaseEvent, true
+	case *types.RawEvent:
+		return &e.BaseEvent, true
+	default:
+		return nil, false
+	}
+}
+
+// LEGACY: Old HandleAGUIRun function removed - replaced by HandleAGUIRunProxy
+// The new proxy forwards requests to the runner's FastAPI server instead of using WebSocket
+
+// streamThreadEvents streams events from ALL runs in a thread (session)
+// This is the correct AG-UI pattern: client connects to thread, not individual runs
+func streamThreadEvents(c *gin.Context, projectName, sessionName string) {
+	threadID := sessionName
+	eventCh := make(chan interface{}, 100)
+	ctx := c.Request.Context()
+
+	// Subscribe to all current and future runs for this session
+	threadSubscribersMu.Lock()
+	if threadSubscribers[sessionName] == nil {
+		threadSubscribers[sessionName] = make(map[chan interface{}]bool)
+	}
+	threadSubscribers[sessionName][eventCh] = true
+	threadSubscribersMu.Unlock()
+
+	defer func() {
+		threadSubscribersMu.Lock()
+		delete(threadSubscribers[sessionName], eventCh)
+		if len(threadSubscribers[sessionName]) == 0 {
+			delete(threadSubscribers, sessionName)
+		}
+		threadSubscribersMu.Unlock()
+		close(eventCh)
+	}()
+
+	// OPTION 1: Compact-on-Read Strategy (COMPLETED RUNS ONLY)
+	// Load events from agui-events.jsonl and compact only COMPLETED runs
+	// Active/in-progress runs will be streamed raw
+
+	// Declare outside so it's accessible later for replaying active runs
+	activeRunIDs := make(map[string]bool)
+
+	events, err := loadEventsForRun(sessionName, "")
+	if err == nil && len(events) > 0 {
+
+		// CRITICAL FIX: Determine which runs are TRULY active by checking event log
+		// A run is only active if NO terminal event exists in the log
+		runHasTerminalEvent := make(map[string]bool)
+		for _, event := range events {
+			eventRunID, ok := event["runId"].(string)
+			if !ok {
+				continue
+			}
+			eventType, ok := event["type"].(string)
+			if !ok {
+				continue
+			}
+
+			if eventRunID != "" && isTerminalEventType(eventType) {
+				runHasTerminalEvent[eventRunID] = true
+			}
+		}
+
+		// Check in-memory state and override with event log truth
+		// Also fix stale in-memory state
+		aguiRunsMu.Lock()
+		for _, state := range aguiRuns {
+			if state.SessionID == sessionName {
+				runID := state.RunID
+				// Only consider active if NO terminal event in log
+				if !runHasTerminalEvent[runID] {
+					activeRunIDs[runID] = true
+				} else {
+					// Fix stale memory state
+					if state.Status == "running" {
+						state.Status = "completed"
+					}
+				}
+			}
+		}
+		aguiRunsMu.Unlock()
+
+		// Filter to only events from COMPLETED runs (have terminal event)
+		completedEvents := make([]map[string]interface{}, 0)
+		skippedCount := 0
+		for _, event := range events {
+			eventRunID, ok := event["runId"].(string)
+			if !ok {
+				continue
+			}
+
+			// Skip events without runId
+			if eventRunID == "" {
+				skippedCount++
+				continue
+			}
+
+			// Skip events from active runs (no terminal event yet)
+			if activeRunIDs[eventRunID] {
+				skippedCount++
+				continue
+			}
+
+			// Include events from completed runs
+			completedEvents = append(completedEvents, event)
+		}
+
+		if len(completedEvents) > 0 {
+			// Compact only completed run events
+			messages := CompactEvents(completedEvents)
+
+			// Send single MESSAGES_SNAPSHOT with compacted messages from COMPLETED runs
+			if len(messages) > 0 {
+				snapshot := &types.MessagesSnapshotEvent{
+					BaseEvent: types.NewBaseEvent(types.EventTypeMessagesSnapshot, threadID, "thread-snapshot"),
+					Messages:  messages,
+				}
+				writeSSEEvent(c.Writer, snapshot)
+				c.Writer.(http.Flusher).Flush()
+			}
+		}
+	} else if err != nil {
+		log.Printf("AGUI: Failed to load events: %v", err)
+	}
+
+	// Replay ALL active runs (not just most recent)
+	// CRITICAL: This ensures all non-compacted events are sent to client
+	aguiRunsMu.RLock()
+	activeRunStates := make([]*AGUIRunState, 0)
+	for _, state := range aguiRuns {
+		if state.SessionID == sessionName && activeRunIDs[state.RunID] {
+			activeRunStates = append(activeRunStates, state)
+		}
+	}
+	aguiRunsMu.RUnlock()
+
+	if len(activeRunStates) > 0 {
+
+		// Load all events once
+		allEvents, err := loadEventsForRun(sessionName, "")
+		if err == nil {
+			for _, activeRunState := range activeRunStates {
+				// Send RUN_STARTED for this active run
+				runStarted := &types.RunStartedEvent{
+					BaseEvent: types.NewBaseEvent(types.EventTypeRunStarted, threadID, activeRunState.RunID),
+				}
+				if activeRunState.ParentRunID != "" {
+					runStarted.ParentRunID = activeRunState.ParentRunID
+				}
+				writeSSEEvent(c.Writer, runStarted)
+
+				// Send state snapshot
+				sendBasicStateSnapshot(c, activeRunState, projectName, sessionName)
+
+				// Collect events for this run
+				runEvents := make([]map[string]interface{}, 0)
+				for _, event := range allEvents {
+					eventRunID, ok := event["runId"].(string)
+					if ok && eventRunID == activeRunState.RunID {
+						runEvents = append(runEvents, event)
+					}
+				}
+
+				// Replay raw events
+				if len(runEvents) > 0 {
+					for _, event := range runEvents {
+						writeSSEEvent(c.Writer, event)
+					}
+				}
+			}
+			c.Writer.(http.Flusher).Flush()
+		}
+	}
+
+	// Stream events from all future runs with keepalive
+	keepaliveTicker := time.NewTicker(15 * time.Second)
+	defer keepaliveTicker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-keepaliveTicker.C:
+			// Send SSE comment to prevent gateway timeout
+			_, err := c.Writer.Write([]byte(": keepalive\n\n"))
+			if err != nil {
+				log.Printf("AGUI: Keepalive write failed, closing stream: %v", err)
+				return
+			}
+			c.Writer.(http.Flusher).Flush()
+		case event, ok := <-eventCh:
+			if !ok {
+				return
+			}
+			writeSSEEvent(c.Writer, event)
+			c.Writer.(http.Flusher).Flush()
+		}
+	}
+}
+
+// HandleAGUIEvents handles GET /api/projects/:projectName/agentic-sessions/:sessionName/agui/events
+// This is the AG-UI SSE stream endpoint
+// See: https://docs.ag-ui.com/quickstart/middleware
+func HandleAGUIEvents(c *gin.Context) {
+	projectName := c.Param("projectName")
+	sessionName := c.Param("sessionName")
+	runID := c.Query("runId")
+
+	// SECURITY: Authenticate user and get user-scoped K8s client
+	reqK8s, _ := handlers.GetK8sClientsForRequest(c)
+	if reqK8s == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid or missing token"})
+		c.Abort()
+		return
+	}
+
+	// SECURITY: Verify user has permission to read this session
+	ctx := context.Background()
+	ssar := &authv1.SelfSubjectAccessReview{
+		Spec: authv1.SelfSubjectAccessReviewSpec{
+			ResourceAttributes: &authv1.ResourceAttributes{
+				Group:     "vteam.ambient-code",
+				Resource:  "agenticsessions",
+				Verb:      "get",
+				Namespace: projectName,
+				Name:      sessionName,
+			},
+		},
+	}
+	res, err := reqK8s.AuthorizationV1().SelfSubjectAccessReviews().Create(ctx, ssar, metav1.CreateOptions{})
+	if err != nil || !res.Status.Allowed {
+		log.Printf("AGUI Events: User not authorized to read session %s/%s", projectName, sessionName)
+		c.JSON(http.StatusForbidden, gin.H{"error": "Unauthorized"})
+		c.Abort()
+		return
+	}
+
+	// Set SSE headers
+	c.Header("Content-Type", "text/event-stream")
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+	c.Header("X-Accel-Buffering", "no")
+
+	// If no runId specified, stream the entire THREAD (all runs for this session)
+	// This is the correct AG-UI pattern: client connects once to thread stream
+	if runID == "" {
+		streamThreadEvents(c, projectName, sessionName)
+		return
+	}
+
+	// Legacy: specific run streaming (kept for compatibility)
+
+	var runState *AGUIRunState
+	aguiRunsMu.RLock()
+	runState = aguiRuns[runID]
+	aguiRunsMu.RUnlock()
+
+	if runState == nil {
+		// Create an implicit run for this connection
+		threadID := sessionName
+		runState = &AGUIRunState{
+			ThreadID:     threadID,
+			RunID:        runID,
+			SessionID:    sessionName,
+			ProjectName:  projectName,
+			Status:       "running",
+			StartedAt:    time.Now(),
+			subscribers:  make(map[chan *types.BaseEvent]bool),
+			fullEventSub: make(map[chan interface{}]bool),
+		}
+		aguiRunsMu.Lock()
+		aguiRuns[runID] = runState
+		aguiRunsMu.Unlock()
+	}
+
+	// Subscribe to full events (includes Delta, ToolCallID, etc.)
+	fullEventCh := make(chan interface{}, 100)
+	runState.subscriberMu.Lock()
+	runState.fullEventSub[fullEventCh] = true
+	runState.subscriberMu.Unlock()
+	defer func() {
+		runState.subscriberMu.Lock()
+		delete(runState.fullEventSub, fullEventCh)
+		runState.subscriberMu.Unlock()
+		close(fullEventCh)
+	}()
+
+	// Send initial sync events (with panic recovery)
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				log.Printf("AGUI: panic in sendInitialSyncEvents: %v", r)
+			}
+		}()
+		sendInitialSyncEvents(c, runState, projectName, sessionName)
+	}()
+
+	// Create context for client disconnection
+	streamCtx := c.Request.Context()
+
+	// Stream events
+	for {
+		select {
+		case <-streamCtx.Done():
+			return
+		case event, ok := <-fullEventCh:
+			if !ok {
+				return
+			}
+			writeSSEEvent(c.Writer, event)
+			c.Writer.(http.Flusher).Flush()
+		}
+	}
+}
+
+// sendInitialSyncEvents sends snapshot events on connection/reconnection
+// This implements the reconnect/restore strategy per AG-UI serialization guidance
+func sendInitialSyncEvents(c *gin.Context, runState *AGUIRunState, projectName, sessionName string) {
+	threadID := runState.ThreadID
+	runID := runState.RunID
+
+	// 1. Send RUN_STARTED
+	runStarted := &types.RunStartedEvent{
+		BaseEvent: types.NewBaseEvent(types.EventTypeRunStarted, threadID, runID),
+	}
+	if runState.ParentRunID != "" {
+		runStarted.ParentRunID = runState.ParentRunID
+	}
+	writeSSEEvent(c.Writer, runStarted)
+
+	// 2. Send basic state snapshot (always succeeds)
+	sendBasicStateSnapshot(c, runState, projectName, sessionName)
+
+	// 3. Compact stored events and send MESSAGES_SNAPSHOT
+	// Per AG-UI spec: compact at read-time, not write-time
+	events, err := loadEventsForRun(sessionName, runID)
+	if err != nil {
+		log.Printf("AGUI: Failed to load events for %s: %v", sessionName, err)
+	}
+
+	if len(events) > 0 {
+		messages := CompactEvents(events)
+
+		if len(messages) > 0 {
+			snapshot := &types.MessagesSnapshotEvent{
+				BaseEvent: types.NewBaseEvent(types.EventTypeMessagesSnapshot, threadID, runID),
+				Messages:  messages,
+			}
+			writeSSEEvent(c.Writer, snapshot)
+		}
+	}
+}
+
+// sendBasicStateSnapshot sends a basic state snapshot with session metadata
+func sendBasicStateSnapshot(c *gin.Context, runState *AGUIRunState, projectName, sessionName string) {
+	threadID := runState.ThreadID
+	runID := runState.RunID
+
+	stateSnapshot := &types.StateSnapshotEvent{
+		BaseEvent: types.NewBaseEvent(types.EventTypeStateSnapshot, threadID, runID),
+		State: map[string]interface{}{
+			"sessionName": sessionName,
+			"projectName": projectName,
+			"status":      runState.Status,
+		},
+	}
+
+	// Enrich with session data if available
+	sessionData, err := getSessionState(projectName, sessionName)
+	if err == nil && sessionData != nil {
+		for k, v := range sessionData {
+			stateSnapshot.State[k] = v
+		}
+	}
+	writeSSEEvent(c.Writer, stateSnapshot)
+}
+
+// writeSSEEvent writes an event in SSE format
+func writeSSEEvent(w http.ResponseWriter, event interface{}) {
+	data, err := json.Marshal(event)
+	if err != nil {
+		log.Printf("AGUI: failed to marshal event: %v", err)
+		return
+	}
+
+	fmt.Fprintf(w, "data: %s\n\n", data)
+	if f, ok := w.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+
+// scheduleRunCleanup removes a run from the active runs map after a delay
+func scheduleRunCleanup(runID string, delay time.Duration) {
+	time.Sleep(delay)
+	aguiRunsMu.Lock()
+	if run, ok := aguiRuns[runID]; ok {
+		// Only delete if run is no longer active
+		if run.Status != "running" {
+			delete(aguiRuns, runID)
+		}
+	}
+	aguiRunsMu.Unlock()
+}
+
+// cleanupOldRuns periodically cleans up old inactive runs
+func init() {
+	go func() {
+		ticker := time.NewTicker(10 * time.Minute)
+		for range ticker.C {
+			cleanupInactiveRuns()
+		}
+	}()
+}
+
+func cleanupInactiveRuns() {
+	cutoff := time.Now().Add(-30 * time.Minute)
+	aguiRunsMu.Lock()
+	defer aguiRunsMu.Unlock()
+	for runID, run := range aguiRuns {
+		if run.Status != "running" && run.StartedAt.Before(cutoff) {
+			delete(aguiRuns, runID)
+		}
+	}
+}
+
+// Legacy translation functions removed - AG-UI events now route directly via RouteAGUIEvent
+
+// Helper functions for state and message retrieval
+
+func getSessionState(projectName, sessionName string) (map[string]interface{}, error) {
+	// Get session from K8s and extract relevant state
+	if handlers.DynamicClient == nil {
+		// Return basic state if K8s client not available
+		return map[string]interface{}{
+			"phase":       "Unknown",
+			"interactive": true,
+		}, nil
+	}
+
+	gvr := handlers.GetAgenticSessionV1Alpha1Resource()
+	item, err := handlers.DynamicClient.Resource(gvr).Namespace(projectName).Get(
+		context.Background(), sessionName, metav1.GetOptions{},
+	)
+	if err != nil {
+		log.Printf("AGUI: failed to get session state: %v", err)
+		return map[string]interface{}{
+			"phase":       "Unknown",
+			"interactive": true,
+		}, nil
+	}
+
+	state := make(map[string]interface{})
+
+	// Extract spec fields
+	if spec, ok := item.Object["spec"].(map[string]interface{}); ok {
+		if interactive, ok := spec["interactive"].(bool); ok {
+			state["interactive"] = interactive
+		}
+		if displayName, ok := spec["displayName"].(string); ok {
+			state["displayName"] = displayName
+		}
+		if repos, ok := spec["repos"].([]interface{}); ok {
+			state["repos"] = repos
+		}
+		if workflow, ok := spec["activeWorkflow"].(map[string]interface{}); ok {
+			state["activeWorkflow"] = workflow
+		}
+	}
+
+	// Extract status fields
+	if status, ok := item.Object["status"].(map[string]interface{}); ok {
+		if phase, ok := status["phase"].(string); ok {
+			state["phase"] = phase
+		}
+		if sdkSessionID, ok := status["sdkSessionId"].(string); ok {
+			state["sdkSessionId"] = sdkSessionID
+		}
+		if restartCount, ok := status["sdkRestartCount"].(int64); ok {
+			state["sdkRestartCount"] = restartCount
+		} else if restartCount, ok := status["sdkRestartCount"].(float64); ok {
+			state["sdkRestartCount"] = int(restartCount)
+		}
+		if reconciledRepos, ok := status["reconciledRepos"].([]interface{}); ok {
+			state["reconciledRepos"] = reconciledRepos
+		}
+	}
+
+	return state, nil
+}
+
+// AG-UI event persistence
+// Implements append-only event log per AG-UI serialization guidance:
+// https://docs.ag-ui.com/concepts/serialization#serialization
+
+// persistRunMetadata saves run metadata for indexing
+func persistRunMetadata(sessionID string, meta types.AGUIRunMetadata) {
+	path := fmt.Sprintf("%s/sessions/%s/agui-runs.jsonl", StateBaseDir, sessionID)
+
+	_ = ensureDir(fmt.Sprintf("%s/sessions/%s", StateBaseDir, sessionID))
+
+	data, err := json.Marshal(meta)
+	if err != nil {
+		log.Printf("AGUI: failed to marshal run metadata: %v", err)
+		return
+	}
+
+	f, err := openFileAppend(path)
+	if err != nil {
+		log.Printf("AGUI: failed to open runs index: %v", err)
+		return
+	}
+	defer f.Close()
+
+	if _, err := f.Write(append(data, '\n')); err != nil {
+		log.Printf("AGUI: failed to write run metadata: %v", err)
+	}
+}
+
+// loadRunsFromDisk loads persisted run metadata from disk
+func loadRunsFromDisk(sessionID string) []types.AGUIRunMetadata {
+	path := fmt.Sprintf("%s/sessions/%s/agui-runs.jsonl", StateBaseDir, sessionID)
+	runs := make([]types.AGUIRunMetadata, 0)
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			log.Printf("AGUI: failed to read runs index: %v", err)
+		}
+		return runs
+	}
+
+	lines := splitLines(data)
+	for _, line := range lines {
+		if len(line) == 0 {
+			continue
+		}
+		var meta types.AGUIRunMetadata
+		if err := json.Unmarshal(line, &meta); err == nil {
+			runs = append(runs, meta)
+		}
+	}
+
+	return runs
+}
+
+// loadEventsForRun loads all events for a session (thread) from disk
+// Per AG-UI spec: all runs in a thread share the same event log
+// Includes automatic migration from legacy message format
+func loadEventsForRun(sessionID, runID string) ([]map[string]interface{}, error) {
+	path := fmt.Sprintf("%s/sessions/%s/agui-events.jsonl", StateBaseDir, sessionID)
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// Check if legacy messages.json exists and migrate
+			if err := MigrateLegacySessionToAGUI(sessionID); err != nil {
+				log.Printf("LegacyMigration: Failed to migrate session %s: %v", sessionID, err)
+			} else {
+				// Try reading again after migration
+				data, err = os.ReadFile(path)
+				if err != nil {
+					return []map[string]interface{}{}, nil
+				}
+			}
+			if len(data) == 0 {
+				return []map[string]interface{}{}, nil
+			}
+		} else {
+			return nil, err
+		}
+	}
+
+	events := make([]map[string]interface{}, 0)
+	lines := splitLines(data)
+	for _, line := range lines {
+		if len(line) == 0 {
+			continue
+		}
+		var event map[string]interface{}
+		if err := json.Unmarshal(line, &event); err == nil {
+			// Filter by runID if specified
+			if runID != "" {
+				eventRunID, ok := event["runId"].(string)
+				if !ok || eventRunID != runID {
+					continue
+				}
+			}
+			events = append(events, event)
+		}
+	}
+
+	return events, nil
+}
+
+// splitLines splits bytes by newline
+func splitLines(data []byte) [][]byte {
+	var lines [][]byte
+	start := 0
+	for i, b := range data {
+		if b == '\n' {
+			line := data[start:i]
+			if len(line) > 0 {
+				lines = append(lines, line)
+			}
+			start = i + 1
+		}
+	}
+	if start < len(data) {
+		lines = append(lines, data[start:])
+	}
+	return lines
+}
+
+// HandleAGUIHistory handles GET /api/projects/:projectName/agentic-sessions/:sessionName/agui/history
+// Returns compacted message history for a session
+func HandleAGUIHistory(c *gin.Context) {
+	projectName := c.Param("projectName")
+	sessionName := c.Param("sessionName")
+
+	// SECURITY: Authenticate user and get user-scoped K8s client
+	reqK8s, _ := handlers.GetK8sClientsForRequest(c)
+	if reqK8s == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid or missing token"})
+		c.Abort()
+		return
+	}
+
+	// SECURITY: Verify user has permission to read this session
+	ctx := context.Background()
+	ssar := &authv1.SelfSubjectAccessReview{
+		Spec: authv1.SelfSubjectAccessReviewSpec{
+			ResourceAttributes: &authv1.ResourceAttributes{
+				Group:     "vteam.ambient-code",
+				Resource:  "agenticsessions",
+				Verb:      "get",
+				Namespace: projectName,
+				Name:      sessionName,
+			},
+		},
+	}
+	res, err := reqK8s.AuthorizationV1().SelfSubjectAccessReviews().Create(ctx, ssar, metav1.CreateOptions{})
+	if err != nil || !res.Status.Allowed {
+		log.Printf("AGUI History: User not authorized to read session %s/%s", projectName, sessionName)
+		c.JSON(http.StatusForbidden, gin.H{"error": "Unauthorized"})
+		c.Abort()
+		return
+	}
+	runID := c.Query("runId")
+
+	// Compact events to messages
+	var messages []types.Message
+	if runID != "" {
+		events, err := loadEventsForRun(sessionName, runID)
+		if err == nil {
+			messages = CompactEvents(events)
+		}
+	}
+
+	// Get runs for this session
+	runs := getRunsForSession(sessionName)
+
+	c.JSON(http.StatusOK, gin.H{
+		"threadId": sessionName,
+		"runId":    runID,
+		"messages": messages,
+		"runs":     runs,
+	})
+}
+
+// HandleAGUIRuns handles GET /api/projects/:projectName/agentic-sessions/:sessionName/agui/runs
+// Returns list of runs for a session (thread)
+func HandleAGUIRuns(c *gin.Context) {
+	projectName := c.Param("projectName")
+	sessionName := c.Param("sessionName")
+
+	// SECURITY: Authenticate user and get user-scoped K8s client
+	reqK8s, _ := handlers.GetK8sClientsForRequest(c)
+	if reqK8s == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid or missing token"})
+		c.Abort()
+		return
+	}
+
+	// SECURITY: Verify user has permission to read this session
+	ctx := context.Background()
+	ssar := &authv1.SelfSubjectAccessReview{
+		Spec: authv1.SelfSubjectAccessReviewSpec{
+			ResourceAttributes: &authv1.ResourceAttributes{
+				Group:     "vteam.ambient-code",
+				Resource:  "agenticsessions",
+				Verb:      "get",
+				Namespace: projectName,
+				Name:      sessionName,
+			},
+		},
+	}
+	res, err := reqK8s.AuthorizationV1().SelfSubjectAccessReviews().Create(ctx, ssar, metav1.CreateOptions{})
+	if err != nil || !res.Status.Allowed {
+		log.Printf("AGUI Runs: User not authorized to read session %s/%s", projectName, sessionName)
+		c.JSON(http.StatusForbidden, gin.H{"error": "Unauthorized"})
+		c.Abort()
+		return
+	}
+
+	runs := getRunsForSession(sessionName)
+
+	c.JSON(http.StatusOK, gin.H{
+		"threadId": sessionName,
+		"runs":     runs,
+	})
+}
+
+func getRunsForSession(sessionID string) []types.AGUIRunMetadata {
+	// First load from disk (historical runs)
+	runs := loadRunsFromDisk(sessionID)
+
+	// Create a set of run IDs from disk
+	diskRunIDs := make(map[string]bool)
+	for _, r := range runs {
+		diskRunIDs[r.RunID] = true
+	}
+
+	// Add any active runs not yet persisted
+	aguiRunsMu.RLock()
+	for _, run := range aguiRuns {
+		if run.SessionID == sessionID && !diskRunIDs[run.RunID] {
+			meta := types.AGUIRunMetadata{
+				ThreadID:    run.ThreadID,
+				RunID:       run.RunID,
+				ParentRunID: run.ParentRunID,
+				SessionName: run.SessionID,
+				ProjectName: run.ProjectName,
+				StartedAt:   run.StartedAt.Format(time.RFC3339),
+				Status:      run.Status,
+			}
+			runs = append(runs, meta)
+		}
+	}
+	aguiRunsMu.RUnlock()
+
+	return runs
+}
+
+// Helper file operations
+
+func ensureDir(path string) error {
+	return os.MkdirAll(path, 0755)
+}
+
+func openFileAppend(path string) (*os.File, error) {
+	return os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
+}
+
+// Integration with existing hub - modify hub.go run() to also broadcast to AG-UI subscribers
+// This is done by calling BroadcastToSessionSubscribers in the hub's broadcast case
+
+func init() {
+	// Hook into the hub to also broadcast to AG-UI subscribers
+	// We'll need to modify hub.go to call BroadcastToSessionSubscribers
+}
diff --git a/components/backend/websocket/agui_proxy.go b/components/backend/websocket/agui_proxy.go
new file mode 100644
index 000000000..6a60ba79b
--- /dev/null
+++ b/components/backend/websocket/agui_proxy.go
@@ -0,0 +1,473 @@
+// Package websocket provides AG-UI protocol endpoints including HTTP proxy to runner.
+package websocket
+
+import (
+	"ambient-code-backend/handlers"
+	"ambient-code-backend/types"
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	authv1 "k8s.io/api/authorization/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+)
+
+// HandleAGUIRunProxy proxies AG-UI run requests to runner's FastAPI server
+// This replaces the WebSocket-based communication with HTTP/SSE
+func HandleAGUIRunProxy(c *gin.Context) {
+	projectName := c.Param("projectName")
+	sessionName := c.Param("sessionName")
+
+	// SECURITY: Authenticate user and get user-scoped K8s client
+	reqK8s, _ := handlers.GetK8sClientsForRequest(c)
+	if reqK8s == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid or missing token"})
+		c.Abort()
+		return
+	}
+
+	// SECURITY: Verify user has permission to update this session
+	ctx := context.Background()
+	ssar := &authv1.SelfSubjectAccessReview{
+		Spec: authv1.SelfSubjectAccessReviewSpec{
+			ResourceAttributes: &authv1.ResourceAttributes{
+				Group:     "vteam.ambient-code",
+				Resource:  "agenticsessions",
+				Verb:      "update",
+				Namespace: projectName,
+				Name:      sessionName,
+			},
+		},
+	}
+	res, err := reqK8s.AuthorizationV1().SelfSubjectAccessReviews().Create(ctx, ssar, metav1.CreateOptions{})
+	if err != nil || !res.Status.Allowed {
+		log.Printf("AGUI Proxy: User not authorized to update session %s/%s", projectName, sessionName)
+		c.JSON(http.StatusForbidden, gin.H{"error": "Unauthorized"})
+		c.Abort()
+		return
+	}
+
+	log.Printf("AGUI Proxy: Forwarding run request for %s/%s", projectName, sessionName)
+
+	var input types.RunAgentInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		log.Printf("AGUI Proxy: Failed to parse input: %v", err)
+		c.JSON(http.StatusBadRequest, gin.H{"error": fmt.Sprintf("invalid input: %v", err)})
+		return
+	}
+	log.Printf("AGUI Proxy: Input has %d messages", len(input.Messages))
+
+	// Generate or use provided IDs
+	threadID := input.ThreadID
+	if threadID == "" {
+		threadID = sessionName
+	}
+	runID := input.RunID
+	if runID == "" {
+		runID = uuid.New().String()
+	}
+	input.ThreadID = threadID
+	input.RunID = runID
+
+	log.Printf("AGUI Proxy: Creating run %s for session %s (threadId=%s)", runID, sessionName, threadID)
+
+	// Create run state for tracking
+	runState := &AGUIRunState{
+		ThreadID:     threadID,
+		RunID:        runID,
+		ParentRunID:  input.ParentRunID,
+		SessionID:    sessionName,
+		ProjectName:  projectName,
+		Status:       "running",
+		StartedAt:    time.Now(),
+		subscribers:  make(map[chan *types.BaseEvent]bool),
+		fullEventSub: make(map[chan interface{}]bool),
+	}
+
+	aguiRunsMu.Lock()
+	aguiRuns[runID] = runState
+	aguiRunsMu.Unlock()
+
+	// Persist run metadata
+	go persistRunMetadata(sessionName, types.AGUIRunMetadata{
+		ThreadID:    threadID,
+		RunID:       runID,
+		ParentRunID: input.ParentRunID,
+		SessionName: sessionName,
+		ProjectName: projectName,
+		StartedAt:   runState.StartedAt.Format(time.RFC3339),
+		Status:      "running",
+	})
+
+	// NOTE: User messages are now echoed by the runner (AG-UI server pattern)
+	// The runner emits TEXT_MESSAGE_START/CONTENT/END events which are persisted
+	// when they stream through this proxy. No need to echo them here.
+
+	// Trigger async display name generation on first user message
+	// This generates a descriptive name using Claude Haiku based on the message
+	go triggerDisplayNameGenerationIfNeeded(projectName, sessionName, input.Messages)
+
+	// Get runner endpoint
+	runnerURL, err := getRunnerEndpoint(projectName, sessionName)
+	if err != nil {
+		log.Printf("AGUI Proxy: Failed to get runner endpoint: %v", err)
+		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Runner not available"})
+		return
+	}
+
+	log.Printf("AGUI Proxy: Runner endpoint: %s", runnerURL)
+
+	// Serialize input for proxy request
+	bodyBytes, err := json.Marshal(input)
+	if err != nil {
+		log.Printf("AGUI Proxy: Failed to serialize input: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to serialize input"})
+		return
+	}
+
+	log.Printf("AGUI Proxy: Run %s starting, will consume runner stream in background", runID)
+
+	// Start background goroutine that owns the entire HTTP lifecycle
+	// This ensures the connection stays open after we return to client
+	// Note: We use context.Background() (not request context) because this goroutine
+	// must continue running after the HTTP request completes. The timeout and terminal
+	// event handling prevent unbounded goroutine accumulation.
+	go func() {
+		// Create request with long timeout (detached from client request lifecycle)
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Hour)
+		defer cancel()
+
+		proxyReq, err := http.NewRequestWithContext(ctx, "POST", runnerURL, bytes.NewReader(bodyBytes))
+		if err != nil {
+			log.Printf("AGUI Proxy: Failed to create request in background: %v", err)
+			updateRunStatus(runID, "error")
+			return
+		}
+
+		// Forward headers
+		proxyReq.Header.Set("Content-Type", "application/json")
+		proxyReq.Header.Set("Accept", "text/event-stream")
+
+		// Execute request
+		client := &http.Client{
+			Timeout: 0, // No timeout, context handles it
+		}
+		resp, err := client.Do(proxyReq)
+		if err != nil {
+			log.Printf("AGUI Proxy: Background request failed: %v", err)
+			updateRunStatus(runID, "error")
+			return
+		}
+		defer resp.Body.Close()
+
+		if resp.StatusCode != http.StatusOK {
+			body, _ := io.ReadAll(resp.Body)
+			log.Printf("AGUI Proxy: Runner returned status %d: %s", resp.StatusCode, string(body))
+			updateRunStatus(runID, "error")
+			return
+		}
+
+		log.Printf("AGUI Proxy: Background stream started for run %s", runID)
+
+		reader := bufio.NewReader(resp.Body)
+
+		for {
+			// Check if context was cancelled (timeout or cleanup)
+			select {
+			case <-ctx.Done():
+				log.Printf("AGUI Proxy: Context cancelled for run %s", runID)
+				return
+			default:
+			}
+
+			line, err := reader.ReadString('\n')
+			if err != nil {
+				if err == io.EOF {
+					log.Printf("AGUI Proxy: Background stream ended for run %s", runID)
+					break
+				}
+				log.Printf("AGUI Proxy: Background stream read error: %v", err)
+				break
+			}
+
+			// Parse and persist SSE events
+			line = strings.TrimSpace(line)
+			if strings.HasPrefix(line, "data: ") {
+				jsonData := strings.TrimPrefix(line, "data: ")
+				handleStreamedEvent(sessionName, runID, threadID, jsonData, runState)
+			}
+		}
+
+		// Mark run as completed
+		aguiRunsMu.RLock()
+		currentStatus := "completed"
+		if state, exists := aguiRuns[runID]; exists && state.Status == "error" {
+			currentStatus = "error"
+		}
+		aguiRunsMu.RUnlock()
+
+		updateRunStatus(runID, currentStatus)
+		log.Printf("AGUI Proxy: Background stream completed for run %s (status=%s)", runID, currentStatus)
+	}()
+
+	// Return run metadata immediately (don't wait for stream)
+	// Events will be broadcast to GET /agui/events subscribers
+	streamURL := fmt.Sprintf("/api/projects/%s/agentic-sessions/%s/agui/events", projectName, sessionName)
+
+	c.JSON(http.StatusOK, gin.H{
+		"threadId":  threadID,
+		"runId":     runID,
+		"streamUrl": streamURL,
+		"status":    "started",
+	})
+}
+
+// handleStreamedEvent parses and persists a streamed AG-UI event
+func handleStreamedEvent(sessionID, runID, threadID, jsonData string, runState *AGUIRunState) {
+	var event map[string]interface{}
+	if err := json.Unmarshal([]byte(jsonData), &event); err != nil {
+		log.Printf("AGUI Proxy: Failed to parse event JSON: %v", err)
+		return
+	}
+
+	eventType, _ := event["type"].(string)
+
+	// Ensure threadId and runId are set
+	if _, ok := event["threadId"]; !ok {
+		event["threadId"] = threadID
+	}
+	if _, ok := event["runId"]; !ok {
+		event["runId"] = runID
+	}
+
+	// Check for terminal events
+	switch eventType {
+	case types.EventTypeRunFinished:
+		updateRunStatus(runID, "completed")
+	case types.EventTypeRunError:
+		updateRunStatus(runID, "error")
+	}
+
+	// Persist event
+	persistAGUIEventMap(sessionID, runID, event)
+
+	// Broadcast to subscribers (for SSE /events endpoint)
+	if runState != nil {
+		runState.BroadcastFull(event)
+	}
+
+	// Also broadcast to thread subscribers
+	broadcastToThread(sessionID, event)
+}
+
+// updateRunStatus updates the status of a run
+func updateRunStatus(runID, status string) {
+	aguiRunsMu.Lock()
+	if state, exists := aguiRuns[runID]; exists {
+		state.Status = status
+		// Update persisted metadata
+		go persistRunMetadata(state.SessionID, types.AGUIRunMetadata{
+			ThreadID:    state.ThreadID,
+			RunID:       state.RunID,
+			ParentRunID: state.ParentRunID,
+			SessionName: state.SessionID,
+			ProjectName: state.ProjectName,
+			StartedAt:   state.StartedAt.Format(time.RFC3339),
+			Status:      status,
+		})
+	}
+	aguiRunsMu.Unlock()
+}
+
+// HandleAGUIInterrupt sends interrupt signal to runner to stop current execution
+// POST /api/projects/:projectName/agentic-sessions/:sessionName/agui/interrupt
+func HandleAGUIInterrupt(c *gin.Context) {
+	projectName := c.Param("projectName")
+	sessionName := c.Param("sessionName")
+
+	// SECURITY: Authenticate user and get user-scoped K8s client
+	reqK8s, _ := handlers.GetK8sClientsForRequest(c)
+	if reqK8s == nil {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid or missing token"})
+		c.Abort()
+		return
+	}
+
+	// SECURITY: Verify user has permission to update this session
+	ctx := context.Background()
+	ssar := &authv1.SelfSubjectAccessReview{
+		Spec: authv1.SelfSubjectAccessReviewSpec{
+			ResourceAttributes: &authv1.ResourceAttributes{
+				Group:     "vteam.ambient-code",
+				Resource:  "agenticsessions",
+				Verb:      "update",
+				Namespace: projectName,
+				Name:      sessionName,
+			},
+		},
+	}
+	res, err := reqK8s.AuthorizationV1().SelfSubjectAccessReviews().Create(ctx, ssar, metav1.CreateOptions{})
+	if err != nil || !res.Status.Allowed {
+		log.Printf("AGUI Interrupt: User not authorized to update session %s/%s", projectName, sessionName)
+		c.JSON(http.StatusForbidden, gin.H{"error": "Unauthorized"})
+		c.Abort()
+		return
+	}
+
+	log.Printf("AGUI Interrupt: Request for %s/%s", projectName, sessionName)
+
+	var input struct {
+		RunID string `json:"runId"`
+	}
+	if err := c.ShouldBindJSON(&input); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "runId required"})
+		return
+	}
+
+	// Get runner endpoint
+	runnerURL, err := getRunnerEndpoint(projectName, sessionName)
+	if err != nil {
+		log.Printf("AGUI Interrupt: Failed to get runner endpoint: %v", err)
+		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Runner not available"})
+		return
+	}
+
+	interruptURL := strings.TrimSuffix(runnerURL, "/") + "/interrupt"
+	log.Printf("AGUI Interrupt: Forwarding to runner: %s", interruptURL)
+
+	// POST to runner's interrupt endpoint
+	req, err := http.NewRequest("POST", interruptURL, bytes.NewReader([]byte("{}")))
+	if err != nil {
+		log.Printf("AGUI Interrupt: Failed to create request: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		log.Printf("AGUI Interrupt: Request failed: %v", err)
+		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+		return
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		log.Printf("AGUI Interrupt: Runner returned %d: %s", resp.StatusCode, string(body))
+		c.JSON(resp.StatusCode, gin.H{"error": string(body)})
+		return
+	}
+
+	log.Printf("AGUI Interrupt: Successfully interrupted run %s", input.RunID)
+	c.JSON(http.StatusOK, gin.H{"message": "Interrupt signal sent"})
+}
+
+// getRunnerEndpoint returns the AG-UI server endpoint for a session
+// The operator creates a Service named "session-{sessionName}" in the project namespace
+func getRunnerEndpoint(projectName, sessionName string) (string, error) {
+	// Use naming convention for service discovery
+	// Format: http://session-{sessionName}.{projectName}.svc.cluster.local:8000/
+	// The operator creates this Service automatically when spawning the runner Job
+	return fmt.Sprintf("http://session-%s.%s.svc.cluster.local:8000/", sessionName, projectName), nil
+}
+
+// broadcastToThread sends event to all thread-level subscribers
+func broadcastToThread(sessionID string, event interface{}) {
+	threadSubscribersMu.RLock()
+	subs, exists := threadSubscribers[sessionID]
+	threadSubscribersMu.RUnlock()
+
+	if !exists {
+		return
+	}
+
+	for ch := range subs {
+		select {
+		case ch <- event:
+		default:
+			// Channel full, skip
+		}
+	}
+}
+
+// triggerDisplayNameGenerationIfNeeded checks if the session needs a display name
+// and triggers async generation using the first REAL user message (not auto-sent initialPrompt)
+func triggerDisplayNameGenerationIfNeeded(projectName, sessionName string, messages []types.Message) {
+	// Extract first user message
+	var userMessage string
+	for _, msg := range messages {
+		if msg.Role == "user" && msg.Content != "" {
+			userMessage = msg.Content
+			break
+		}
+	}
+
+	if userMessage == "" {
+		log.Printf("DisplayNameGen: No user message found in run request for %s/%s", projectName, sessionName)
+		return
+	}
+
+	// Check if session already has a display name
+	if handlers.DynamicClient == nil {
+		log.Printf("DisplayNameGen: DynamicClient not initialized, skipping display name generation")
+		return
+	}
+
+	gvr := handlers.GetAgenticSessionV1Alpha1Resource()
+	ctx := context.Background()
+
+	item, err := handlers.DynamicClient.Resource(gvr).Namespace(projectName).Get(ctx, sessionName, metav1.GetOptions{})
+	if err != nil {
+		log.Printf("DisplayNameGen: Failed to get session %s/%s: %v", projectName, sessionName, err)
+		return
+	}
+
+	// Extract spec using unstructured helpers (per CLAUDE.md guidelines)
+	spec, found, err := unstructured.NestedMap(item.Object, "spec")
+	if err != nil || !found {
+		log.Printf("DisplayNameGen: Failed to get spec for %s/%s", projectName, sessionName)
+		return
+	}
+
+	// Skip if this message is the auto-sent initialPrompt (not a real user message)
+	initialPrompt, _, _ := unstructured.NestedString(spec, "initialPrompt")
+	if initialPrompt != "" && strings.TrimSpace(userMessage) == strings.TrimSpace(initialPrompt) {
+		log.Printf("DisplayNameGen: Skipping auto-sent initialPrompt for %s/%s", projectName, sessionName)
+		return
+	}
+
+	// Check if display name generation is needed
+	if !handlers.ShouldGenerateDisplayName(spec) {
+		log.Printf("DisplayNameGen: Session %s/%s already has display name, skipping", projectName, sessionName)
+		return
+	}
+
+	// Extract session context for better name generation
+	sessionCtx := handlers.ExtractSessionContext(spec)
+
+	log.Printf("DisplayNameGen: Triggering async generation for %s/%s with message: %q",
+		projectName, sessionName, truncateForLog(userMessage, 50))
+
+	// Trigger async generation (runs in background, fails silently)
+	handlers.GenerateDisplayNameAsync(projectName, sessionName, userMessage, sessionCtx)
+}
+
+// truncateForLog truncates a string for logging purposes
+func truncateForLog(s string, maxLen int) string {
+	if len(s) <= maxLen {
+		return s
+	}
+	return s[:maxLen] + "..."
+}
diff --git a/components/backend/websocket/compaction.go b/components/backend/websocket/compaction.go
new file mode 100644
index 000000000..d03f77f7c
--- /dev/null
+++ b/components/backend/websocket/compaction.go
@@ -0,0 +1,390 @@
+package websocket
+
+import (
+	"ambient-code-backend/types"
+	"log"
+
+	"github.com/google/uuid"
+)
+
+// MessageCompactor compacts AG-UI events into message snapshots
+// Per AG-UI spec: https://docs.ag-ui.com/concepts/serialization
+type MessageCompactor struct {
+	messages        []types.Message
+	currentMessage  *types.Message
+	activeToolCalls map[string]*ActiveToolCall // toolId -> tool state
+	hiddenMessages  map[string]bool            // messageId -> hidden flag
+}
+
+// ActiveToolCall tracks an in-progress tool call
+type ActiveToolCall struct {
+	ID              string
+	Name            string
+	Args            string // Accumulated from TOOL_CALL_ARGS deltas
+	ParentToolUseID string
+	Status          string
+}
+
+// NewMessageCompactor creates a new message compactor
+func NewMessageCompactor() *MessageCompactor {
+	return &MessageCompactor{
+		messages:        make([]types.Message, 0),
+		activeToolCalls: make(map[string]*ActiveToolCall),
+		hiddenMessages:  make(map[string]bool),
+	}
+}
+
+// HandleEvent processes a single AG-UI event and updates compacted state
+func (c *MessageCompactor) HandleEvent(event map[string]interface{}) {
+	eventType, _ := event["type"].(string)
+
+	switch eventType {
+	case types.EventTypeTextMessageStart:
+		c.handleTextMessageStart(event)
+	case types.EventTypeTextMessageContent:
+		c.handleTextMessageContent(event)
+	case types.EventTypeTextMessageEnd:
+		c.handleTextMessageEnd(event)
+	case types.EventTypeToolCallStart:
+		c.handleToolCallStart(event)
+	case types.EventTypeToolCallArgs:
+		c.handleToolCallArgs(event)
+	case types.EventTypeToolCallEnd:
+		c.handleToolCallEnd(event)
+	case types.EventTypeRaw:
+		c.handleRawEvent(event)
+	case types.EventTypeMessagesSnapshot:
+		c.handleMessagesSnapshot(event)
+	case types.EventTypeRunStarted, types.EventTypeRunFinished, types.EventTypeRunError:
+		// Lifecycle events - skip, don't affect message compaction
+	case types.EventTypeStepStarted, types.EventTypeStepFinished:
+		// Step events - skip, don't affect message compaction
+	case types.EventTypeStateSnapshot, types.EventTypStateDelta:
+		// State events - skip, don't affect message compaction
+	case types.EventTypeActivitySnapshot, types.EventTypeActivityDelta:
+		// Activity events - skip, don't affect message compaction
+	default:
+		log.Printf("Compaction: WARNING - Unhandled event type: %s", eventType)
+	}
+}
+
+// GetMessages returns the compacted messages (excluding hidden ones)
+func (c *MessageCompactor) GetMessages() []types.Message {
+	// Flush any active message
+	if c.currentMessage != nil {
+		c.messages = append(c.messages, *c.currentMessage)
+		c.currentMessage = nil
+	}
+
+	// DO NOT include in-progress tools in snapshots!
+	// Snapshots should only contain COMPLETED runs with finished tool calls.
+	// In-progress tools will be streamed as raw events from the active run.
+	//
+	// If we included "running" status tools here, they would duplicate when
+	// the active run's TOOL_CALL_END events are replayed.
+	if len(c.activeToolCalls) > 0 {
+		// Clear activeToolCalls - don't include them in snapshot
+		c.activeToolCalls = make(map[string]*ActiveToolCall)
+	}
+
+	// Filter out hidden messages (auto-sent initial/workflow prompts)
+	visibleMessages := make([]types.Message, 0, len(c.messages))
+	hiddenCount := 0
+	for _, msg := range c.messages {
+		if c.hiddenMessages[msg.ID] {
+			hiddenCount++
+			continue
+		}
+		visibleMessages = append(visibleMessages, msg)
+	}
+
+	return visibleMessages
+}
+
+// Event Handlers
+
+func (c *MessageCompactor) handleTextMessageStart(event map[string]interface{}) {
+	// Flush previous message if any
+	if c.currentMessage != nil {
+		c.messages = append(c.messages, *c.currentMessage)
+	}
+
+	// Handle both camelCase and snake_case
+	messageID, _ := event["messageId"].(string)
+	if messageID == "" {
+		messageID, _ = event["message_id"].(string)
+	}
+	role, _ := event["role"].(string)
+	if role == "" {
+		role = types.RoleAssistant
+	}
+
+	c.currentMessage = &types.Message{
+		ID:      messageID,
+		Role:    role,
+		Content: "",
+	}
+}
+
+func (c *MessageCompactor) handleTextMessageContent(event map[string]interface{}) {
+	if c.currentMessage == nil {
+		return
+	}
+
+	delta, _ := event["delta"].(string)
+	c.currentMessage.Content += delta
+}
+
+func (c *MessageCompactor) handleTextMessageEnd(event map[string]interface{}) {
+	if c.currentMessage != nil {
+		// User messages never have tool calls - flush immediately
+		// Assistant messages might have tool calls - keep open
+		// We'll flush when a new TEXT_MESSAGE_START arrives or at the end of compaction
+		if c.currentMessage.Role == types.RoleUser {
+			c.messages = append(c.messages, *c.currentMessage)
+			c.currentMessage = nil
+		}
+	}
+}
+
+func (c *MessageCompactor) handleToolCallStart(event map[string]interface{}) {
+	// Handle both camelCase (TypeScript) and snake_case (Python ag_ui.core)
+	toolID, _ := event["toolCallId"].(string)
+	if toolID == "" {
+		toolID, _ = event["tool_call_id"].(string)
+	}
+	toolName, _ := event["toolCallName"].(string)
+	if toolName == "" {
+		toolName, _ = event["tool_call_name"].(string)
+	}
+
+	// Try multiple field names for parent tool ID
+	parentToolUseID, _ := event["parentToolUseId"].(string)
+	if parentToolUseID == "" {
+		parentToolUseID, _ = event["parentToolUseID"].(string)
+	}
+	if parentToolUseID == "" {
+		parentToolUseID, _ = event["parent_tool_call_id"].(string)
+	}
+
+	if toolID != "" {
+		c.activeToolCalls[toolID] = &ActiveToolCall{
+			ID:              toolID,
+			Name:            toolName,
+			Args:            "",
+			ParentToolUseID: parentToolUseID,
+			Status:          "running",
+		}
+	}
+}
+
+func (c *MessageCompactor) handleToolCallArgs(event map[string]interface{}) {
+	// Handle both camelCase and snake_case
+	toolID, _ := event["toolCallId"].(string)
+	if toolID == "" {
+		toolID, _ = event["tool_call_id"].(string)
+	}
+	delta, _ := event["delta"].(string)
+
+	if toolID == "" {
+		return
+	}
+
+	if active, ok := c.activeToolCalls[toolID]; ok {
+		active.Args += delta
+	}
+}
+
+func (c *MessageCompactor) handleToolCallEnd(event map[string]interface{}) {
+	// Handle both camelCase and snake_case
+	toolID, _ := event["toolCallId"].(string)
+	if toolID == "" {
+		toolID, _ = event["tool_call_id"].(string)
+	}
+	result, _ := event["result"].(string)
+	errorStr, _ := event["error"].(string)
+
+	if toolID == "" {
+		return
+	}
+
+	active, ok := c.activeToolCalls[toolID]
+	if !ok {
+		return
+	}
+
+	// Create completed tool call
+	tc := types.ToolCall{
+		ID:              active.ID,
+		Name:            active.Name,
+		Args:            active.Args,
+		Type:            "function",
+		ParentToolUseID: active.ParentToolUseID,
+		Result:          result,
+		Status:          "completed",
+	}
+	if errorStr != "" {
+		tc.Error = errorStr
+		tc.Status = "error"
+	}
+
+	// Add to message
+	// Check if we need to create a new message or add to current
+	if c.currentMessage != nil && c.currentMessage.Role == types.RoleAssistant {
+		// Add to current message
+		c.currentMessage.ToolCalls = append(c.currentMessage.ToolCalls, tc)
+	} else {
+		// Create new message for this tool call
+		c.messages = append(c.messages, types.Message{
+			ID:        uuid.New().String(),
+			Role:      types.RoleAssistant,
+			ToolCalls: []types.ToolCall{tc},
+		})
+	}
+
+	// Remove from active
+	delete(c.activeToolCalls, toolID)
+}
+
+func (c *MessageCompactor) handleRawEvent(event map[string]interface{}) {
+	// Check for both "data" and "event" fields (AG-UI uses "event")
+	var data map[string]interface{}
+	if d, ok := event["event"].(map[string]interface{}); ok {
+		data = d
+	} else if d, ok := event["data"].(map[string]interface{}); ok {
+		data = d
+	} else {
+		return
+	}
+
+	// Handle message_metadata events (for hiding auto-sent prompts)
+	if msgType, _ := data["type"].(string); msgType == "message_metadata" {
+		if hidden, _ := data["hidden"].(bool); hidden {
+			if messageID, ok := data["messageId"].(string); ok {
+				c.hiddenMessages[messageID] = true
+			}
+		}
+		return
+	}
+
+	role, _ := data["role"].(string)
+	if role == "" {
+		return
+	}
+
+	// Flush current message
+	if c.currentMessage != nil {
+		c.messages = append(c.messages, *c.currentMessage)
+		c.currentMessage = nil
+	}
+
+	// Add raw message
+	msg := types.Message{Role: role}
+	if id, ok := data["id"].(string); ok {
+		msg.ID = id
+	}
+	if content, ok := data["content"].(string); ok {
+		msg.Content = content
+	}
+	if timestamp, ok := data["timestamp"].(string); ok {
+		msg.Timestamp = timestamp
+	}
+
+	c.messages = append(c.messages, msg)
+}
+
+func (c *MessageCompactor) handleMessagesSnapshot(event map[string]interface{}) {
+	// If runner sends MESSAGES_SNAPSHOT, use it directly (overrides compaction)
+	msgs, ok := event["messages"].([]interface{})
+	if !ok {
+		return
+	}
+
+	// Replace all messages with snapshot
+	c.messages = make([]types.Message, 0, len(msgs))
+	c.currentMessage = nil
+
+	for _, m := range msgs {
+		msgMap, ok := m.(map[string]interface{})
+		if !ok {
+			continue
+		}
+
+		msg := types.Message{}
+		if id, ok := msgMap["id"].(string); ok {
+			msg.ID = id
+		}
+		if role, ok := msgMap["role"].(string); ok {
+			msg.Role = role
+		}
+		if content, ok := msgMap["content"].(string); ok {
+			msg.Content = content
+		}
+		if timestamp, ok := msgMap["timestamp"].(string); ok {
+			msg.Timestamp = timestamp
+		}
+
+		// Extract toolCalls array
+		if toolCalls, ok := msgMap["toolCalls"].([]interface{}); ok {
+			msg.ToolCalls = make([]types.ToolCall, 0, len(toolCalls))
+			for _, tc := range toolCalls {
+				tcMap, ok := tc.(map[string]interface{})
+				if !ok {
+					continue
+				}
+
+				toolCall := types.ToolCall{}
+				if id, ok := tcMap["id"].(string); ok {
+					toolCall.ID = id
+				}
+				if name, ok := tcMap["name"].(string); ok {
+					toolCall.Name = name
+				}
+				if args, ok := tcMap["args"].(string); ok {
+					toolCall.Args = args
+				}
+				if tcType, ok := tcMap["type"].(string); ok {
+					toolCall.Type = tcType
+				}
+				if parentID, ok := tcMap["parentToolUseId"].(string); ok {
+					toolCall.ParentToolUseID = parentID
+				}
+				if result, ok := tcMap["result"].(string); ok {
+					toolCall.Result = result
+				}
+				if status, ok := tcMap["status"].(string); ok {
+					toolCall.Status = status
+				}
+				if errorStr, ok := tcMap["error"].(string); ok {
+					toolCall.Error = errorStr
+				}
+
+				msg.ToolCalls = append(msg.ToolCalls, toolCall)
+			}
+		}
+
+		c.messages = append(c.messages, msg)
+	}
+
+}
+
+// CompactEvents is the main entry point for event compaction
+func CompactEvents(events []map[string]interface{}) []types.Message {
+
+	// Count event types to help debug
+	eventTypeCounts := make(map[string]int)
+	for _, event := range events {
+		eventType, _ := event["type"].(string)
+		eventTypeCounts[eventType]++
+	}
+
+	compactor := NewMessageCompactor()
+
+	for _, event := range events {
+		compactor.HandleEvent(event)
+	}
+
+	messages := compactor.GetMessages()
+
+	return messages
+}
diff --git a/components/backend/websocket/handlers.go b/components/backend/websocket/handlers.go
deleted file mode 100644
index 5c3a5ad05..000000000
--- a/components/backend/websocket/handlers.go
+++ /dev/null
@@ -1,333 +0,0 @@
-package websocket
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"log"
-	"net/http"
-	"strings"
-	"time"
-
-	"ambient-code-backend/handlers"
-
-	"github.com/gin-gonic/gin"
-	"github.com/gorilla/websocket"
-	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
-)
-
-// WebSocket upgrader
-var upgrader = websocket.Upgrader{
-	CheckOrigin: func(r *http.Request) bool {
-		// Allow all origins for development - should be restricted in production
-		return true
-	},
-}
-
-// HandleSessionWebSocket handles WebSocket connections for sessions
-// Route: /projects/:projectName/sessions/:sessionId/ws
-func HandleSessionWebSocket(c *gin.Context) {
-	sessionID := c.Param("sessionId")
-	log.Printf("handleSessionWebSocket for session: %s", sessionID)
-
-	// Access enforced by RBAC on downstream resources
-
-	// Best-effort user identity: prefer forwarded user, else extract ServiceAccount from bearer token
-	var userIDStr string
-	if v, ok := c.Get("userID"); ok {
-		if s, ok2 := v.(string); ok2 {
-			userIDStr = s
-		}
-	}
-	if userIDStr == "" {
-		if ns, sa, ok := handlers.ExtractServiceAccountFromAuth(c); ok {
-			userIDStr = ns + ":" + sa
-		}
-	}
-
-	// Upgrade HTTP connection to WebSocket
-	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
-	if err != nil {
-		log.Printf("WebSocket upgrade failed: %v", err)
-		return
-	}
-
-	sessionConn := &SessionConnection{
-		SessionID: sessionID,
-		Conn:      conn,
-		UserID:    userIDStr,
-	}
-
-	// Register connection
-	Hub.register <- sessionConn
-
-	// Handle messages from client
-	go handleWebSocketMessages(sessionConn)
-
-	// Keep connection alive
-	go handleWebSocketPing(sessionConn)
-}
-
-// handleWebSocketMessages processes incoming WebSocket messages
-func handleWebSocketMessages(conn *SessionConnection) {
-	defer func() {
-		Hub.unregister <- conn
-	}()
-
-	for {
-		messageType, messageData, err := conn.Conn.ReadMessage()
-		if err != nil {
-			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
-				log.Printf("WebSocket error: %v", err)
-			}
-			break
-		}
-
-		if messageType == websocket.TextMessage {
-			var msg map[string]interface{}
-			if err := json.Unmarshal(messageData, &msg); err != nil {
-				log.Printf("Failed to parse WebSocket message: %v", err)
-				continue
-			}
-
-			// Handle control messages
-			if msgType, ok := msg["type"].(string); ok {
-				if msgType == "ping" {
-					// Respond with pong
-					pong := map[string]interface{}{
-						"type":      "pong",
-						"timestamp": time.Now().UTC().Format(time.RFC3339),
-					}
-					pongData, _ := json.Marshal(pong)
-					// Lock write mutex before writing pong
-					conn.writeMu.Lock()
-					_ = conn.Conn.WriteMessage(websocket.TextMessage, pongData)
-					conn.writeMu.Unlock()
-					continue
-				}
-				// Extract payload from runner message to avoid double-nesting
-				// Runner sends: {type, seq, timestamp, payload}
-				// We only want to store the payload field
-				payload, ok := msg["payload"].(map[string]interface{})
-				if !ok {
-					payload = msg // Fallback for legacy format
-				}
-				// Broadcast all other messages to session listeners (UI and others)
-				sessionMsg := &SessionMessage{
-					SessionID: conn.SessionID,
-					Type:      msgType,
-					Timestamp: time.Now().UTC().Format(time.RFC3339),
-					Payload:   payload,
-				}
-				Hub.broadcast <- sessionMsg
-			}
-		}
-	}
-}
-
-// handleWebSocketPing sends periodic ping messages
-func handleWebSocketPing(conn *SessionConnection) {
-	ticker := time.NewTicker(30 * time.Second)
-	defer ticker.Stop()
-
-	for range ticker.C {
-		// Lock write mutex before writing ping
-		conn.writeMu.Lock()
-		err := conn.Conn.WriteMessage(websocket.PingMessage, nil)
-		conn.writeMu.Unlock()
-		if err != nil {
-			return
-		}
-	}
-}
-
-// GetSessionMessagesWS handles GET /projects/:projectName/sessions/:sessionId/messages
-// Retrieves messages from S3 storage
-func GetSessionMessagesWS(c *gin.Context) {
-	sessionID := c.Param("sessionId")
-
-	// Access enforced by RBAC on downstream resources
-
-	messages, err := retrieveMessagesFromS3(sessionID)
-	if err != nil {
-		log.Printf("getSessionMessagesWS: retrieve failed: %v", err)
-		c.JSON(http.StatusInternalServerError, gin.H{
-			"error": fmt.Sprintf("failed to retrieve messages: %v", err),
-		})
-		return
-	}
-
-	// Optional consolidation of partial messages
-	includeParam := strings.ToLower(strings.TrimSpace(c.Query("include_partial_messages")))
-	includePartials := includeParam == "1" || includeParam == "true" || includeParam == "yes"
-
-	collapsed := make([]SessionMessage, 0, len(messages))
-	activePartialIndex := -1
-	for _, m := range messages {
-		if m.Type == "message.partial" {
-			if includePartials {
-				if activePartialIndex >= 0 {
-					collapsed[activePartialIndex] = m
-				} else {
-					collapsed = append(collapsed, m)
-					activePartialIndex = len(collapsed) - 1
-				}
-			}
-			// If not including partials, simply skip adding them
-			continue
-		}
-		// On any non-partial, clear active partial placeholder
-		activePartialIndex = -1
-		collapsed = append(collapsed, m)
-	}
-
-	c.JSON(http.StatusOK, gin.H{
-		"sessionId": sessionID,
-		"messages":  collapsed,
-	})
-}
-
-// PostSessionMessageWS handles POST /projects/:projectName/sessions/:sessionId/messages
-// Accepts a generic JSON body. If a "type" string is provided, it will be used.
-// Otherwise, defaults to "user_message" and wraps body under payload.
-func PostSessionMessageWS(c *gin.Context) {
-	projectName := c.Param("projectName")
-	sessionID := c.Param("sessionId")
-
-	var body map[string]interface{}
-	if err := c.BindJSON(&body); err != nil {
-		log.Printf("postSessionMessageWS: bind failed: %v", err)
-		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid JSON body"})
-		return
-	}
-
-	msgType := "user_message"
-	if v, ok := body["type"].(string); ok && v != "" {
-		msgType = v
-		// Remove type from payload to avoid duplication
-		delete(body, "type")
-	}
-
-	message := &SessionMessage{
-		SessionID: sessionID,
-		Type:      msgType,
-		Timestamp: time.Now().UTC().Format(time.RFC3339),
-		Payload:   body,
-	}
-
-	// Broadcast to session listeners (runner) and persist
-	Hub.broadcast <- message
-
-	// Check if we should auto-generate a display name
-	// Only for user_message type (not control messages like interrupt/end_session)
-	if msgType == "user_message" {
-		go triggerDisplayNameGenerationIfNeeded(projectName, sessionID, body)
-	}
-
-	c.JSON(http.StatusAccepted, gin.H{"status": "queued"})
-}
-
-// maxUserMessageChars is the maximum characters to include from user messages for display name generation
-const maxUserMessageChars = 1000
-
-// triggerDisplayNameGenerationIfNeeded checks if display name generation should be triggered
-// and initiates it asynchronously. This runs in a goroutine to not block the response.
-func triggerDisplayNameGenerationIfNeeded(projectName, sessionID string, messageBody map[string]interface{}) {
-	// Extract current user message content
-	currentContent, ok := messageBody["content"].(string)
-	if !ok || strings.TrimSpace(currentContent) == "" {
-		return
-	}
-
-	// Get session to check if displayName is set and get context
-	session, err := getSessionForDisplayName(projectName, sessionID)
-	if err != nil {
-		log.Printf("DisplayNameGen: Failed to get session %s/%s: %v", projectName, sessionID, err)
-		return
-	}
-
-	spec, ok := session["spec"].(map[string]interface{})
-	if !ok {
-		return
-	}
-
-	// Check if display name should be generated (only if empty/unset)
-	if !handlers.ShouldGenerateDisplayName(spec) {
-		return
-	}
-
-	log.Printf("DisplayNameGen: Triggering generation for %s/%s", projectName, sessionID)
-
-	// Collect all user messages (existing + current) for better context
-	combinedContent := collectUserMessages(sessionID, currentContent)
-
-	// Extract session context for better name generation
-	sessionCtx := handlers.ExtractSessionContext(spec)
-
-	// Trigger async display name generation
-	handlers.GenerateDisplayNameAsync(projectName, sessionID, combinedContent, sessionCtx)
-}
-
-// collectUserMessages fetches existing user messages from storage and combines with current message
-// Returns a truncated string of all user messages (max maxUserMessageChars)
-func collectUserMessages(sessionID, currentMessage string) string {
-	// Fetch existing messages from storage
-	existingMessages, err := retrieveMessagesFromS3(sessionID)
-	if err != nil {
-		log.Printf("DisplayNameGen: Failed to retrieve messages for %s: %v", sessionID, err)
-		// Fall back to just the current message
-		return truncateString(currentMessage, maxUserMessageChars)
-	}
-
-	// Collect user message contents
-	var userMessages []string
-	for _, msg := range existingMessages {
-		if msg.Type == "user_message" {
-			// Extract content from payload (Payload is already map[string]interface{})
-			if content, ok := msg.Payload["content"].(string); ok && strings.TrimSpace(content) != "" {
-				userMessages = append(userMessages, strings.TrimSpace(content))
-			}
-		}
-	}
-
-	// Add current message
-	userMessages = append(userMessages, strings.TrimSpace(currentMessage))
-
-	// Combine with separator
-	combined := strings.Join(userMessages, " | ")
-
-	// Truncate if too long
-	return truncateString(combined, maxUserMessageChars)
-}
-
-// truncateString truncates a string to maxLen characters, adding "..." if truncated
-func truncateString(s string, maxLen int) string {
-	if len(s) <= maxLen {
-		return s
-	}
-	if maxLen <= 3 {
-		return s[:maxLen]
-	}
-	return s[:maxLen-3] + "..."
-}
-
-// getSessionForDisplayName retrieves session data for display name generation
-func getSessionForDisplayName(projectName, sessionID string) (map[string]interface{}, error) {
-	if handlers.DynamicClient == nil {
-		return nil, fmt.Errorf("dynamic client not initialized")
-	}
-
-	gvr := handlers.GetAgenticSessionV1Alpha1Resource()
-	item, err := handlers.DynamicClient.Resource(gvr).Namespace(projectName).Get(
-		context.Background(), sessionID, metav1.GetOptions{},
-	)
-	if err != nil {
-		return nil, err
-	}
-
-	return item.Object, nil
-}
-
-// NOTE: GetSessionMessagesClaudeFormat removed - session continuation now uses
-// SDK's built-in resume functionality with persisted ~/.claude state
-// See: https://docs.claude.com/en/api/agent-sdk/sessions
diff --git a/components/backend/websocket/hub.go b/components/backend/websocket/hub.go
deleted file mode 100644
index e0cc79338..000000000
--- a/components/backend/websocket/hub.go
+++ /dev/null
@@ -1,202 +0,0 @@
-// Package websocket provides real-time WebSocket communication for session updates.
-package websocket
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"log"
-	"os"
-	"sync"
-	"time"
-
-	"github.com/gorilla/websocket"
-)
-
-// SessionWebSocketHub manages WebSocket connections for sessions
-type SessionWebSocketHub struct {
-	// Map of sessionID -> SessionConnection pointers
-	sessions map[string]map[*SessionConnection]bool
-	// Register new connections
-	register chan *SessionConnection
-	// Unregister connections
-	unregister chan *SessionConnection
-	// Broadcast messages to session
-	broadcast chan *SessionMessage
-	mu        sync.RWMutex
-}
-
-// SessionConnection represents a WebSocket connection to a session
-type SessionConnection struct {
-	SessionID string
-	Conn      *websocket.Conn
-	UserID    string
-	writeMu   sync.Mutex // Protects concurrent writes to Conn
-}
-
-// SessionMessage represents a message in a session
-type SessionMessage struct {
-	SessionID string                 `json:"sessionId"`
-	Type      string                 `json:"type"`
-	Timestamp string                 `json:"timestamp"`
-	Payload   map[string]interface{} `json:"payload"`
-	// Partial message support
-	Partial *PartialMessageInfo `json:"partial,omitempty"`
-}
-
-// PartialMessageInfo for fragmented messages
-type PartialMessageInfo struct {
-	ID    string `json:"id"`
-	Index int    `json:"index"`
-	Total int    `json:"total"`
-	Data  string `json:"data"`
-}
-
-// Package-level variables
-var (
-	Hub          *SessionWebSocketHub
-	StateBaseDir string
-)
-
-// Initialize WebSocket hub
-func init() {
-	Hub = &SessionWebSocketHub{
-		sessions:   make(map[string]map[*SessionConnection]bool),
-		register:   make(chan *SessionConnection),
-		unregister: make(chan *SessionConnection),
-		broadcast:  make(chan *SessionMessage),
-	}
-	go Hub.run()
-}
-
-// run starts the WebSocket hub
-func (h *SessionWebSocketHub) run() {
-	for {
-		select {
-		case conn := <-h.register:
-			h.mu.Lock()
-			if h.sessions[conn.SessionID] == nil {
-				h.sessions[conn.SessionID] = make(map[*SessionConnection]bool)
-			}
-			h.sessions[conn.SessionID][conn] = true
-			h.mu.Unlock()
-			log.Printf("WebSocket connection registered for session %s", conn.SessionID)
-
-		case conn := <-h.unregister:
-			h.mu.Lock()
-			if connections, exists := h.sessions[conn.SessionID]; exists {
-				if _, exists := connections[conn]; exists {
-					delete(connections, conn)
-					conn.Conn.Close()
-					if len(connections) == 0 {
-						delete(h.sessions, conn.SessionID)
-					}
-				}
-			}
-			h.mu.Unlock()
-			log.Printf("WebSocket connection unregistered for session %s", conn.SessionID)
-
-		case message := <-h.broadcast:
-			h.mu.RLock()
-			connections := h.sessions[message.SessionID]
-			h.mu.RUnlock()
-
-			if connections != nil {
-				messageData, _ := json.Marshal(message)
-				for sessionConn := range connections {
-					// Lock write mutex before writing
-					sessionConn.writeMu.Lock()
-					err := sessionConn.Conn.WriteMessage(websocket.TextMessage, messageData)
-					sessionConn.writeMu.Unlock()
-					if err != nil {
-						// Unregister in goroutine to avoid deadlock - hub select loop
-						// can only process one case at a time, so blocking send would hang
-						go func(conn *SessionConnection) {
-							h.unregister <- conn
-						}(sessionConn)
-					}
-				}
-			}
-
-			// Also persist to S3
-			go persistMessageToS3(message)
-		}
-	}
-}
-
-// SendMessageToSession sends a message to all connections for a session
-func SendMessageToSession(sessionID string, messageType string, payload map[string]interface{}) {
-	message := &SessionMessage{
-		SessionID: sessionID,
-		Type:      messageType,
-		Timestamp: time.Now().UTC().Format(time.RFC3339),
-		Payload:   payload,
-	}
-
-	Hub.broadcast <- message
-}
-
-// SendPartialMessage sends a fragmented message to a session
-func SendPartialMessage(sessionID string, partialID string, index, total int, data string) {
-	message := &SessionMessage{
-		SessionID: sessionID,
-		Type:      "message.partial",
-		Timestamp: time.Now().UTC().Format(time.RFC3339),
-		Payload:   map[string]interface{}{},
-		Partial: &PartialMessageInfo{
-			ID:    partialID,
-			Index: index,
-			Total: total,
-			Data:  data,
-		},
-	}
-
-	Hub.broadcast <- message
-}
-
-// Helper functions
-
-func persistMessageToS3(message *SessionMessage) {
-	// Write messages to per-project content service path as JSONL append for now
-	// Backend does not have project in this scope; persist to local state dir for durability
-	path := fmt.Sprintf("%s/sessions/%s/messages.jsonl", StateBaseDir, message.SessionID)
-	log.Printf("persistMessageToS3: path: %s", path)
-	b, _ := json.Marshal(message)
-	// Ensure dir
-	_ = os.MkdirAll(fmt.Sprintf("%s/sessions/%s", StateBaseDir, message.SessionID), 0o755)
-	f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
-	if err != nil {
-		log.Printf("persistMessage: open failed: %v", err)
-		return
-	}
-	defer f.Close()
-	if _, err := f.Write(append(b, '\n')); err != nil {
-		log.Printf("persistMessage: write failed: %v", err)
-	}
-}
-
-func retrieveMessagesFromS3(sessionID string) ([]SessionMessage, error) {
-	// Read from local state JSONL path for now
-	path := fmt.Sprintf("%s/sessions/%s/messages.jsonl", StateBaseDir, sessionID)
-	data, err := os.ReadFile(path)
-	if err != nil {
-		log.Printf("retrieveMessagesFromS3: read failed: %v", err)
-		if os.IsNotExist(err) {
-			return []SessionMessage{}, nil
-		}
-		return nil, err
-	}
-	lines := bytes.Split(data, []byte("\n"))
-	msgs := make([]SessionMessage, 0, len(lines))
-	for _, line := range lines {
-		line = bytes.TrimSpace(line)
-		if len(line) == 0 {
-			continue
-		}
-		var m SessionMessage
-		if err := json.Unmarshal(line, &m); err == nil {
-			msgs = append(msgs, m)
-		}
-	}
-	return msgs, nil
-}
diff --git a/components/backend/websocket/legacy_translator.go b/components/backend/websocket/legacy_translator.go
new file mode 100644
index 000000000..bd61d6c8f
--- /dev/null
+++ b/components/backend/websocket/legacy_translator.go
@@ -0,0 +1,114 @@
+package websocket
+
+import (
+	"ambient-code-backend/types"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"log"
+	"os"
+	"time"
+)
+
+// MigrateLegacySessionToAGUI converts old message format to AG-UI events
+// Creates a MESSAGES_SNAPSHOT from legacy messages and persists it
+func MigrateLegacySessionToAGUI(sessionID string) error {
+	// Check if session has legacy messages (JSONL format)
+	legacyPath := StateBaseDir + "/sessions/" + sessionID + "/messages.jsonl"
+	data, err := os.ReadFile(legacyPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// No legacy file, nothing to migrate
+			return nil
+		}
+		return err
+	}
+
+	log.Printf("LegacyMigration: Found legacy messages.jsonl for %s, converting to AG-UI", sessionID)
+
+	// Parse JSONL - each line is a complete message
+	var legacyMessages []map[string]interface{}
+	lines := splitLines(data)
+	for _, line := range lines {
+		if len(line) == 0 {
+			continue
+		}
+		var msg map[string]interface{}
+		if err := json.Unmarshal(line, &msg); err == nil {
+			legacyMessages = append(legacyMessages, msg)
+		}
+	}
+
+	// Convert to AG-UI Message format
+	messages := make([]types.Message, 0)
+
+	for _, legacyMsg := range legacyMessages {
+		msgType, _ := legacyMsg["type"].(string)
+		payload, _ := legacyMsg["payload"].(map[string]interface{})
+
+		switch msgType {
+		case "user_message":
+			content, _ := payload["content"].(string)
+			messages = append(messages, types.Message{
+				ID:      generateEventID(),
+				Role:    types.RoleUser,
+				Content: content,
+			})
+
+		case "agent.message":
+			// Check if it's a text message
+			if content, ok := payload["content"].(map[string]interface{}); ok {
+				textType, _ := content["type"].(string)
+				if textType == "text_block" {
+					text, _ := content["text"].(string)
+					messages = append(messages, types.Message{
+						ID:      generateEventID(),
+						Role:    types.RoleAssistant,
+						Content: text,
+					})
+				}
+			}
+			// Tool calls will be reconstructed from tool_result pairs
+
+			// system.message, agent.running, agent.waiting are not chat messages, skip
+		}
+	}
+
+	if len(messages) == 0 {
+		log.Printf("LegacyMigration: No chat messages found in legacy file")
+		return nil
+	}
+
+	log.Printf("LegacyMigration: Converted %d legacy messages to AG-UI format", len(messages))
+
+	// Create MESSAGES_SNAPSHOT event and persist it
+	snapshot := map[string]interface{}{
+		"type":      types.EventTypeMessagesSnapshot,
+		"threadId":  sessionID,
+		"runId":     "legacy-migration",
+		"timestamp": time.Now().UTC().Format(time.RFC3339Nano),
+		"messages":  messages,
+	}
+
+	// Persist to agui-events.jsonl
+	persistAGUIEventMap(sessionID, "legacy-migration", snapshot)
+
+	log.Printf("LegacyMigration: Persisted MESSAGES_SNAPSHOT with %d messages", len(messages))
+
+	// Rename legacy file to indicate it's been migrated
+	migratedPath := legacyPath + ".migrated"
+	if err := os.Rename(legacyPath, migratedPath); err != nil {
+		log.Printf("LegacyMigration: Warning - failed to rename legacy file: %v", err)
+	} else {
+		log.Printf("LegacyMigration: Renamed %s to %s", legacyPath, migratedPath)
+	}
+
+	return nil
+}
+
+// generateEventID creates a random ID for events
+func generateEventID() string {
+	b := make([]byte, 16)
+	rand.Read(b)
+	return hex.EncodeToString(b)
+}
diff --git a/components/frontend/Dockerfile b/components/frontend/Dockerfile
index c656ac5ac..b2e566825 100644
--- a/components/frontend/Dockerfile
+++ b/components/frontend/Dockerfile
@@ -1,6 +1,14 @@
 # Use Red Hat UBI Node.js 20 minimal image for dependencies
 FROM registry.access.redhat.com/ubi9/nodejs-20-minimal AS deps
 
+# Build arguments for metadata
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
 WORKDIR /app
 
 USER 0
@@ -12,6 +20,14 @@ RUN npm ci
 # Rebuild the source code only when needed
 FROM registry.access.redhat.com/ubi9/nodejs-20-minimal AS builder
 
+# Build arguments (need to redeclare for each stage)
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
 USER 0
 
 WORKDIR /app
@@ -25,17 +41,48 @@ COPY . .
 # Uncomment the following line in case you want to disable telemetry during the build.
 ENV NEXT_TELEMETRY_DISABLED=1
 
+# Make build metadata available to Next.js at build time
+ENV NEXT_PUBLIC_GIT_COMMIT=${GIT_COMMIT}
+ENV NEXT_PUBLIC_GIT_BRANCH=${GIT_BRANCH}
+ENV NEXT_PUBLIC_GIT_REPO=${GIT_REPO}
+ENV NEXT_PUBLIC_GIT_VERSION=${GIT_VERSION}
+ENV NEXT_PUBLIC_BUILD_DATE=${BUILD_DATE}
+ENV NEXT_PUBLIC_BUILD_USER=${BUILD_USER}
+
 RUN npm run build
 
 # Production image, copy all the files and run next
 FROM registry.access.redhat.com/ubi9/nodejs-20-minimal AS runner
 
+# Build arguments (need to redeclare for final stage)
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
+# Add labels to force cache invalidation and provide metadata
+LABEL git.commit="${GIT_COMMIT}"
+LABEL git.branch="${GIT_BRANCH}"
+LABEL git.version="${GIT_VERSION}"
+LABEL build.date="${BUILD_DATE}"
+LABEL build.user="${BUILD_USER}"
+
 WORKDIR /app
 
 ENV NODE_ENV=production
 # Uncomment the following line in case you want to disable telemetry during runtime.
 ENV NEXT_TELEMETRY_DISABLED=1
 
+# Build metadata as environment variables (NEXT_PUBLIC_ prefix makes them available to client)
+ENV NEXT_PUBLIC_GIT_COMMIT=${GIT_COMMIT}
+ENV NEXT_PUBLIC_GIT_BRANCH=${GIT_BRANCH}
+ENV NEXT_PUBLIC_GIT_REPO=${GIT_REPO}
+ENV NEXT_PUBLIC_GIT_VERSION=${GIT_VERSION}
+ENV NEXT_PUBLIC_BUILD_DATE=${BUILD_DATE}
+ENV NEXT_PUBLIC_BUILD_USER=${BUILD_USER}
+
 # Copy public assets
 COPY --from=builder /app/public ./public
 
diff --git a/components/frontend/next.config.js b/components/frontend/next.config.js
index bbab259ea..5ee112947 100644
--- a/components/frontend/next.config.js
+++ b/components/frontend/next.config.js
@@ -1,6 +1,9 @@
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  output: 'standalone'
+  output: 'standalone',
+  experimental: {
+    instrumentationHook: true,
+  }
 }
 
 module.exports = nextConfig
diff --git a/components/frontend/package-lock.json b/components/frontend/package-lock.json
index 82f2f638f..78539d3ad 100644
--- a/components/frontend/package-lock.json
+++ b/components/frontend/package-lock.json
@@ -30,6 +30,7 @@
         "lucide-react": "^0.542.0",
         "next": "15.5.9",
         "next-themes": "^0.4.6",
+        "python-struct": "^1.1.3",
         "react": "^19.1.0",
         "react-dom": "^19.1.0",
         "react-hook-form": "^7.62.0",
@@ -6257,6 +6258,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/long": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/long/-/long-4.0.0.tgz",
+      "integrity": "sha512-XsP+KhQif4bjX1kbuSiySJFNAehNxgLb6hPRGJ9QsUr8ajHkuXGdrHmFUTUUXhDwVX2R5bY4JNZEwbUiMhV+MA==",
+      "license": "Apache-2.0"
+    },
     "node_modules/longest-streak": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz",
@@ -8125,6 +8132,15 @@
         "node": ">=6"
       }
     },
+    "node_modules/python-struct": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/python-struct/-/python-struct-1.1.3.tgz",
+      "integrity": "sha512-UsI/mNvk25jRpGKYI38Nfbv84z48oiIWwG67DLVvjRhy8B/0aIK+5Ju5WOHgw/o9rnEmbAS00v4rgKFQeC332Q==",
+      "license": "MIT",
+      "dependencies": {
+        "long": "^4.0.0"
+      }
+    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
diff --git a/components/frontend/package.json b/components/frontend/package.json
index 9deafaa57..7f0109453 100644
--- a/components/frontend/package.json
+++ b/components/frontend/package.json
@@ -31,6 +31,7 @@
     "lucide-react": "^0.542.0",
     "next": "15.5.9",
     "next-themes": "^0.4.6",
+    "python-struct": "^1.1.3",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-hook-form": "^7.62.0",
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/events/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/events/route.ts
new file mode 100644
index 000000000..d7f27ec53
--- /dev/null
+++ b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/events/route.ts
@@ -0,0 +1,94 @@
+/**
+ * AG-UI SSE Events Proxy
+ * Proxies the backend AG-UI SSE stream through Next.js for Bearer auth compatibility.
+ * 
+ * Browser EventSource cannot set Authorization headers, so we proxy through
+ * the Next.js same-origin API to inject auth headers server-side.
+ * 
+ * See: https://docs.ag-ui.com/quickstart/introduction
+ */
+
+import { BACKEND_URL } from '@/lib/config'
+import { buildForwardHeadersAsync } from '@/lib/auth'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ name: string; sessionName: string }> },
+) {
+  const { name, sessionName } = await params
+  const url = new URL(request.url)
+  const runId = url.searchParams.get('runId') || ''
+
+  // Build auth headers from the incoming request
+  const headers = await buildForwardHeadersAsync(request)
+
+  // Remove Content-Type as we're making a GET request for SSE
+  delete headers['Content-Type']
+
+  // Build backend URL
+  let backendUrl = `${BACKEND_URL}/projects/${encodeURIComponent(name)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/events`
+  if (runId) {
+    backendUrl += `?runId=${encodeURIComponent(runId)}`
+  }
+
+  try {
+    // Fetch from backend SSE endpoint
+    const response = await fetch(backendUrl, {
+      method: 'GET',
+      headers: {
+        ...headers,
+        Accept: 'text/event-stream',
+        'Cache-Control': 'no-cache',
+      },
+      // @ts-expect-error - Node.js fetch supports duplex for streaming
+      duplex: 'half',
+    })
+
+    if (!response.ok) {
+      const errorText = await response.text()
+      return new Response(JSON.stringify({ error: errorText }), {
+        status: response.status,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    // Pipe the SSE stream through
+    const { readable, writable } = new TransformStream()
+    
+    // Forward the body in a non-blocking way
+    if (response.body) {
+      response.body.pipeTo(writable).catch((err) => {
+        // ResponseAborted is normal when client disconnects, don't log as error
+        if (err?.name !== 'AbortError' && !err?.message?.includes('ResponseAborted')) {
+          console.error('AG-UI SSE proxy pipe error:', err)
+        }
+      })
+    }
+
+    return new Response(readable, {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-store, must-revalidate',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      },
+    })
+  } catch (error) {
+    // Don't log ECONNREFUSED as error during backend restarts - it's expected
+    const isConnRefused = error && typeof error === 'object' && 'code' in error && error.code === 'ECONNREFUSED'
+    if (!isConnRefused) {
+      console.error('AG-UI SSE proxy error:', error)
+    } else {
+      console.log('Backend temporarily unavailable (ECONNREFUSED), client will retry')
+    }
+    return new Response(
+      JSON.stringify({ error: 'Failed to connect to AG-UI event stream' }),
+      { status: 503, headers: { 'Content-Type': 'application/json' } },
+    )
+  }
+}
+
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/history/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/history/route.ts
new file mode 100644
index 000000000..f763a7a33
--- /dev/null
+++ b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/history/route.ts
@@ -0,0 +1,36 @@
+/**
+ * AG-UI History Endpoint Proxy
+ * Returns compacted message history for a session.
+ * 
+ * See: https://docs.ag-ui.com/concepts/serialization
+ */
+
+import { BACKEND_URL } from '@/lib/config'
+import { buildForwardHeadersAsync } from '@/lib/auth'
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ name: string; sessionName: string }> },
+) {
+  const { name, sessionName } = await params
+  const url = new URL(request.url)
+  const runId = url.searchParams.get('runId') || ''
+  const headers = await buildForwardHeadersAsync(request)
+
+  let backendUrl = `${BACKEND_URL}/projects/${encodeURIComponent(name)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/history`
+  if (runId) {
+    backendUrl += `?runId=${encodeURIComponent(runId)}`
+  }
+
+  const resp = await fetch(backendUrl, {
+    method: 'GET',
+    headers,
+  })
+
+  const data = await resp.text()
+  return new Response(data, {
+    status: resp.status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/interrupt/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/interrupt/route.ts
new file mode 100644
index 000000000..25fe0d5c5
--- /dev/null
+++ b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/interrupt/route.ts
@@ -0,0 +1,39 @@
+/**
+ * AG-UI Interrupt Endpoint Proxy
+ * Forwards interrupt signal to backend to stop Claude SDK execution.
+ * 
+ * See: https://platform.claude.com/docs/en/agent-sdk/python#methods
+ */
+
+import { BACKEND_URL } from '@/lib/config'
+import { buildForwardHeadersAsync } from '@/lib/auth'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ name: string; sessionName: string }> },
+) {
+  const { name, sessionName } = await params
+  const headers = await buildForwardHeadersAsync(request)
+  const body = await request.text()
+
+  const backendUrl = `${BACKEND_URL}/projects/${encodeURIComponent(name)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/interrupt`
+
+  const resp = await fetch(backendUrl, {
+    method: 'POST',
+    headers: { 
+      ...headers, 
+      'Content-Type': 'application/json',
+    },
+    body,
+  })
+
+  const data = await resp.text()
+  return new Response(data, {
+    status: resp.status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/run/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/run/route.ts
new file mode 100644
index 000000000..f3f303358
--- /dev/null
+++ b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/run/route.ts
@@ -0,0 +1,41 @@
+/**
+ * AG-UI Run Endpoint Proxy
+ * Creates a new agent run and returns metadata immediately.
+ * Events are broadcast to GET /agui/events subscribers (middleware pattern).
+ * 
+ * See: https://docs.ag-ui.com/concepts/architecture
+ */
+
+import { BACKEND_URL } from '@/lib/config'
+import { buildForwardHeadersAsync } from '@/lib/auth'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ name: string; sessionName: string }> },
+) {
+  const { name, sessionName } = await params
+  const headers = await buildForwardHeadersAsync(request)
+  const body = await request.text()
+
+  const backendUrl = `${BACKEND_URL}/projects/${encodeURIComponent(name)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/run`
+
+  const resp = await fetch(backendUrl, {
+    method: 'POST',
+    headers: { 
+      ...headers, 
+      'Content-Type': 'application/json',
+    },
+    body,
+  })
+
+  // Backend returns JSON metadata immediately (not SSE stream)
+  // Events are broadcast to GET /agui/events subscribers
+  const data = await resp.text()
+  return new Response(data, {
+    status: resp.status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/runs/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/runs/route.ts
new file mode 100644
index 000000000..344c7e9fa
--- /dev/null
+++ b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/agui/runs/route.ts
@@ -0,0 +1,31 @@
+/**
+ * AG-UI Runs Endpoint Proxy
+ * Returns list of runs for a session (thread).
+ * 
+ * See: https://docs.ag-ui.com/concepts/serialization
+ */
+
+import { BACKEND_URL } from '@/lib/config'
+import { buildForwardHeadersAsync } from '@/lib/auth'
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ name: string; sessionName: string }> },
+) {
+  const { name, sessionName } = await params
+  const headers = await buildForwardHeadersAsync(request)
+
+  const backendUrl = `${BACKEND_URL}/projects/${encodeURIComponent(name)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/runs`
+
+  const resp = await fetch(backendUrl, {
+    method: 'GET',
+    headers,
+  })
+
+  const data = await resp.text()
+  return new Response(data, {
+    status: resp.status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/messages/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/messages/route.ts
deleted file mode 100644
index 977ce9741..000000000
--- a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/messages/route.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { BACKEND_URL } from '@/lib/config'
-import { buildForwardHeadersAsync } from '@/lib/auth'
-
-export async function GET(
-  request: Request,
-  { params }: { params: Promise<{ name: string; sessionName: string }> },
-) {
-  const { name, sessionName } = await params
-  const headers = await buildForwardHeadersAsync(request)
-  const resp = await fetch(`${BACKEND_URL}/projects/${encodeURIComponent(name)}/sessions/${encodeURIComponent(sessionName)}/messages`, {
-    method: 'GET',
-    headers,
-  })
-  const data = await resp.text()
-  return new Response(data, { status: resp.status, headers: { 'Content-Type': 'application/json' } })
-}
-
-export async function POST(
-  request: Request,
-  { params }: { params: Promise<{ name: string; sessionName: string }> },
-) {
-  const { name, sessionName } = await params
-  const headers = await buildForwardHeadersAsync(request)
-  const body = await request.text()
-  const resp = await fetch(`${BACKEND_URL}/projects/${encodeURIComponent(name)}/sessions/${encodeURIComponent(sessionName)}/messages`, {
-    method: 'POST',
-    headers: { ...headers, 'Content-Type': 'application/json' },
-    body,
-  })
-  const data = await resp.text()
-  return new Response(data, { status: resp.status, headers: { 'Content-Type': 'application/json' } })
-}
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/workspace/upload/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/workspace/upload/route.ts
index 298026029..a0abc32ff 100644
--- a/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/workspace/upload/route.ts
+++ b/components/frontend/src/app/api/projects/[name]/agentic-sessions/[sessionName]/workspace/upload/route.ts
@@ -256,9 +256,6 @@ async function compressImageIfNeeded(
     }
 
     const finalSize = compressed.byteLength;
-    console.log(
-      `Compressed ${contentType} image: ${originalSize} bytes -> ${finalSize} bytes (${Math.round((finalSize / originalSize) * 100)}%)`
-    );
 
     // Convert Node.js Buffer to ArrayBuffer by creating a new ArrayBuffer and copying data
     const arrayBuffer = new ArrayBuffer(finalSize);
diff --git a/components/frontend/src/app/api/projects/[name]/agentic-sessions/route.ts b/components/frontend/src/app/api/projects/[name]/agentic-sessions/route.ts
index 7bef7fd5c..1f6a43680 100644
--- a/components/frontend/src/app/api/projects/[name]/agentic-sessions/route.ts
+++ b/components/frontend/src/app/api/projects/[name]/agentic-sessions/route.ts
@@ -31,14 +31,6 @@ export async function POST(
     const body = await request.text();
     const headers = await buildForwardHeadersAsync(request);
     
-    console.log('[API Route] Creating session for project:', name);
-    console.log('[API Route] Auth headers present:', {
-      hasUser: !!headers['X-Forwarded-User'],
-      hasUsername: !!headers['X-Forwarded-Preferred-Username'],
-      hasToken: !!headers['X-Forwarded-Access-Token'],
-      hasEmail: !!headers['X-Forwarded-Email'],
-    });
-    
     const response = await fetch(`${BACKEND_URL}/projects/${encodeURIComponent(name)}/agentic-sessions`, {
       method: 'POST',
       headers,
@@ -46,7 +38,6 @@ export async function POST(
     });
     
     const text = await response.text();
-    console.log('[API Route] Backend response status:', response.status);
     if (!response.ok) {
       console.error('[API Route] Backend error:', text);
     }
diff --git a/components/frontend/src/app/projects/[name]/sessions/[sessionName]/hooks/use-workflow-management.ts b/components/frontend/src/app/projects/[name]/sessions/[sessionName]/hooks/use-workflow-management.ts
index 69567908d..654823911 100644
--- a/components/frontend/src/app/projects/[name]/sessions/[sessionName]/hooks/use-workflow-management.ts
+++ b/components/frontend/src/app/projects/[name]/sessions/[sessionName]/hooks/use-workflow-management.ts
@@ -48,17 +48,8 @@ export function useWorkflowManagement({
         throw new Error(errorData.error || "Failed to update workflow");
       }
       
-      // 2. Send WebSocket message to trigger workflow clone and restart
-      await fetch(`/api/projects/${projectName}/agentic-sessions/${sessionName}/messages`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          type: "workflow_change",
-          gitUrl: pendingWorkflow.gitUrl,
-          branch: pendingWorkflow.branch,
-          path: pendingWorkflow.path || "",
-        }),
-      });
+      // Note: Workflow clone and restart handled by operator
+      // Initial workflow prompt auto-executed via AG-UI pattern (POST /agui/run)
       
       successToast(`Activating workflow: ${pendingWorkflow.name}`);
       setActiveWorkflow(pendingWorkflow.id);
diff --git a/components/frontend/src/app/projects/[name]/sessions/[sessionName]/lib/message-adapter.ts b/components/frontend/src/app/projects/[name]/sessions/[sessionName]/lib/message-adapter.ts
deleted file mode 100644
index e5d346824..000000000
--- a/components/frontend/src/app/projects/[name]/sessions/[sessionName]/lib/message-adapter.ts
+++ /dev/null
@@ -1,228 +0,0 @@
-import type { SessionMessage } from "@/types";
-import type { MessageObject, ToolUseMessages } from "@/types/agentic-session";
-import type { RawWireMessage, InnerEnvelope, ToolUseBlockWithTimestamp, ToolResultBlockWithTimestamp } from "./types";
-
-/**
- * Converts raw wire messages from the backend into structured MessageObject and ToolUseMessages
- * for display in the UI. This handles all the complex message parsing and transformation logic.
- */
-export function adaptSessionMessages(
-  messages: SessionMessage[],
-  isInteractive: boolean = false
-): Array<MessageObject | ToolUseMessages> {
-  try {
-    const toolUseBlocks: ToolUseBlockWithTimestamp[] = [];
-    const toolResultBlocks: ToolResultBlockWithTimestamp[] = [];
-    const agenticMessages: MessageObject[] = [];
-
-  for (const raw of messages as RawWireMessage[]) {
-    const envelope: InnerEnvelope = ((raw?.payload as InnerEnvelope) ?? (raw as unknown as InnerEnvelope)) || {};
-    const innerType: string = (raw as unknown as InnerEnvelope)?.type || envelope.type || "";
-    const innerTs: string = raw?.timestamp || envelope.timestamp || new Date().toISOString();
-    const payloadValue = envelope.payload;
-    const innerPayload: Record<string, unknown> = (payloadValue && typeof payloadValue === 'object' && !Array.isArray(payloadValue))
-      ? (payloadValue as Record<string, unknown>)
-      : ((typeof envelope === 'object' ? (envelope as unknown as Record<string, unknown>) : {}) as Record<string, unknown>);
-    const partial = (envelope.partial as InnerEnvelope["partial"]) || ((raw as unknown as { partial?: InnerEnvelope["partial"] })?.partial) || undefined;
-
-    switch (innerType) {
-      case "message.partial": {
-        const text = partial?.data || "";
-        if (text) {
-          agenticMessages.push({
-            type: "agent_message",
-            content: { type: "text_block", text },
-            model: "claude",
-            timestamp: innerTs,
-          });
-        }
-        break;
-      }
-      case "agent.message": {
-        if (partial?.data) {
-          const text = String(partial.data || "");
-          if (text) {
-            agenticMessages.push({
-              type: "agent_message",
-              content: { type: "text_block", text },
-              model: "claude",
-              timestamp: innerTs,
-            });
-            break;
-          }
-        }
-
-        const toolName = (innerPayload?.tool as string | undefined);
-        const toolInput = (innerPayload?.input as Record<string, unknown> | undefined) || {};
-        const providedId = (innerPayload?.id as string | undefined);
-        const result = innerPayload?.tool_result as unknown as { tool_use_id?: string; content?: unknown; is_error?: boolean } | undefined;
-        
-        if (toolName) {
-          const id = providedId ? String(providedId) : String(envelope?.seq ?? `${toolName}-${toolUseBlocks.length}`);
-          toolUseBlocks.push({
-            block: { type: "tool_use_block", id, name: toolName, input: toolInput },
-            timestamp: innerTs,
-          });
-        } else if (result?.tool_use_id) {
-          toolResultBlocks.push({
-            block: {
-              type: "tool_result_block",
-              tool_use_id: String(result.tool_use_id),
-              content: (result.content as string | Array<Record<string, unknown>> | null | undefined) ?? null,
-              is_error: Boolean(result.is_error),
-            },
-            timestamp: innerTs,
-          });
-        } else if ((innerPayload as Record<string, unknown>)?.type === 'result.message') {
-          let rp: Record<string, unknown> = (innerPayload.payload as Record<string, unknown>) || {};
-          if (rp && typeof rp === 'object' && 'payload' in rp && rp.payload && typeof rp.payload === 'object') {
-            rp = rp.payload as Record<string, unknown>;
-          }
-          agenticMessages.push({
-            type: "result_message",
-            subtype: String(rp.subtype || ""),
-            duration_ms: Number(rp.duration_ms || 0),
-            duration_api_ms: Number(rp.duration_api_ms || 0),
-            is_error: Boolean(rp.is_error || false),
-            num_turns: Number(rp.num_turns || 0),
-            session_id: String(rp.session_id || ""),
-            total_cost_usd: (typeof rp.total_cost_usd === 'number' ? rp.total_cost_usd : null),
-            usage: (typeof rp.usage === 'object' && rp.usage ? rp.usage as Record<string, unknown> : null),
-            result: (typeof rp.result === 'string' ? rp.result : null),
-            timestamp: innerTs,
-          });
-          if (typeof rp.result === 'string' && rp.result.trim()) {
-            agenticMessages.push({
-              type: "agent_message",
-              content: { type: "text_block", text: String(rp.result) },
-              model: "claude",
-              timestamp: innerTs,
-            });
-          }
-        } else {
-          const envelopePayload = envelope.payload;
-          const contentText = (innerPayload.content as Record<string, unknown> | undefined)?.text;
-          const messageText = innerPayload.message;
-          const nestedContentText = (innerPayload.payload as Record<string, unknown> | undefined)?.content as Record<string, unknown> | undefined;
-          const text = (typeof envelopePayload === 'string')
-            ? String(envelopePayload)
-            : (
-                (typeof contentText === 'string' ? String(contentText) : undefined)
-                || (typeof messageText === 'string' ? String(messageText) : undefined)
-                || (typeof nestedContentText?.text === 'string' ? String(nestedContentText.text) : '')
-              );
-          if (text) {
-            agenticMessages.push({
-              type: "agent_message",
-              content: { type: "text_block", text },
-              model: "claude",
-              timestamp: innerTs,
-            });
-          }
-        }
-        break;
-      }
-      case "system.message": {
-        let text = "";
-        let isDebug = false;
-        
-        // The envelope object might have message/payload at different levels
-        // Try envelope.payload first, then fall back to envelope itself
-        const envelopeObj = envelope as { message?: string; payload?: string | { message?: string; payload?: string; debug?: boolean }; debug?: boolean };
-        
-        // Check if envelope.payload is a string
-        if (typeof envelopeObj.payload === 'string') {
-          text = envelopeObj.payload;
-        }
-        // Check if envelope.payload is an object with message or payload
-        else if (typeof envelopeObj.payload === 'object' && envelopeObj.payload !== null) {
-          const payloadObj = envelopeObj.payload as { message?: string; payload?: string; debug?: boolean };
-          text = payloadObj.message || (typeof payloadObj.payload === 'string' ? payloadObj.payload : "");
-          isDebug = payloadObj.debug === true;
-        }
-        // Fall back to envelope.message directly
-        else if (typeof envelopeObj.message === 'string') {
-          text = envelopeObj.message;
-        }
-        
-        if (envelopeObj.debug === true) {
-          isDebug = true;
-        }
-        
-        // Always create a system message - show the raw envelope if we couldn't extract text
-        agenticMessages.push({
-          type: "system_message",
-          subtype: "system.message",
-          data: { 
-            message: text || `[system event: ${JSON.stringify(envelope)}]`,
-            debug: isDebug 
-          },
-          timestamp: innerTs,
-        });
-        break;
-      }
-      case "user.message":
-      case "user_message": {
-        const text = (innerPayload?.content as string | undefined) || "";
-        if (text) {
-          agenticMessages.push({
-            type: "user_message",
-            content: { type: "text_block", text },
-            timestamp: innerTs,
-          });
-        }
-        break;
-      }
-      case "agent.running": {
-        agenticMessages.push({ type: "agent_running", timestamp: innerTs });
-        break;
-      }
-      case "agent.waiting": {
-        agenticMessages.push({ type: "agent_waiting", timestamp: innerTs });
-        break;
-      }
-      default: {
-        agenticMessages.push({
-          type: "system_message",
-          subtype: innerType || "unknown",
-          data: innerPayload || {},
-          timestamp: innerTs,
-        });
-      }
-    }
-  }
-
-  const toolUseMessages: ToolUseMessages[] = [];
-  for (const tu of toolUseBlocks) {
-    const match = toolResultBlocks.find((tr) => tr.block.tool_use_id === tu.block.id);
-    if (match) {
-      toolUseMessages.push({
-        type: "tool_use_messages",
-        timestamp: tu.timestamp,
-        toolUseBlock: tu.block,
-        resultBlock: match.block,
-      });
-    } else {
-      toolUseMessages.push({
-        type: "tool_use_messages",
-        timestamp: tu.timestamp,
-        toolUseBlock: tu.block,
-        resultBlock: { type: "tool_result_block", tool_use_id: tu.block.id, content: null, is_error: false },
-      });
-    }
-  }
-
-    const all = [...agenticMessages, ...toolUseMessages];
-    const sorted = all.sort((a, b) => {
-      const at = new Date(a.timestamp || 0).getTime();
-      const bt = new Date(b.timestamp || 0).getTime();
-      return at - bt;
-    });
-    
-    return isInteractive ? sorted.filter((m) => m.type !== "result_message") : sorted;
-  } catch (error) {
-    console.error('Failed to adapt session messages:', error);
-    return []; // Return empty array on error
-  }
-}
-
diff --git a/components/frontend/src/app/projects/[name]/sessions/[sessionName]/page.tsx b/components/frontend/src/app/projects/[name]/sessions/[sessionName]/page.tsx
index a6a46aee5..8c964eeb2 100644
--- a/components/frontend/src/app/projects/[name]/sessions/[sessionName]/page.tsx
+++ b/components/frontend/src/app/projects/[name]/sessions/[sessionName]/page.tsx
@@ -78,20 +78,19 @@ import { McpIntegrationsAccordion } from "./components/accordions/mcp-integratio
 import { useGitOperations } from "./hooks/use-git-operations";
 import { useWorkflowManagement } from "./hooks/use-workflow-management";
 import { useFileOperations } from "./hooks/use-file-operations";
-import { adaptSessionMessages } from "./lib/message-adapter";
 import type { DirectoryOption, DirectoryRemote } from "./lib/types";
 
-import type { SessionMessage } from "@/types";
-import type { MessageObject, ToolUseMessages } from "@/types/agentic-session";
+import type { MessageObject, ToolUseMessages, HierarchicalToolMessage } from "@/types/agentic-session";
+import type { AGUIToolCall } from "@/types/agui";
+
+// AG-UI streaming
+import { useAGUIStream } from "@/hooks/use-agui-stream";
 
 // React Query hooks
 import {
   useSession,
-  useSessionMessages,
   useStopSession,
   useDeleteSession,
-  useSendChatMessage,
-  useSendControlMessage,
   useSessionK8sResources,
   useContinueSession,
 } from "@/services/queries";
@@ -191,11 +190,6 @@ export default function ProjectSessionDetailPage({
     error,
     refetch: refetchSession,
   } = useSession(projectName, sessionName);
-  const { data: messages = [] } = useSessionMessages(
-    projectName,
-    sessionName,
-    session?.status?.phase,
-  );
   const { data: k8sResources } = useSessionK8sResources(
     projectName,
     sessionName,
@@ -203,8 +197,60 @@ export default function ProjectSessionDetailPage({
   const stopMutation = useStopSession();
   const deleteMutation = useDeleteSession();
   const continueMutation = useContinueSession();
-  const sendChatMutation = useSendChatMessage();
-  const sendControlMutation = useSendControlMessage();
+
+  // AG-UI streaming hook - replaces useSessionMessages and useSendChatMessage
+  // Note: autoConnect is intentionally false to avoid SSR hydration mismatch
+  // Connection is triggered manually in useEffect after client hydration
+  const aguiStream = useAGUIStream({
+    projectName: projectName || "",
+    sessionName: sessionName || "",
+    autoConnect: false, // Manual connection after hydration
+    onError: (err) => console.error("AG-UI stream error:", err),
+  });
+  const aguiState = aguiStream.state;
+  const aguiSendMessage = aguiStream.sendMessage;
+  const aguiInterrupt = aguiStream.interrupt;
+  const isRunActive = aguiStream.isRunActive;
+  const aguiConnectRef = useRef(aguiStream.connect);
+  
+  // Keep connect ref up to date
+  useEffect(() => {
+    aguiConnectRef.current = aguiStream.connect;
+  }, [aguiStream.connect]);
+
+  // Connect to AG-UI event stream for history and live updates
+  // AG-UI pattern: GET /agui/events streams ALL thread events (past + future)
+  // POST /agui/run creates runs, events broadcast to GET subscribers
+  const hasConnectedRef = useRef(false);
+  useEffect(() => {
+    if (!projectName || !sessionName) return;
+    
+    // Connect once on mount and keep connection open
+    if (!hasConnectedRef.current) {
+      hasConnectedRef.current = true;
+      aguiConnectRef.current();
+    }
+  }, [projectName, sessionName]);
+
+  // Auto-send initial prompt (handles session start, workflow activation, restarts)
+  // AG-UI pattern: Client (or backend) initiates runs via POST /agui/run
+  const lastProcessedPromptRef = useRef<string>("");
+  
+  useEffect(() => {
+    if (!session || !aguiSendMessage) return;
+    
+    const initialPrompt = session?.spec?.initialPrompt;
+    
+    // NOTE: Initial prompt execution handled by backend auto-trigger (StartSession handler)
+    // Backend waits for subscriber before executing, ensuring events are received
+    // This works for both UI and headless/API usage
+    
+    // Track that we've seen this prompt (for workflow changes)
+    if (initialPrompt && lastProcessedPromptRef.current !== initialPrompt) {
+      lastProcessedPromptRef.current = initialPrompt;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session?.spec?.initialPrompt, session?.status?.phase, aguiState.messages.length, aguiState.status]);
 
   // Workflow management hook
   const workflowManagement = useWorkflowManagement({
@@ -460,10 +506,10 @@ export default function ProjectSessionDetailPage({
 
   // Track when first message loads
   useEffect(() => {
-    if (messages && messages.length > 0 && !firstMessageLoaded) {
+    if (aguiState.messages && aguiState.messages.length > 0 && !firstMessageLoaded) {
       setFirstMessageLoaded(true);
     }
-  }, [messages, firstMessageLoaded]);
+  }, [aguiState.messages, firstMessageLoaded]);
 
   // Load active workflow and remotes from session
   useEffect(() => {
@@ -548,13 +594,365 @@ export default function ProjectSessionDetailPage({
     );
   };
 
-  // Convert messages using extracted adapter
-  const streamMessages: Array<MessageObject | ToolUseMessages> = useMemo(() => {
-    return adaptSessionMessages(
-      messages as SessionMessage[],
-      session?.spec?.interactive || false,
-    );
-  }, [messages, session?.spec?.interactive]);
+  // Convert AG-UI messages to display format with hierarchical tool call rendering
+  const streamMessages: Array<MessageObject | ToolUseMessages | HierarchicalToolMessage> = useMemo(() => {
+    
+    // Helper function to parse tool arguments
+    const parseToolArgs = (args: string | undefined): Record<string, unknown> => {
+      if (!args) return {};
+      try {
+        const parsed = JSON.parse(args);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          return parsed as Record<string, unknown>;
+        }
+        return { value: parsed };
+      } catch {
+        return { _raw: String(args || '') };
+      }
+    };
+
+    // Helper function to create a tool message from a tool call
+    const createToolMessage = (
+      tc: AGUIToolCall,
+      timestamp: string
+    ): ToolUseMessages => {
+      const toolInput = parseToolArgs(tc.args);
+      return {
+        type: "tool_use_messages",
+        timestamp,
+        toolUseBlock: {
+          type: "tool_use_block",
+          id: tc.id,
+          name: tc.name,
+          input: toolInput,
+        },
+        resultBlock: {
+          type: "tool_result_block",
+          tool_use_id: tc.id,
+          content: tc.result || null,
+          is_error: tc.status === "error",
+        },
+      };
+    };
+
+    const result: Array<MessageObject | ToolUseMessages | HierarchicalToolMessage> = [];
+    
+    // Phase A: Collect all tool calls from all messages for hierarchy building
+    const allToolCalls = new Map<string, { tc: AGUIToolCall; timestamp: string }>();
+    
+    for (const msg of aguiState.messages) {
+      const timestamp = msg.timestamp || new Date().toISOString();
+      
+      if (msg.toolCalls && Array.isArray(msg.toolCalls)) {
+        for (const tc of msg.toolCalls) {
+          if (tc && tc.id && tc.name) {
+            allToolCalls.set(tc.id, { tc, timestamp });
+          }
+        }
+      }
+    }
+    
+    // Add currently streaming tool call to the map if present
+    // This ensures streaming tools (both parents and children) are included in hierarchy
+    // CRITICAL: Don't require name - add even if name is null to prevent orphaned children
+    if (aguiState.currentToolCall?.id) {
+      const streamingToolId = aguiState.currentToolCall.id;
+      const streamingParentId = aguiState.currentToolCall.parentToolUseId;
+      const toolName = aguiState.currentToolCall.name || "unknown_tool";  // Default if null
+      
+      // Create a pseudo-tool-call for the streaming tool
+      const streamingTC: AGUIToolCall = {
+        id: streamingToolId,
+        name: toolName,
+        args: aguiState.currentToolCall.args || "",
+        type: "function",
+        parentToolUseId: streamingParentId,
+        status: "running",
+      };
+      
+      if (!allToolCalls.has(streamingToolId)) {
+        allToolCalls.set(streamingToolId, { 
+          tc: streamingTC, 
+          timestamp: new Date().toISOString() 
+        });
+      }
+    }
+    
+    // Add pending children to render map so they show during streaming!
+    // These are children that finished before their parent tool finished
+    if (aguiState.pendingChildren && aguiState.pendingChildren.size > 0) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      for (const [parentId, children] of aguiState.pendingChildren.entries()) {
+        for (const childMsg of children) {
+          if (childMsg.toolCalls) {
+            for (const tc of childMsg.toolCalls) {
+              if (!allToolCalls.has(tc.id)) {
+                allToolCalls.set(tc.id, {
+                  tc: tc,
+                  timestamp: new Date().toISOString(),
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+    
+    // Phase B: Build parent-child relationships
+    const topLevelTools = new Set<string>();
+    const childrenByParent = new Map<string, string[]>();
+    
+    for (const [toolId, { tc }] of allToolCalls) {
+      if (tc.parentToolUseId) {
+        // This is a child tool call
+        if (!childrenByParent.has(tc.parentToolUseId)) {
+          childrenByParent.set(tc.parentToolUseId, []);
+        }
+        childrenByParent.get(tc.parentToolUseId)!.push(toolId);
+      } else {
+        // This is a top-level tool call
+        topLevelTools.add(toolId);
+      }
+    }
+    
+    // Handle orphaned children - but DON'T promote to top-level if parent is streaming
+    for (const [toolId, { tc }] of allToolCalls) {
+      if (tc.parentToolUseId && !allToolCalls.has(tc.parentToolUseId)) {
+        // Check if parent is the currently streaming tool
+        if (aguiState.currentToolCall?.id === tc.parentToolUseId) {
+          // Don't promote to top-level - parent is streaming and will appear
+        } else {
+          // Parent truly not found, render as top-level (fallback)
+          console.warn(`  ⚠️ Orphaned child: ${tc.name} (${toolId.substring(0, 8)}) - parent ${tc.parentToolUseId.substring(0, 8)} not found`);
+          topLevelTools.add(toolId);
+        }
+      }
+    }
+    
+    // Track which tool calls we've already rendered
+    const renderedToolCalls = new Set<string>();
+    
+    // Phase C: Process messages and build hierarchical structure
+    for (const msg of aguiState.messages) {
+      const timestamp = msg.timestamp || new Date().toISOString();
+      
+      // Handle text content by role
+      if (msg.role === "user") {
+        result.push({
+          type: "user_message",
+          content: { type: "text_block", text: msg.content || "" },
+          timestamp,
+        });
+      } else if (msg.role === "assistant") {
+        // Check if this is a thinking block (from RAW event)
+        const metadata = msg.metadata as Record<string, unknown> | undefined;
+        if (metadata?.type === "thinking_block") {
+          result.push({
+            type: "agent_message",
+            content: {
+              type: "thinking_block",
+              thinking: metadata.thinking as string || "",
+              signature: metadata.signature as string || "",
+            },
+            model: "claude",
+            timestamp,
+          });
+        } else if (msg.content) {
+          // Only push text message if there's actual content
+          result.push({
+            type: "agent_message",
+            content: { type: "text_block", text: msg.content },
+            model: "claude",
+            timestamp,
+          });
+        }
+      } else if (msg.role === "tool") {
+        // Standalone tool results (not from toolCalls array)
+        if (msg.toolCallId && !allToolCalls.has(msg.toolCallId)) {
+          result.push({
+            type: "tool_use_messages",
+            timestamp,
+            toolUseBlock: {
+              type: "tool_use_block",
+              id: msg.toolCallId,
+              name: msg.name || "tool",
+              input: {},
+            },
+            resultBlock: {
+              type: "tool_result_block",
+              tool_use_id: msg.toolCallId,
+              content: msg.content || null,
+              is_error: false,
+            },
+          });
+        }
+      } else if (msg.role === "system") {
+        result.push({
+          type: "system_message",
+          subtype: "system.message",
+          data: { message: msg.content || "" },
+          timestamp,
+        });
+      }
+      
+      // Handle tool calls embedded in this message
+      if (msg.toolCalls && Array.isArray(msg.toolCalls)) {
+        for (const tc of msg.toolCalls) {
+          if (!tc || !tc.id || !tc.name) continue;
+          
+          // Skip if already rendered or if it's a child (will be rendered inside parent)
+          if (renderedToolCalls.has(tc.id)) {
+            continue;
+          }
+          if (!topLevelTools.has(tc.id)) {
+            continue;
+          }
+          
+          // Build children array for this tool call
+          const childIds = childrenByParent.get(tc.id) || [];
+          
+          const children: ToolUseMessages[] = childIds
+            .map(childId => {
+              const childData = allToolCalls.get(childId);
+              if (!childData) return null;
+              renderedToolCalls.add(childId);
+              return createToolMessage(childData.tc, childData.timestamp);
+            })
+            .filter((c): c is ToolUseMessages => c !== null);
+          
+          // Create the hierarchical tool message
+          const toolInput = parseToolArgs(tc.args);
+          
+          const toolMessage: HierarchicalToolMessage = {
+            type: "tool_use_messages",
+            timestamp,
+            toolUseBlock: {
+              type: "tool_use_block",
+              id: tc.id,
+              name: tc.name,
+              input: toolInput,
+            },
+            resultBlock: {
+              type: "tool_result_block",
+              tool_use_id: tc.id,
+              content: tc.result || null,
+              is_error: tc.status === "error",
+            },
+            children: children.length > 0 ? children : undefined,
+          };
+          
+          result.push(toolMessage);
+          renderedToolCalls.add(tc.id);
+        }
+      }
+    }
+    
+    // Add streaming message if currently streaming
+    if (aguiState.currentMessage?.content) {
+      result.push({
+        type: "agent_message",
+        content: { type: "text_block", text: aguiState.currentMessage.content },
+        model: "claude",
+        timestamp: new Date().toISOString(),
+        streaming: true,
+      } as MessageObject & { streaming?: boolean });
+    }
+    
+    // Render ALL currently streaming tool calls (supports parallel tool execution)
+    // CRITICAL: This renders tools immediately when TOOL_CALL_START arrives,
+    // not waiting until TOOL_CALL_END like the allToolCalls map approach does
+    const pendingToolCalls = aguiState.pendingToolCalls || new Map();
+    
+    for (const [toolId, pendingTool] of pendingToolCalls) {
+      if (renderedToolCalls.has(toolId)) continue;
+      
+      const toolName = pendingTool.name || "unknown_tool";
+      const toolArgs = pendingTool.args || "";
+      const streamingParentId = pendingTool.parentToolUseId;
+      
+      // Only render if this is a top-level tool (not a child waiting for parent)
+      // Children will be rendered nested inside their parent
+      const isTopLevel = !streamingParentId || !pendingToolCalls.has(streamingParentId);
+      
+      if (isTopLevel) {
+        const toolInput = parseToolArgs(toolArgs);
+        
+        // Get any pending children for this tool (children that finished before parent)
+        const pendingForThis = aguiState.pendingChildren?.get(toolId) || [];
+        const children: ToolUseMessages[] = pendingForThis
+          .map(childMsg => {
+            const childTC = childMsg.toolCalls?.[0];
+            if (!childTC) return null;
+            return createToolMessage(childTC, new Date().toISOString());
+          })
+          .filter((c): c is ToolUseMessages => c !== null);
+        
+        // Also include any streaming children from pendingToolCalls
+        for (const [childId, childTool] of pendingToolCalls) {
+          if (childTool.parentToolUseId === toolId && !renderedToolCalls.has(childId)) {
+            const childInput = parseToolArgs(childTool.args || "");
+            children.push({
+              type: "tool_use_messages",
+              timestamp: new Date().toISOString(),
+              toolUseBlock: {
+                type: "tool_use_block",
+                id: childId,
+                name: childTool.name,
+                input: childInput,
+              },
+              resultBlock: {
+                type: "tool_result_block",
+                tool_use_id: childId,
+                content: null,  // Still streaming
+                is_error: false,
+              },
+            });
+            renderedToolCalls.add(childId);
+          }
+        }
+        
+        // Also include any children from the childrenByParent map
+        const childIds = childrenByParent.get(toolId) || [];
+        for (const childId of childIds) {
+          if (renderedToolCalls.has(childId)) continue;
+          const childData = allToolCalls.get(childId);
+          if (childData) {
+            children.push(createToolMessage(childData.tc, childData.timestamp));
+            renderedToolCalls.add(childId);
+          }
+        }
+        
+        const streamingToolMessage: HierarchicalToolMessage = {
+          type: "tool_use_messages",
+          timestamp: new Date().toISOString(),
+          toolUseBlock: {
+            type: "tool_use_block",
+            id: toolId,
+            name: toolName,
+            input: toolInput,
+          },
+          resultBlock: {
+            type: "tool_result_block",
+            tool_use_id: toolId,
+            content: null,  // No result yet - still running!
+            is_error: false,
+          },
+          children: children.length > 0 ? children : undefined,
+        };
+        
+        result.push(streamingToolMessage);
+        renderedToolCalls.add(toolId);
+      }
+    }
+    
+    return result;
+  }, [
+    aguiState.messages,
+    aguiState.currentMessage,
+    aguiState.currentToolCall,
+    aguiState.pendingToolCalls,  // CRITICAL: Include so UI updates when new tools start
+    aguiState.pendingChildren,   // CRITICAL: Include so UI updates when children finish
+  ]);
 
   // Auto-refresh artifacts when messages complete
   // UX improvement: Automatically refresh the artifacts panel when Claude writes new files,
@@ -682,58 +1080,35 @@ export default function ProjectSessionDetailPage({
     );
   };
 
-  const sendChat = () => {
+  const sendChat = async () => {
     if (!chatInput.trim()) return;
 
     const finalMessage = chatInput.trim();
+    setChatInput("");
 
-    sendChatMutation.mutate(
-      { projectName, sessionName, content: finalMessage },
-      {
-        onSuccess: () => {
-          setChatInput("");
-        },
-        onError: (err) =>
-          errorToast(
-            err instanceof Error ? err.message : "Failed to send message",
-          ),
-      },
-    );
+    try {
+      await aguiSendMessage(finalMessage);
+    } catch (err) {
+      errorToast(err instanceof Error ? err.message : "Failed to send message");
+    }
   };
 
-  const handleCommandClick = (slashCommand: string) => {
-    const finalMessage = slashCommand;
-
-    sendChatMutation.mutate(
-      { projectName, sessionName, content: finalMessage },
-      {
-        onSuccess: () => {
-          successToast(`Command ${slashCommand} sent`);
-        },
-        onError: (err) =>
-          errorToast(
-            err instanceof Error ? err.message : "Failed to send command",
-          ),
-      },
-    );
+  const handleCommandClick = async (slashCommand: string) => {
+    try {
+      await aguiSendMessage(slashCommand);
+      successToast(`Command ${slashCommand} sent`);
+    } catch (err) {
+      errorToast(err instanceof Error ? err.message : "Failed to send command");
+    }
   };
 
-  const handleInterrupt = () => {
-    sendControlMutation.mutate(
-      { projectName, sessionName, type: "interrupt" },
-      {
-        onSuccess: () => successToast("Agent interrupted"),
-        onError: (err) =>
-          errorToast(
-            err instanceof Error ? err.message : "Failed to interrupt agent",
-          ),
-      },
-    );
-  };
+  // LEGACY: Old handleInterrupt removed - now using aguiInterrupt from useAGUIStream
+  // which calls the proper AG-UI interrupt endpoint that signals Claude SDK
 
   const handleEndSession = () => {
-    sendControlMutation.mutate(
-      { projectName, sessionName, type: "end_session" },
+    // Use stop API to end the session
+    stopMutation.mutate(
+      { projectName, sessionName, data: { reason: "end_session" } },
       {
         onSuccess: () => successToast("Session ended successfully"),
         onError: (err) =>
@@ -873,7 +1248,7 @@ export default function ProjectSessionDetailPage({
                   onDelete={handleDelete}
                   durationMs={durationMs}
                   k8sResources={k8sResources}
-                  messageCount={messages.length}
+                  messageCount={aguiState.messages.length}
                   renderMode="kebab-only"
                 />
               </div>
@@ -1445,12 +1820,13 @@ export default function ProjectSessionDetailPage({
                         chatInput={chatInput}
                         setChatInput={setChatInput}
                         onSendChat={() => Promise.resolve(sendChat())}
-                        onInterrupt={() => Promise.resolve(handleInterrupt())}
+                        onInterrupt={aguiInterrupt}
                         onEndSession={() => Promise.resolve(handleEndSession())}
                         onGoToResults={() => {}}
                         onContinue={handleContinue}
                         workflowMetadata={workflowMetadata}
                         onCommandClick={handleCommandClick}
+                        isRunActive={isRunActive}
                       />
                     </div>
                   </CardContent>
diff --git a/components/frontend/src/components/session/MessagesTab.tsx b/components/frontend/src/components/session/MessagesTab.tsx
index 0fc7e6f50..014defb4e 100644
--- a/components/frontend/src/components/session/MessagesTab.tsx
+++ b/components/frontend/src/components/session/MessagesTab.tsx
@@ -6,6 +6,7 @@ import { Badge } from "@/components/ui/badge";
 import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
 import { MessageSquare, Loader2, Settings, Terminal, Users } from "lucide-react";
 import { StreamMessage } from "@/components/ui/stream-message";
+import { LoadingDots } from "@/components/ui/message";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -28,10 +29,11 @@ export type MessagesTabProps = {
   onContinue: () => void;
   workflowMetadata?: WorkflowMetadata;
   onCommandClick?: (slashCommand: string) => void;
+  isRunActive?: boolean;  // NEW: Track if agent is actively processing
 };
 
 
-const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chatInput, setChatInput, onSendChat, onInterrupt, onEndSession, onGoToResults, onContinue, workflowMetadata, onCommandClick }) => {
+const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chatInput, setChatInput, onSendChat, onInterrupt, onEndSession, onGoToResults, onContinue, workflowMetadata, onCommandClick, isRunActive = false }) => {
   const [sendingChat, setSendingChat] = useState(false);
   const [interrupting, setInterrupting] = useState(false);
   const [ending, setEnding] = useState(false);
@@ -277,6 +279,13 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
           <StreamMessage key={`sm-${idx}`} message={m} isNewest={idx === filteredMessages.length - 1} onGoToResults={onGoToResults} />
         ))}
 
+        {/* Show loading indicator when agent is actively processing */}
+        {isRunActive && filteredMessages.length > 0 && (
+          <div className="pl-12 pr-4 py-2">
+            <LoadingDots />
+          </div>
+        )}
+
         {filteredMessages.length === 0 && isCreating && (
           <div className="flex items-center justify-center py-12">
             <Alert className="max-w-md mx-4">
@@ -337,7 +346,7 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
                 <textarea
                   ref={textareaRef}
                   className="w-full border rounded p-2 text-sm"
-                  placeholder="Type a message to the agent... (Press Enter to send, Shift+Enter for new line)"
+                  placeholder={isRunActive ? "Agent is processing... (click Stop to interrupt)" : "Type a message to the agent... (Press Enter to send, Shift+Enter for new line)"}
                   value={chatInput}
                   onChange={handleChatInputChange}
                   onKeyDown={(e) => {
@@ -378,7 +387,7 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
                     }
                   }}
                   rows={3}
-                  disabled={sendingChat}
+                  disabled={sendingChat || isRunActive}
                 />
                 
                 {/* Autocomplete popup */}
@@ -608,15 +617,27 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
                   )}
                 </div>
                 <div className="flex gap-2">
-                  <Button 
-                    variant="outline" 
-                    size="sm" 
-                    onClick={handleInterrupt}
-                    disabled={interrupting || sendingChat || ending}
-                  >
-                    {interrupting && <Loader2 className="w-3 h-3 mr-1 animate-spin" />}
-                    Interrupt agent
-                  </Button>
+                  {/* Show Stop button when run is active, otherwise show Send */}
+                  {isRunActive ? (
+                    <Button 
+                      variant="destructive" 
+                      size="sm" 
+                      onClick={handleInterrupt}
+                      disabled={interrupting}
+                    >
+                      {interrupting && <Loader2 className="w-3 h-3 mr-1 animate-spin" />}
+                      Stop
+                    </Button>
+                  ) : (
+                    <Button 
+                      size="sm" 
+                      onClick={handleSendChat} 
+                      disabled={!chatInput.trim() || sendingChat || ending}
+                    >
+                      {sendingChat && <Loader2 className="w-3 h-3 mr-1 animate-spin" />}
+                      Send
+                    </Button>
+                  )}
                   <Button 
                     variant="secondary" 
                     size="sm" 
@@ -626,14 +647,6 @@ const MessagesTab: React.FC<MessagesTabProps> = ({ session, streamMessages, chat
                     {ending && <Loader2 className="w-3 h-3 mr-1 animate-spin" />}
                     End session
                   </Button>
-                  <Button 
-                    size="sm" 
-                    onClick={handleSendChat} 
-                    disabled={!chatInput.trim() || sendingChat || interrupting || ending}
-                  >
-                    {sendingChat && <Loader2 className="w-3 h-3 mr-1 animate-spin" />}
-                    Send
-                  </Button>
                 </div>
               </div>
           </div>
diff --git a/components/frontend/src/components/session/OverviewTab.tsx b/components/frontend/src/components/session/OverviewTab.tsx
deleted file mode 100644
index d8694ef30..000000000
--- a/components/frontend/src/components/session/OverviewTab.tsx
+++ /dev/null
@@ -1,497 +0,0 @@
-"use client";
-
-import React from "react";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import { Badge } from "@/components/ui/badge";
-import { Button } from "@/components/ui/button";
-import { Brain, Clock, RefreshCw, ExternalLink, Box, Container, HardDrive } from "lucide-react";
-import { cn } from "@/lib/utils";
-import type { AgenticSession } from "@/types/agentic-session";
-import type { SessionMessage } from "@/types";
-import { getK8sResourceStatusColor } from "@/lib/status-colors";
-
-type Props = {
-  session: AgenticSession;
-  promptExpanded: boolean;
-  setPromptExpanded: (v: boolean) => void;
-  latestLiveMessage: SessionMessage | null;
-  diffTotals: Record<number, { total_added: number; total_removed: number }>;
-  onPush: (repoIndex: number) => Promise<void>;
-  onAbandon: (repoIndex: number) => Promise<void>;
-  busyRepo: Record<number, 'push' | 'abandon' | null>;
-  buildGithubCompareUrl: (inUrl: string, inBranch?: string, outUrl?: string, outBranch?: string) => string | null;
-  onRefreshDiff: () => Promise<void>;
-  k8sResources?: {
-    jobName?: string;
-    jobStatus?: string;
-    pods?: Array<{
-      name: string;
-      phase: string;
-      containers: Array<{
-        name: string;
-        state: string;
-        exitCode?: number;
-        reason?: string;
-      }>;
-      isTempPod?: boolean;
-    }>;
-    pvcName?: string;
-    pvcExists?: boolean;
-    pvcSize?: string;
-  };
-};
-
-// Utility to generate OpenShift console URLs
-const getOpenShiftConsoleUrl = (namespace: string, resourceType: 'Job' | 'Pod' | 'PVC', resourceName: string): string | null => {
-  // Try to derive console URL from current window location
-  // OpenShift console is typically at console-openshift-console.apps.<cluster-domain>
-  const hostname = window.location.hostname;
-  
-  // Check if we're on an OpenShift route (apps.*)
-  if (hostname.includes('.apps.')) {
-    const clusterDomain = hostname.split('.apps.')[1];
-    const consoleUrl = `https://console-openshift-console.apps.${clusterDomain}`;
-    
-    const resourceMap = {
-      'Job': 'batch~v1~Job',
-      'Pod': 'core~v1~Pod',
-      'PVC': 'core~v1~PersistentVolumeClaim',
-    };
-    
-    return `${consoleUrl}/k8s/ns/${namespace}/${resourceMap[resourceType]}/${resourceName}`;
-  }
-  
-  // Fallback: For local development or non-standard setups, return null
-  return null;
-};
-
-export const OverviewTab: React.FC<Props> = ({ session, promptExpanded, setPromptExpanded, latestLiveMessage, diffTotals, onPush, onAbandon, busyRepo, buildGithubCompareUrl, onRefreshDiff, k8sResources }) => {
-  const [refreshingDiff, setRefreshingDiff] = React.useState(false);
-  const [expandedPods, setExpandedPods] = React.useState<Record<string, boolean>>({});
-
-  const projectNamespace = session.metadata?.namespace || '';
-  return (
-    <div className="space-y-6">
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
-        <Card>
-          <CardHeader>
-            <CardTitle className="flex items-center">
-              <Brain className="w-5 h-5 mr-2" />
-              Initial Prompt
-            </CardTitle>
-          </CardHeader>
-          <CardContent>
-            {(() => {
-              const promptText = session.spec.initialPrompt || "";
-              const promptIsLong = promptText.length > 400;
-              return (
-                <>
-                  <div className={cn("relative", !promptExpanded && promptIsLong ? "max-h-40 overflow-hidden" : "")}>
-                    <p className="whitespace-pre-wrap text-sm">{promptText}</p>
-                    {!promptExpanded && promptIsLong ? (
-                      <div className="absolute inset-x-0 bottom-0 h-12 bg-gradient-to-t from-white to-transparent pointer-events-none" />
-                    ) : null}
-                  </div>
-                  {promptIsLong && (
-                    <button
-                      className="mt-2 text-xs text-link hover:underline"
-                      onClick={() => setPromptExpanded(!promptExpanded)}
-                      aria-expanded={promptExpanded}
-                      aria-controls="initial-prompt"
-                    >
-                      {promptExpanded ? "View less" : "View more"}
-                    </button>
-                  )}
-                </>
-              );
-            })()}
-          </CardContent>
-        </Card>
-        <Card>
-          <CardHeader>
-            <div className="flex items-center justify-between">
-              <CardTitle>Latest Message</CardTitle>
-            </div>
-          </CardHeader>
-          <CardContent>
-            {latestLiveMessage ? (
-              <div className="space-y-2 text-sm">
-                <div className="flex items-center gap-2">
-                  <Badge variant="outline" className="text-xs">{latestLiveMessage.type}</Badge>
-                  <span className="text-xs text-muted-foreground">{new Date(latestLiveMessage.timestamp).toLocaleTimeString()}</span>
-                </div>
-                <div className="relative max-h-40 overflow-hidden">
-                  <pre className="whitespace-pre-wrap break-words bg-muted/50 rounded p-2 text-xs text-foreground">{JSON.stringify(latestLiveMessage.payload, null, 2)}</pre>
-                  <div className="absolute inset-x-0 bottom-0 h-12 bg-gradient-to-t from-white to-transparent pointer-events-none" />
-                </div>
-              </div>
-            ) : (
-              <div className="text-sm text-muted-foreground">No messages yet</div>
-            )}
-          </CardContent>
-        </Card>
-      </div>
-
-      <div className="grid grid-cols-1 gap-6">
-        {session.status && (
-          <Card>
-            <CardHeader>
-              <CardTitle className="flex items-center">
-                <Clock className="w-5 h-5 mr-2" />
-                System Status & Configuration
-              </CardTitle>
-            </CardHeader>
-            <CardContent>
-              <div className="space-y-4 text-sm">
-                <div>
-                  <div className="text-xs font-semibold text-muted-foreground mb-2">Runtime</div>
-                  <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
-                    <div>
-                      <p className="font-semibold">Phase</p>
-                      <p className="text-muted-foreground">{session.status?.phase ?? "Unknown"}</p>
-                    </div>
-                    {/* startTime/completionTime removed from simplified status */}
-                  </div>
-                </div>
-
-                <div>
-                  <div className="text-xs font-semibold text-muted-foreground mb-2">LLM Config</div>
-                  <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
-                    <div>
-                      <p className="font-semibold">Model</p>
-                      <p className="text-muted-foreground">{session.spec.llmSettings.model}</p>
-                    </div>
-                    <div>
-                      <p className="font-semibold">Temperature</p>
-                      <p className="text-muted-foreground">{session.spec.llmSettings.temperature}</p>
-                    </div>
-                    <div>
-                      <p className="font-semibold">Max Tokens</p>
-                      <p className="text-muted-foreground">{session.spec.llmSettings.maxTokens}</p>
-                    </div>
-                    <div>
-                      <p className="font-semibold">Timeout</p>
-                      <p className="text-muted-foreground">{session.spec.timeout}s</p>
-                    </div>
-                  </div>
-                </div>
-
-                {k8sResources && (
-                  <div>
-                    <div className="text-xs font-semibold text-muted-foreground mb-2">Kubernetes Resources</div>
-                    <div className="space-y-2">
-                      {/* PVC - Always shown at root level (owned by AgenticSession CR) */}
-                      {k8sResources.pvcName && (
-                        <div className="flex items-center gap-2">
-                          <Badge variant="outline" className="text-xs">
-                            <HardDrive className="w-3 h-3 mr-1" />
-                            PVC
-                          </Badge>
-                          {(() => {
-                            const consoleUrl = getOpenShiftConsoleUrl(projectNamespace, 'PVC', k8sResources.pvcName);
-                            return consoleUrl ? (
-                              <a
-                                href={consoleUrl}
-                                target="_blank"
-                                rel="noopener noreferrer"
-                                className="font-mono text-xs text-link hover:text-link-hover hover:underline flex items-center gap-1"
-                              >
-                                {k8sResources.pvcName}
-                                <ExternalLink className="w-3 h-3" />
-                              </a>
-                            ) : (
-                              <span className="font-mono text-xs">{k8sResources.pvcName}</span>
-                            );
-                          })()}
-                          <Badge className={`text-xs ${k8sResources.pvcExists ? 'bg-green-100 text-green-800 border-green-300 dark:bg-green-700 dark:text-white dark:border-green-700' : 'bg-red-100 text-red-800 border-red-300 dark:bg-red-700 dark:text-white dark:border-red-700'}`}>
-                            {k8sResources.pvcExists ? 'Exists' : 'Not Found'}
-                          </Badge>
-                          {k8sResources.pvcSize && <span className="text-xs text-muted-foreground">{k8sResources.pvcSize}</span>}
-                        </div>
-                      )}
-                      
-                      {/* Temp Content Pods - Always at root level (for completed sessions) */}
-                      {k8sResources.pods && k8sResources.pods.filter(p => p.isTempPod).map((pod) => (
-                        <div key={pod.name} className="space-y-1">
-                          <div className="flex items-center gap-2">
-                            <button
-                              onClick={() => setExpandedPods(prev => ({ ...prev, [pod.name]: !prev[pod.name] }))}
-                              className="text-xs text-link hover:underline flex items-center gap-1"
-                            >
-                              {expandedPods[pod.name] ? 'Hide' : 'Show'}
-                            </button>
-                            <Badge variant="outline" className="text-xs">
-                              <Container className="w-3 h-3 mr-1" />
-                              Temp Pod
-                            </Badge>
-                            {(() => {
-                              const consoleUrl = getOpenShiftConsoleUrl(projectNamespace, 'Pod', pod.name);
-                              return consoleUrl ? (
-                                <a
-                                  href={consoleUrl}
-                                  target="_blank"
-                                  rel="noopener noreferrer"
-                                  className="font-mono text-xs text-link hover:text-link-hover hover:underline flex items-center gap-1 truncate max-w-[250px]"
-                                  title={pod.name}
-                                >
-                                  {pod.name}
-                                  <ExternalLink className="w-3 h-3 flex-shrink-0" />
-                                </a>
-                              ) : (
-                                <span className="font-mono text-xs truncate max-w-[250px]" title={pod.name}>
-                                  {pod.name}
-                                </span>
-                              );
-                            })()}
-                            <Badge className={`text-xs ${getK8sResourceStatusColor(pod.phase)}`}>
-                              {pod.phase}
-                            </Badge>
-                            <Badge variant="outline" className="text-xs bg-purple-50 text-purple-700 border-purple-200">
-                              Workspace viewer
-                            </Badge>
-                          </div>
-                          
-                          {/* Temp pod containers */}
-                          {expandedPods[pod.name] && pod.containers && pod.containers.length > 0 && (
-                            <div className="ml-4 space-y-1 border-l-2 border-gray-200 pl-3">
-                              {pod.containers.map((container) => (
-                                <div key={container.name} className="flex items-center gap-2">
-                                  <Badge variant="outline" className="text-xs">
-                                    <Box className="w-3 h-3 mr-1" />
-                                    {container.name}
-                                  </Badge>
-                                  <Badge className={`text-xs ${getK8sResourceStatusColor(container.state)}`}>
-                                    {container.state}
-                                  </Badge>
-                                  {container.exitCode !== undefined && (
-                                    <span className="text-xs text-muted-foreground">Exit: {container.exitCode}</span>
-                                  )}
-                                  {container.reason && (
-                                    <span className="text-xs text-muted-foreground">({container.reason})</span>
-                                  )}
-                                </div>
-                              ))}
-                            </div>
-                          )}
-                        </div>
-                      ))}
-                      
-                      {/* Job - Only shown when job exists */}
-                      {k8sResources.jobName && (
-                      <div className="text-xs space-y-1">
-                        <div className="flex items-center gap-2">
-                          <Badge variant="outline" className="text-xs">
-                            <Box className="w-3 h-3 mr-1" />
-                            Job
-                          </Badge>
-                          {(() => {
-                            const consoleUrl = getOpenShiftConsoleUrl(projectNamespace, 'Job', k8sResources.jobName);
-                            return consoleUrl ? (
-                              <a
-                                href={consoleUrl}
-                                target="_blank"
-                                rel="noopener noreferrer"
-                                className="font-mono text-xs text-link hover:text-link-hover hover:underline flex items-center gap-1"
-                              >
-                                {k8sResources.jobName}
-                                <ExternalLink className="w-3 h-3" />
-                              </a>
-                            ) : (
-                              <span className="font-mono text-xs">{k8sResources.jobName}</span>
-                            );
-                          })()}
-                          <Badge className={`text-xs ${getK8sResourceStatusColor(k8sResources.jobStatus || 'Unknown')}`}>
-                            {k8sResources.jobStatus || 'Unknown'}
-                          </Badge>
-                        </div>
-                        
-                        {/* Job Pods - Only non-temp pods */}
-                        {k8sResources.pods && k8sResources.pods.filter(p => !p.isTempPod).length > 0 && (
-                          <div className="ml-4 space-y-1 border-l-2 border-gray-200 pl-3">
-                            {k8sResources.pods.filter(p => !p.isTempPod).map((pod) => (
-                              <div key={pod.name} className="space-y-1">
-                                <div className="flex items-center gap-2">
-                                  <button
-                                    onClick={() => setExpandedPods(prev => ({ ...prev, [pod.name]: !prev[pod.name] }))}
-                                    className="text-xs text-link hover:underline flex items-center gap-1"
-                                  >
-                                    {expandedPods[pod.name] ? 'Hide' : 'Show'}
-                                  </button>
-                                  <Badge variant="outline" className="text-xs">
-                                    <Container className="w-3 h-3 mr-1" />
-                                    Pod
-                                  </Badge>
-                                  {(() => {
-                                    const consoleUrl = getOpenShiftConsoleUrl(projectNamespace, 'Pod', pod.name);
-                                    return consoleUrl ? (
-                                      <a
-                                        href={consoleUrl}
-                                        target="_blank"
-                                        rel="noopener noreferrer"
-                                        className="font-mono text-xs text-link hover:text-link-hover hover:underline flex items-center gap-1 truncate max-w-[200px]"
-                                        title={pod.name}
-                                      >
-                                        {pod.name}
-                                        <ExternalLink className="w-3 h-3 flex-shrink-0" />
-                                      </a>
-                                    ) : (
-                                      <span className="font-mono text-xs truncate max-w-[200px]" title={pod.name}>
-                                        {pod.name}
-                                      </span>
-                                    );
-                                  })()}
-                                  <Badge className={`text-xs ${getK8sResourceStatusColor(pod.phase)}`}>
-                                    {pod.phase}
-                                  </Badge>
-                                  {pod.isTempPod && (
-                                    <Badge variant="outline" className="text-xs bg-purple-50 text-purple-700 border-purple-200 dark:bg-purple-950/50 dark:text-purple-300 dark:border-purple-800">
-                                      Workspace viewer
-                                    </Badge>
-                                  )}
-                                </div>
-                                
-                                {expandedPods[pod.name] && pod.containers && (
-                                  <div className="ml-4 space-y-1 border-l-2 border-gray-200 pl-3">
-                                    {pod.containers.map((container) => (
-                                      <div key={container.name} className="flex items-center gap-2">
-                                        <Badge variant="outline" className="text-xs">
-                                          <Box className="w-3 h-3 mr-1" />
-                                          {container.name}
-                                        </Badge>
-                                        <Badge className={`text-xs ${getK8sResourceStatusColor(container.state)}`}>
-                                          {container.state}
-                                        </Badge>
-                                        {container.exitCode !== undefined && (
-                                          <span className="text-xs text-muted-foreground">Exit: {container.exitCode}</span>
-                                        )}
-                                        {container.reason && (
-                                          <span className="text-xs text-muted-foreground">({container.reason})</span>
-                                        )}
-                                      </div>
-                                    ))}
-                                  </div>
-                                )}
-                              </div>
-                            ))}
-                          </div>
-                        )}
-                      </div>
-                      )}
-                    </div>
-                  </div>
-                )}
-
-                <div>
-                  <div className="flex items-center justify-between mb-2">
-                    <div className="text-xs font-semibold text-muted-foreground">Repositories</div>
-                    <Button
-                      size="sm"
-                      variant="ghost"
-                      onClick={async () => {
-                        setRefreshingDiff(true);
-                        try {
-                          await onRefreshDiff();
-                        } finally {
-                          setRefreshingDiff(false);
-                        }
-                      }}
-                      disabled={refreshingDiff}
-                      className="h-6 px-2"
-                    >
-                      <RefreshCw className={cn("h-3 w-3", refreshingDiff && "animate-spin")} />
-                    </Button>
-                  </div>
-                  {session.spec.repos && session.spec.repos.length > 0 ? (
-                    <div className="space-y-2">
-                      {session.spec.repos.map((repo, idx) => {
-                        const isMain = idx === 0; // First repo is always the working directory
-                        const branch = repo.branch || 'main';
-                        const compareUrl = buildGithubCompareUrl(repo.url, branch, repo.url, branch);
-                        
-                        // Check if temp pod is running and ready
-                        const tempPod = k8sResources?.pods?.find(p => p.isTempPod);
-                        const tempPodReady = tempPod?.phase === 'Running';
-                        
-                        const br = diffTotals[idx] || { total_added: 0, total_removed: 0 };
-                        const hasChanges = tempPodReady && (br.total_added > 0 || br.total_removed > 0);
-                        return (
-                          <div key={idx} className="flex items-center gap-2 text-sm font-mono">
-                            {isMain && <span className="text-xs bg-primary/10 text-primary px-2 py-0.5 rounded font-sans">MAIN</span>}
-                            <span className="text-muted-foreground break-all">{repo.url}</span>
-                            <span className="text-xs bg-primary/10 text-primary px-2 py-0.5 rounded font-sans">{repo.branch || "main"}</span>
-                            {/* repo.status removed from simplified repo structure */}
-                            <span className="flex-1" />
-                            
-                            {!tempPodReady ? (
-                              <span className="text-xs text-muted-foreground italic">
-                                (read-only - temp service not running)
-                              </span>
-                            ) : !hasChanges ? (
-                              compareUrl ? (
-                                <a 
-                                  href={compareUrl} 
-                                  target="_blank" 
-                                  rel="noreferrer" 
-                                  className="flex items-center gap-1 text-xs text-link hover:underline"
-                                >
-                                  Compare
-                                  <ExternalLink className="h-3 w-3" />
-                                </a>
-                              ) : (
-                                <span className="text-xs text-muted-foreground">no diff</span>
-                              )
-                            ) : (
-                              <span className="flex items-center gap-2">
-                                {br.total_added > 0 && (
-                                  <span className="text-xs px-1 py-0.5 rounded border bg-green-50 text-green-700 border-green-200 dark:bg-green-950/50 dark:text-green-300 dark:border-green-800">
-                                    +{br.total_added}
-                                  </span>
-                                )}
-                                {br.total_removed > 0 && (
-                                  <span className="text-xs px-1 py-0.5 rounded border bg-red-50 text-red-700 border-red-200 dark:bg-red-950/50 dark:text-red-300 dark:border-red-800">
-                                    -{br.total_removed}
-                                  </span>
-                                )}
-                              </span>
-                            )}
-                            {hasChanges && compareUrl ? (
-                              <a 
-                                href={compareUrl} 
-                                target="_blank" 
-                                rel="noreferrer" 
-                                className="flex items-center gap-1 text-xs text-link hover:underline"
-                              >
-                                Compare
-                                <ExternalLink className="h-3 w-3" />
-                              </a>
-                            ) : null}
-                            {hasChanges && tempPodReady && (
-                              repo.url ? (
-                                <div className="flex items-center gap-2">
-                                  <Button size="sm" variant="secondary" onClick={() => onPush(idx)} disabled={!tempPodReady}>{busyRepo[idx] === 'push' ? 'Pushing…' : 'Push'}</Button>
-                                  <Button size="sm" variant="outline" onClick={() => onAbandon(idx)} disabled={!tempPodReady}>{busyRepo[idx] === 'abandon' ? 'Abandoning…' : 'Abandon'}</Button>
-                                </div>
-                              ) : (
-                                <Button size="sm" variant="outline" onClick={() => onAbandon(idx)} disabled={!tempPodReady}>{busyRepo[idx] === 'abandon' ? 'Abandoning…' : 'Abandon changes'}</Button>
-                              )
-                            )}
-                          </div>
-                        );
-                      })}
-                    </div>
-                  ) : (
-                    <p className="text-muted-foreground">No repositories configured</p>
-                  )}
-                </div>
-              </div>
-            </CardContent>
-          </Card>
-        )}
-      </div>
-    </div>
-  );
-};
-
-export default OverviewTab;
-
-
diff --git a/components/frontend/src/components/session/ResultsTab.tsx b/components/frontend/src/components/session/ResultsTab.tsx
deleted file mode 100644
index eec95aaff..000000000
--- a/components/frontend/src/components/session/ResultsTab.tsx
+++ /dev/null
@@ -1,100 +0,0 @@
-"use client";
-
-import React from "react";
-import ReactMarkdown from "react-markdown";
-import remarkGfm from "remark-gfm";
-import rehypeHighlight from "rehype-highlight";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-
-type ResultMeta = {
-  subtype?: string;
-  duration_ms?: number;
-  duration_api_ms?: number;
-  is_error?: boolean;
-  num_turns?: number;
-  session_id?: string;
-  total_cost_usd?: number | null;
-  usage?: Record<string, unknown> | null;
-};
-
-type Props = {
-  result?: string | null;
-  meta?: ResultMeta | null;
-  components?: Record<string, React.ComponentType<unknown>>;
-};
-
-const ResultsTab: React.FC<Props> = ({ result, meta, components }) => {
-  if (!result && !meta) return <div className="text-sm text-muted-foreground">No artifacts yet</div>;
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle>
-          Agent Artifacts
-        </CardTitle>
-      </CardHeader>
-      <CardContent>
-        {result ? (
-          <div className="bg-card rounded-lg prose prose-sm max-w-none prose-headings:text-foreground prose-p:text-foreground/80 prose-strong:text-foreground prose-code:bg-muted prose-code:px-1 prose-code:py-0.5 prose-code:rounded prose-pre:bg-slate-950 prose-pre:dark:bg-black prose-pre:text-slate-50">
-            <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeHighlight]} components={components}>
-              {result}
-            </ReactMarkdown>
-          </div>
-        ) : null}
-
-        {meta ? (
-          <div className="mt-4 border rounded-md p-3 bg-card">
-            <div className="grid grid-cols-1 sm:grid-cols-2 gap-3 text-sm">
-              {typeof meta.subtype === 'string' && meta.subtype ? (
-                <div>
-                  <div className="text-xs text-muted-foreground">Status</div>
-                  <div className="font-medium capitalize">{meta.subtype}{meta.is_error ? " (error)" : ""}</div>
-                </div>
-              ) : null}
-              {typeof meta.num_turns === 'number' ? (
-                <div>
-                  <div className="text-xs text-muted-foreground">Turns</div>
-                  <div className="font-medium">{meta.num_turns}</div>
-                </div>
-              ) : null}
-              {typeof meta.duration_ms === 'number' ? (
-                <div>
-                  <div className="text-xs text-muted-foreground">Duration</div>
-                  <div className="font-medium">{meta.duration_ms} ms</div>
-                </div>
-              ) : null}
-              {typeof meta.duration_api_ms === 'number' ? (
-                <div>
-                  <div className="text-xs text-muted-foreground">API Time</div>
-                  <div className="font-medium">{meta.duration_api_ms} ms</div>
-                </div>
-              ) : null}
-              {typeof meta.total_cost_usd === 'number' ? (
-                <div>
-                  <div className="text-xs text-muted-foreground">Cost (USD)</div>
-                  <div className="font-medium">${meta.total_cost_usd.toFixed(6)}</div>
-                </div>
-              ) : null}
-              {typeof meta.session_id === 'string' && meta.session_id ? (
-                <div className="sm:col-span-2">
-                  <div className="text-xs text-muted-foreground">Session ID</div>
-                  <div className="font-mono text-xs break-all">{meta.session_id}</div>
-                </div>
-              ) : null}
-            </div>
-
-            {meta.usage ? (
-              <div className="mt-3">
-                <div className="text-xs text-muted-foreground mb-1">Usage</div>
-                <pre className="bg-slate-950 dark:bg-black text-slate-50 rounded p-3 text-xs overflow-auto"><code>{JSON.stringify(meta.usage, null, 2)}</code></pre>
-              </div>
-            ) : null}
-          </div>
-        ) : null}
-      </CardContent>
-    </Card>
-  );
-};
-
-export default ResultsTab;
-
-
diff --git a/components/frontend/src/components/ui/message.tsx b/components/frontend/src/components/ui/message.tsx
index b3ab31880..dfb7a7b68 100644
--- a/components/frontend/src/components/ui/message.tsx
+++ b/components/frontend/src/components/ui/message.tsx
@@ -20,6 +20,7 @@ export type MessageProps = {
   borderless?: boolean;
   actions?: React.ReactNode;
   timestamp?: string;
+  streaming?: boolean;
 };
 
 const defaultComponents: Components = {
@@ -171,13 +172,14 @@ export const LoadingDots = () => {
 
 export const Message = React.forwardRef<HTMLDivElement, MessageProps>(
   (
-    { role, content, isLoading, className, components, borderless, actions, timestamp, ...props },
+    { role, content, isLoading, className, components, borderless, actions, timestamp, streaming, ...props },
     ref
   ) => {
     const isBot = role === "bot";
     const avatarBg = isBot ? "bg-blue-600" : "bg-green-600";
     const avatarText = isBot ? "AI" : "U";
     const formattedTime = formatTimestamp(timestamp);
+    const isActivelyStreaming = streaming && isBot;
 
     const avatar = (
       <div className="flex-shrink-0">
@@ -185,7 +187,7 @@ export const Message = React.forwardRef<HTMLDivElement, MessageProps>(
         className={cn(
           "w-8 h-8 rounded-full flex items-center justify-center",
           avatarBg,
-          isLoading && "animate-pulse"
+          (isLoading || isActivelyStreaming) && "animate-pulse"
         )}
       >
         <span className="text-white text-xs font-semibold">
@@ -221,12 +223,17 @@ export const Message = React.forwardRef<HTMLDivElement, MessageProps>(
                     <LoadingDots />
                   </div>
                 ) : (
-                  <ReactMarkdown
-                    remarkPlugins={[remarkGfm]}
-                    components={components || defaultComponents}
-                  >
-                    {content}
-                  </ReactMarkdown>
+                  <div className="inline">
+                    <ReactMarkdown
+                      remarkPlugins={[remarkGfm]}
+                      components={components || defaultComponents}
+                    >
+                      {content}
+                    </ReactMarkdown>
+                    {isActivelyStreaming && (
+                      <span className="inline-block w-2 h-4 bg-primary/70 animate-pulse ml-0.5 align-middle" />
+                    )}
+                  </div>
                 )}
               </div>
 
diff --git a/components/frontend/src/components/ui/stream-message.tsx b/components/frontend/src/components/ui/stream-message.tsx
index edeffd496..77cbab175 100644
--- a/components/frontend/src/components/ui/stream-message.tsx
+++ b/components/frontend/src/components/ui/stream-message.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import React from "react";
-import { MessageObject, ToolUseMessages } from "@/types/agentic-session";
+import { MessageObject, ToolUseMessages, HierarchicalToolMessage } from "@/types/agentic-session";
 import { LoadingDots, Message } from "@/components/ui/message";
 import { ToolMessage } from "@/components/ui/tool-message";
 import { ThinkingMessage } from "@/components/ui/thinking-message";
@@ -9,7 +9,7 @@ import { SystemMessage } from "@/components/ui/system-message";
 import { Button } from "@/components/ui/button";
 
 export type StreamMessageProps = {
-  message: MessageObject | ToolUseMessages;
+  message: (MessageObject | ToolUseMessages | HierarchicalToolMessage) & { streaming?: boolean };
   onGoToResults?: () => void;
   plainCard?: boolean;
   isNewest?: boolean;
@@ -32,11 +32,20 @@ const getRandomAgentMessage = () => {
 };
 
 export const StreamMessage: React.FC<StreamMessageProps> = ({ message, onGoToResults, plainCard=false, isNewest=false }) => {
-  const isToolUsePair = (m: MessageObject | ToolUseMessages): m is ToolUseMessages =>
+  const isToolUsePair = (m: MessageObject | ToolUseMessages | HierarchicalToolMessage): m is ToolUseMessages | HierarchicalToolMessage =>
     m != null && typeof m === "object" && "toolUseBlock" in m && "resultBlock" in m;
 
   if (isToolUsePair(message)) {
-    return <ToolMessage toolUseBlock={message.toolUseBlock} resultBlock={message.resultBlock} timestamp={message.timestamp} />;
+    // Check if this is a hierarchical message with children
+    const hierarchical = message as HierarchicalToolMessage;
+    return (
+      <ToolMessage 
+        toolUseBlock={message.toolUseBlock} 
+        resultBlock={message.resultBlock} 
+        timestamp={message.timestamp}
+        childToolCalls={hierarchical.children}
+      />
+    );
   }
 
   const m = message as MessageObject;
@@ -53,14 +62,15 @@ export const StreamMessage: React.FC<StreamMessageProps> = ({ message, onGoToRes
     }
     case "user_message":
     case "agent_message": {
+      const isStreaming = 'streaming' in message && message.streaming;
       if (typeof m.content === "string") {
-        return <Message role={m.type === "agent_message" ? "bot" : "user"} content={m.content} name="Claude AI" borderless={plainCard} timestamp={m.timestamp}/>;
+        return <Message role={m.type === "agent_message" ? "bot" : "user"} content={m.content} name="Claude AI" borderless={plainCard} timestamp={m.timestamp} streaming={isStreaming}/>;
       }
       switch (m.content.type) {
         case "thinking_block":
           return <ThinkingMessage block={m.content} />
         case "text_block":
-          return <Message role={m.type === "agent_message" ? "bot" : "user"} content={m.content.text} name="Claude AI" borderless={plainCard} timestamp={m.timestamp}/>
+          return <Message role={m.type === "agent_message" ? "bot" : "user"} content={m.content.text} name="Claude AI" borderless={plainCard} timestamp={m.timestamp} streaming={isStreaming}/>
         case "tool_use_block":
           return <ToolMessage toolUseBlock={m.content} borderless={plainCard}/>
         case "tool_result_block":
diff --git a/components/frontend/src/components/ui/tool-message.tsx b/components/frontend/src/components/ui/tool-message.tsx
index 49ec9f5d5..efbc9a67c 100644
--- a/components/frontend/src/components/ui/tool-message.tsx
+++ b/components/frontend/src/components/ui/tool-message.tsx
@@ -3,7 +3,7 @@
 import React, { useState } from "react";
 import { cn } from "@/lib/utils";
 import { Badge } from "@/components/ui/badge";
-import { ToolResultBlock, ToolUseBlock } from "@/types/agentic-session";
+import { ToolResultBlock, ToolUseBlock, ToolUseMessages } from "@/types/agentic-session";
 import {
   ChevronDown,
   ChevronRight,
@@ -20,6 +20,7 @@ import { formatTimestamp } from "@/lib/format-timestamp";
 export type ToolMessageProps = {
   toolUseBlock?: ToolUseBlock;
   resultBlock?: ToolResultBlock;
+  childToolCalls?: ToolUseMessages[];
   className?: string;
   borderless?: boolean;
   timestamp?: string;
@@ -145,9 +146,130 @@ const getColorClassesForName = (name: string) => {
   return colorChoices[idx];
 };
 
+// Helper to convert Python literal to JSON-parseable string
+const pythonLiteralToJson = (pythonStr: string): string => {
+  // This handles Python dict/list notation like [{'type': 'text', 'text': '...'}]
+  // Use a state machine to properly handle quotes and escape sequences
+  
+  let result = '';
+  let inString = false;
+  let stringChar = '';
+  let escaped = false;
+  
+  for (let i = 0; i < pythonStr.length; i++) {
+    const char = pythonStr[i];
+    
+    if (escaped) {
+      // Handle escape sequences
+      if (inString) {
+        // Inside string - convert Python escapes to JSON escapes
+        if (char === "'") {
+          // Python: \' → JSON: ' (no escape needed in double-quoted JSON string)
+          result += "'";
+        } else if (char === '"') {
+          // Python: \" → JSON: \" (keep escape)
+          result += '\\"';
+        } else {
+          // All other escapes (\n, \t, \\, etc.) are valid in both
+          result += '\\' + char;
+        }
+      } else {
+        // Outside string - just copy
+        result += '\\' + char;
+      }
+      escaped = false;
+      continue;
+    }
+    
+    if (char === '\\') {
+      escaped = true;
+      continue;
+    }
+    
+    // Handle quotes
+    if (char === "'" || char === '"') {
+      if (!inString) {
+        // Starting a string
+        inString = true;
+        stringChar = char;
+        result += '"'; // Always use double quotes in JSON
+      } else if (char === stringChar) {
+        // Ending a string
+        inString = false;
+        stringChar = '';
+        result += '"';
+      } else {
+        // Different quote inside string
+        if (char === '"') {
+          // Double quote inside single-quoted Python string
+          result += '\\"'; // Must escape in JSON
+        } else {
+          // Single quote inside double-quoted string
+          result += "'"; // No escape needed
+        }
+      }
+      continue;
+    }
+    
+    // If we're in a string, just copy characters
+    if (inString) {
+      result += char;
+      continue;
+    }
+    
+    // Handle Python keywords outside strings
+    if (!inString) {
+      if (pythonStr.substr(i, 4) === 'True') {
+        result += 'true';
+        i += 3;
+        continue;
+      }
+      if (pythonStr.substr(i, 5) === 'False') {
+        result += 'false';
+        i += 4;
+        continue;
+      }
+      if (pythonStr.substr(i, 4) === 'None') {
+        result += 'null';
+        i += 3;
+        continue;
+      }
+    }
+    
+    result += char;
+  }
+  
+  return result;
+};
+
 const extractTextFromResultContent = (content: unknown): string => {
   try {
-    if (typeof content === "string") return content;
+    // If string, try to parse as JSON/Python first (handles stringified arrays/objects)
+    if (typeof content === "string") {
+      // Try parsing if it looks like JSON/Python
+      if (content.trim().startsWith("[") || content.trim().startsWith("{")) {
+        try {
+          // FIRST: Try parsing as valid JSON (backend now sends proper JSON)
+          const parsed = JSON.parse(content);
+          return extractTextFromResultContent(parsed);
+        } catch {
+          // FALLBACK: Try converting Python notation to JSON (for old sessions)
+          try {
+            const jsonStr = pythonLiteralToJson(content);
+            const parsed = JSON.parse(jsonStr);
+            return extractTextFromResultContent(parsed);
+          } catch {
+            // LAST RESORT: Can't parse, just return the raw string
+            // This handles cases where the content is malformed or uses unknown syntax
+            console.warn('Failed to parse result content, showing raw text');
+            return content;
+          }
+        }
+      }
+      return content;
+    }
+    
+    // Handle arrays of text blocks
     if (Array.isArray(content)) {
       const texts = content
         .map((item) => {
@@ -159,8 +281,9 @@ const extractTextFromResultContent = (content: unknown): string => {
         .filter(Boolean);
       if (texts.length) return texts.join("\n\n");
     }
+    
+    // Handle nested content arrays
     if (content && typeof content === "object") {
-      // Some schemas nest under content: []
       const maybe = (content as Record<string, unknown>).content;
       if (Array.isArray(maybe)) {
         const texts = maybe
@@ -174,19 +297,203 @@ const extractTextFromResultContent = (content: unknown): string => {
         if (texts.length) return texts.join("\n\n");
       }
     }
+    
     return JSON.stringify(content ?? "");
   } catch {
     return String(content ?? "");
   }
 };
 
+// Generate smart summary for tool calls based on tool name and input
+const generateToolSummary = (toolName: string, input?: Record<string, unknown>): string => {
+  if (!input || Object.keys(input).length === 0) return formatToolName(toolName);
+  
+  // WebSearch - show query
+  if (toolName.toLowerCase().includes("websearch") || toolName.toLowerCase().includes("web_search")) {
+    const query = input.query as string | undefined;
+    if (query) return `Searching the web for "${query}"`;
+  }
+  
+  // FileRead - show file path
+  if (toolName.toLowerCase().includes("read") && (input.file || input.path || input.target_file)) {
+    const file = (input.file || input.path || input.target_file) as string;
+    return `Reading ${file}`;
+  }
+  
+  // FileWrite - show file path
+  if (toolName.toLowerCase().includes("write") && (input.file || input.path || input.target_file)) {
+    const file = (input.file || input.path || input.target_file) as string;
+    return `Writing to ${file}`;
+  }
+  
+  // Grep - show pattern and path
+  if (toolName.toLowerCase().includes("grep") || toolName.toLowerCase().includes("search")) {
+    const pattern = input.pattern as string | undefined;
+    const path = input.path as string | undefined;
+    if (pattern && path) return `Searching for "${pattern}" in ${path}`;
+    if (pattern) return `Searching for "${pattern}"`;
+  }
+  
+  // Command execution
+  if (toolName.toLowerCase().includes("command") || toolName.toLowerCase().includes("terminal")) {
+    const command = input.command as string | undefined;
+    if (command) {
+      const truncated = command.length > 50 ? command.substring(0, 50) + "..." : command;
+      return `Running: ${truncated}`;
+    }
+  }
+  
+  // Fallback: show first string value from input (often contains the main parameter)
+  const firstStringValue = Object.values(input).find(v => typeof v === 'string' && v.length > 0) as string | undefined;
+  if (firstStringValue) {
+    const truncated = firstStringValue.length > 60 ? firstStringValue.substring(0, 60) + "..." : firstStringValue;
+    return truncated;
+  }
+  
+  // Last resort: show formatted tool name
+  return formatToolName(toolName);
+};
+
+// Child Tool Call component for hierarchical rendering (collapsed by default)
+type ChildToolCallProps = {
+  toolUseBlock?: ToolUseBlock;
+  resultBlock?: ToolResultBlock;
+};
+
+const ChildToolCall: React.FC<ChildToolCallProps> = ({ toolUseBlock, resultBlock }) => {
+  const [expanded, setExpanded] = useState(false);
+  
+  // Check if result has actual content (same logic as parent tool)
+  const hasActualResult = Boolean(
+    resultBlock && 
+    resultBlock.content !== undefined && 
+    resultBlock.content !== null &&
+    (() => {
+      const content = resultBlock.content;
+      // Empty string
+      if (content === "") return false;
+      // Empty array
+      if (Array.isArray(content) && content.length === 0) return false;
+      // Empty object
+      if (typeof content === 'object' && !Array.isArray(content) && Object.keys(content).length === 0) return false;
+      // String that only contains whitespace or quotes
+      if (typeof content === 'string' && content.trim() === '') return false;
+      if (typeof content === 'string' && (content === '""' || content === "''")) return false;
+      // Has actual content
+      return true;
+    })()
+  );
+  
+  const isError = resultBlock?.is_error === true;
+  const isSuccess = hasActualResult && !isError;
+  const isPending = !hasActualResult;
+  
+  const toolName = toolUseBlock?.name || "unknown_tool";
+  
+  // Parse input - it might be a string that needs JSON parsing or already an object
+  let toolInput: Record<string, unknown> | undefined;
+  if (toolUseBlock?.input) {
+    if (typeof toolUseBlock.input === 'string') {
+      try {
+        toolInput = JSON.parse(toolUseBlock.input) as Record<string, unknown>;
+      } catch {
+        // If parsing fails, treat the string as a single value
+        toolInput = { value: toolUseBlock.input };
+      }
+    } else {
+      toolInput = toolUseBlock.input as Record<string, unknown>;
+    }
+  }
+  
+  // Generate smart collapsed summary - ALWAYS show the query/input, not the result
+  // Result should only be visible when expanded
+  const collapsedSummary = generateToolSummary(toolName, toolInput);
+  
+  return (
+    <div className="py-1">
+      <div 
+        className="flex items-center gap-2 cursor-pointer hover:bg-muted/30 rounded px-2 py-1"
+        onClick={() => setExpanded(!expanded)}
+      >
+        {isError && <X className="w-3 h-3 text-red-500 flex-shrink-0" />}
+        {isSuccess && <Check className="w-3 h-3 text-green-500 flex-shrink-0" />}
+        {isPending && <Loader2 className="w-3 h-3 animate-spin text-blue-500 flex-shrink-0" />}
+        
+        <Badge variant="secondary" className="text-[10px] px-1.5 py-0.5 flex-shrink-0">
+          {formatToolName(toolName)}
+        </Badge>
+        
+        {/* Collapsed summary */}
+        {!expanded && (
+          <span className="text-[11px] text-muted-foreground truncate flex-1">
+            {collapsedSummary}
+          </span>
+        )}
+        
+        <ChevronRight className={cn(
+          "w-3 h-3 text-muted-foreground transition-transform flex-shrink-0",
+          expanded && "rotate-90"
+        )} />
+      </div>
+      
+      {expanded && (
+        <div className="mt-1 ml-5 text-xs space-y-2 bg-muted/20 rounded p-2 border border-border">
+          {toolInput && Object.keys(toolInput).length > 0 && (
+            <div>
+              <div className="font-medium text-foreground/70 mb-1">Input</div>
+              <pre className="text-[10px] overflow-x-auto text-muted-foreground">
+                {JSON.stringify(toolInput, null, 2)}
+              </pre>
+            </div>
+          )}
+          {resultBlock?.content && (
+            <div>
+              <div className="font-medium text-foreground/70 mb-1">
+                Result {isError && <span className="text-red-600">(Error)</span>}
+              </div>
+              {/* Render result as markdown for better formatting */}
+              <ExpandableMarkdown 
+                className="prose-sm" 
+                content={extractTextFromResultContent(resultBlock.content as unknown)}
+                maxLength={500}
+              />
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
 export const ToolMessage = React.forwardRef<HTMLDivElement, ToolMessageProps>(
-  ({ toolUseBlock, resultBlock, className, borderless, timestamp, ...props }, ref) => {
+  ({ toolUseBlock, resultBlock, childToolCalls, className, borderless, timestamp, ...props }, ref) => {
     const [isExpanded, setIsExpanded] = useState(false);
 
     const toolResultBlock = resultBlock;
-    const isToolCall = Boolean(toolUseBlock && !toolResultBlock);
-    const isToolResult = Boolean(toolResultBlock);
+    
+    // Check if result has actual content (not just empty object/array/string)
+    const hasActualResult = Boolean(
+      toolResultBlock && 
+      toolResultBlock.content !== undefined && 
+      toolResultBlock.content !== null &&
+      (() => {
+        const content = toolResultBlock.content;
+        // Empty string
+        if (content === "") return false;
+        // Empty array
+        if (Array.isArray(content) && content.length === 0) return false;
+        // Empty object
+        if (typeof content === 'object' && !Array.isArray(content) && Object.keys(content).length === 0) return false;
+        // String that only contains whitespace or quotes
+        if (typeof content === 'string' && content.trim() === '') return false;
+        if (typeof content === 'string' && (content === '""' || content === "''")) return false;
+        // Has actual content
+        return true;
+      })()
+    );
+    
+    const isToolCall = Boolean(toolUseBlock && !hasActualResult);
+    const isToolResult = hasActualResult;
 
     // For tool calls/results, show collapsible interface
     const toolName = formatToolName(toolUseBlock?.name);
@@ -249,7 +556,7 @@ export const ToolMessage = React.forwardRef<HTMLDivElement, ToolMessageProps>(
                 )}
                 onClick={() => setIsExpanded(!isExpanded)}
               >
-                <div className={cn("flex items-center", isCompact ? "space-x-1.5" : "space-x-2")}>
+                <div className={cn("flex items-center flex-1 min-w-0", isCompact ? "space-x-1.5" : "space-x-2")}>
                   {/* Status Icon */}
                   {!isCompact && (
                     <div className="flex-shrink-0">
@@ -265,26 +572,42 @@ export const ToolMessage = React.forwardRef<HTMLDivElement, ToolMessageProps>(
                       {isLoading && (
                         <Loader2 className="w-3 h-3 text-blue-500 animate-spin" />
                       )}
+                      {isSuccess && <Check className="w-3 h-3 text-green-500" />}
                       {isError && <X className="w-3 h-3 text-red-500" />}
                     </div>
                   )}
 
-                  {/* Tool Name */}
-                  <div className="flex-1 flex items-center min-h-0">
+                  {/* Tool Name Badge */}
+                  <div className="flex-shrink-0">
                     <Badge
                       className={cn(
                         "text-xs text-white",
-                        isLoading && "bg-blue-500 animate-pulse",
+                        isLoading && "bg-blue-500",
                         isError && "bg-red-600",
                         isSuccess && "bg-green-600",
                         isSubagent && subagentClasses?.badgeBg,
                         isCompact && "!py-0 px-1.5 leading-tight"
                       )}
                     >
-                      {isSubagent ? displayName : (isLoading ? "Calling" : "Called") + " " + displayName}
+                      {displayName}
                     </Badge>
                   </div>
 
+                  {/* Title/Description - Always visible (collapsed or expanded) */}
+                  <div className="flex-1 min-w-0 text-sm text-muted-foreground truncate">
+                    {isSubagent ? (
+                      // Agent: Show description (title)
+                      <span className="truncate">
+                        {subagentDescription || subagentPrompt || "Working..."}
+                      </span>
+                    ) : (
+                      // Regular tool: Show query/input summary
+                      <span className="truncate">
+                        {generateToolSummary(toolUseBlock?.name || "", inputData)}
+                      </span>
+                    )}
+                  </div>
+
                   {/* Expand/Collapse Icon */}
                   <div className="flex-shrink-0">
                     {isExpanded ? (
@@ -296,33 +619,69 @@ export const ToolMessage = React.forwardRef<HTMLDivElement, ToolMessageProps>(
                 </div>
               </div>
 
-              {/* Subagent primary content (description + prompt) */}
-              {isSubagent ? (
+              {/* Subagent primary content - REORDERED: Input → Activity → Result */}
+              {isSubagent && isExpanded ? (
                 <div className="px-3 pb-3 space-y-3">
-                  <div>
-                    {subagentDescription && subagentDescription.trim() ? (
-                      <div className="text-foreground">
-                        <ExpandableMarkdown className="prose-sm" content={subagentDescription} />
-                      </div>
-                    ) : isLoading ? (
-                      <div className="text-muted-foreground text-sm italic">
-                        Working on your request...
+                  {/* 1. INPUT - Show when expanded */}
+                  {subagentPrompt && (
+                    <div className="space-y-2">
+                      <h4 className="text-xs font-medium text-foreground/60 uppercase tracking-wide">
+                        Prompt
+                      </h4>
+                      <div className="rounded p-2 overflow-x-auto bg-muted/20 border border-border text-xs text-muted-foreground">
+                        <ExpandableMarkdown className="prose-sm" content={subagentPrompt} maxLength={500} />
                       </div>
-                    ) : null}
-                    
-                    {isLoading && subagentDescription && subagentDescription.trim() && (
-                      <div className="flex items-center gap-2 text-xs text-muted-foreground mt-2">
-                        <Loader2 className="w-3 h-3 animate-bounce" />
-                        <span>Waiting for result…</span>
+                    </div>
+                  )}
+                  
+                  {/* 2. ACTIVITY - Agent child tool calls */}
+                  {childToolCalls && childToolCalls.length > 0 && (
+                    <div className="space-y-2">
+                      <h4 className="text-xs font-medium text-foreground/60 uppercase tracking-wide">
+                        Activity
+                      </h4>
+                      <div className="space-y-1 pl-2 border-l-2 border-purple-200 dark:border-purple-800">
+                        {childToolCalls.map((child, idx) => (
+                          <ChildToolCall
+                            key={`child-${child.toolUseBlock?.id || idx}`}
+                            toolUseBlock={child.toolUseBlock}
+                            resultBlock={child.resultBlock}
+                          />
+                        ))}
                       </div>
-                    )}
-                  </div>
+                    </div>
+                  )}
+                  
+                  {/* Loading indicator when waiting for result */}
+                  {isLoading && (
+                    <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                      <Loader2 className="w-3 h-3 animate-spin" />
+                      <span>
+                        {childToolCalls && childToolCalls.length > 0 
+                          ? "Processing..." 
+                          : "Waiting for result…"}
+                      </span>
+                    </div>
+                  )}
 
-                  {isExpanded && subagentPrompt && (
+                  {/* 3. RESULT - Only show if there's actual content */}
+                  {hasActualResult && (
                     <div>
-                      <h4 className="text-xs font-medium text-foreground/80 mb-1">Prompt</h4>
-                      <div className="rounded p-2 overflow-x-auto">
-                        <ExpandableMarkdown className="prose-sm" content={subagentPrompt} />
+                      <h4 className="text-xs font-medium text-foreground/60 uppercase tracking-wide">
+                        Result {isError && <span className="text-red-600">(Error)</span>}
+                      </h4>
+                      <div className={cn(
+                        "rounded p-2 mt-1 overflow-x-auto border text-xs",
+                        isError 
+                          ? "bg-red-50 dark:bg-red-950/50 border-red-200 dark:border-red-800"
+                          : "bg-muted/30 border-border"
+                      )}>
+                        {/* CRITICAL: Render result as markdown for better formatting */}
+                        <ExpandableMarkdown 
+                          className="prose-sm" 
+                          content={extractTextFromResultContent(toolResultBlock?.content as unknown)}
+                          maxLength={1000}
+                        />
                       </div>
                     </div>
                   )}
@@ -368,38 +727,6 @@ export const ToolMessage = React.forwardRef<HTMLDivElement, ToolMessageProps>(
                 )
               )}
             </div>
-
-            {/* Subagent Result Card (separate) */}
-            {isSubagent && isToolResult && (
-              <div
-                className={cn(
-                  "mt-2 rounded-lg border shadow-sm",
-                  subagentClasses?.cardBg,
-                  subagentClasses?.border
-                )}
-              >
-                <div className="flex items-center justify-between p-3">
-                  <div className="flex items-center space-x-2">
-                    <div className="flex-shrink-0">
-                      {isSuccess && <Check className="w-4 h-4 text-green-500" />}
-                      {isError && <X className="w-4 h-4 text-red-500" />}
-                    </div>
-                    <div className="flex-1">
-                      <Badge
-                        className={cn("text-xs text-white", subagentClasses?.badgeBg)}
-                      >
-                        {displayName}
-                      </Badge>
-                    </div>
-                  </div>
-                </div>
-                <div className="px-3 pb-3">
-                  <div className={cn("rounded p-2 overflow-x-auto text-foreground")}>
-                    <ExpandableMarkdown className="prose-sm" content={extractTextFromResultContent(toolResultBlock?.content as unknown)} />
-                  </div>
-                </div>
-              </div>
-            )}
           </div>
         </div>
       </div>
diff --git a/components/frontend/src/hooks/use-agui-stream.ts b/components/frontend/src/hooks/use-agui-stream.ts
new file mode 100644
index 000000000..1c8839a61
--- /dev/null
+++ b/components/frontend/src/hooks/use-agui-stream.ts
@@ -0,0 +1,791 @@
+'use client'
+
+/**
+ * AG-UI Event Stream Hook
+ * 
+ * EventSource-based hook for consuming AG-UI events from the backend.
+ * Uses the same-origin SSE proxy to bypass browser EventSource auth limitations.
+ * 
+ * Reference: https://docs.ag-ui.com/concepts/events
+ * Reference: https://docs.ag-ui.com/concepts/messages
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  AGUIClientState,
+  AGUIEvent,
+  AGUIEventType,
+  AGUIMessage,
+  AGUIRole,
+  AGUIStepStartedEvent,
+  isRunStartedEvent,
+  isRunFinishedEvent,
+  isRunErrorEvent,
+  isTextMessageStartEvent,
+  isTextMessageContentEvent,
+  isTextMessageEndEvent,
+  isToolCallStartEvent,
+  isToolCallEndEvent,
+  isStateSnapshotEvent,
+  isMessagesSnapshotEvent,
+  isActivitySnapshotEvent,
+} from '@/types/agui'
+
+type UseAGUIStreamOptions = {
+  projectName: string
+  sessionName: string
+  runId?: string
+  autoConnect?: boolean
+  onEvent?: (event: AGUIEvent) => void
+  onMessage?: (message: AGUIMessage) => void
+  onError?: (error: string) => void
+  onConnected?: () => void
+  onDisconnected?: () => void
+}
+
+type UseAGUIStreamReturn = {
+  state: AGUIClientState
+  connect: (runId?: string) => void
+  disconnect: () => void
+  sendMessage: (content: string) => Promise<void>
+  interrupt: () => Promise<void>
+  isConnected: boolean
+  isStreaming: boolean
+  isRunActive: boolean
+}
+
+  const initialState: AGUIClientState = {
+    threadId: null,
+    runId: null,
+    status: 'idle',
+    messages: [],
+    state: {},
+    activities: [],
+    currentMessage: null,
+    currentToolCall: null,  // DEPRECATED: kept for backward compat
+    pendingToolCalls: new Map(),  // NEW: tracks ALL in-progress tool calls
+    pendingChildren: new Map(),
+    error: null,
+  }
+
+export function useAGUIStream(options: UseAGUIStreamOptions): UseAGUIStreamReturn {
+  // Track hidden message IDs (auto-sent initial/workflow prompts)
+  const hiddenMessageIdsRef = useRef<Set<string>>(new Set())
+  const {
+    projectName,
+    sessionName,
+    runId: initialRunId,
+    autoConnect = false,
+    onEvent,
+    onMessage,
+    onError,
+    onConnected,
+    onDisconnected,
+  } = options
+
+  const [state, setState] = useState<AGUIClientState>(initialState)
+  const [isRunActive, setIsRunActive] = useState(false)
+  const currentRunIdRef = useRef<string | null>(null)
+  const eventSourceRef = useRef<EventSource | null>(null)
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const mountedRef = useRef(false)
+  
+  // Track mounted state without causing re-renders
+  useEffect(() => {
+    mountedRef.current = true
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  // Process incoming AG-UI events
+  const processEvent = useCallback(
+    (event: AGUIEvent) => {
+      onEvent?.(event)
+
+      setState((prev) => {
+        const newState = { ...prev }
+
+        if (isRunStartedEvent(event)) {
+          newState.threadId = event.threadId
+          newState.runId = event.runId
+          newState.status = 'connected'
+          newState.error = null
+          
+          // Track active run
+          currentRunIdRef.current = event.runId
+          setIsRunActive(true)
+          
+          return newState
+        }
+
+        if (isRunFinishedEvent(event)) {
+          newState.status = 'completed'
+          
+          // Mark run as inactive
+          if (currentRunIdRef.current === event.runId) {
+            setIsRunActive(false)
+            currentRunIdRef.current = null
+          }
+          
+          // Flush any pending message
+          if (newState.currentMessage?.content) {
+            const msg: AGUIMessage = {
+              id: newState.currentMessage.id || crypto.randomUUID(),
+              role: newState.currentMessage.role || AGUIRole.ASSISTANT,
+              content: newState.currentMessage.content,
+            }
+            newState.messages = [...newState.messages, msg]
+            onMessage?.(msg)
+          }
+          newState.currentMessage = null
+          return newState
+        }
+
+        if (isRunErrorEvent(event)) {
+          newState.status = 'error'
+          newState.error = event.error
+          onError?.(event.error)
+          
+          // Mark run as inactive on error
+          if (currentRunIdRef.current === event.runId) {
+            setIsRunActive(false)
+            currentRunIdRef.current = null
+          }
+          
+          return newState
+        }
+
+        if (isTextMessageStartEvent(event)) {
+          newState.currentMessage = {
+            id: event.messageId || null,
+            role: event.role,
+            content: '',
+          }
+          return newState
+        }
+
+        if (isTextMessageContentEvent(event)) {
+          if (newState.currentMessage) {
+            // Create a NEW object so React detects the change and re-renders
+            newState.currentMessage = {
+              ...newState.currentMessage,
+              content: (newState.currentMessage.content || '') + event.delta,
+            }
+          }
+          return newState
+        }
+
+        if (isTextMessageEndEvent(event)) {
+          if (newState.currentMessage?.content) {
+            const messageId = newState.currentMessage.id || crypto.randomUUID();
+            
+            // Skip hidden messages (auto-sent initial/workflow prompts)
+            if (hiddenMessageIdsRef.current.has(messageId)) {
+              newState.currentMessage = null;
+              return newState;
+            }
+            
+            // Check if this message already exists (e.g., from MESSAGES_SNAPSHOT)
+            const existingIndex = newState.messages.findIndex(m => m.id === messageId);
+            
+            if (existingIndex >= 0) {
+              // Message exists - update content if different (don't duplicate)
+              const existingMsg = newState.messages[existingIndex];
+              if (existingMsg.content !== newState.currentMessage.content) {
+                const updatedMessages = [...newState.messages];
+                updatedMessages[existingIndex] = {
+                  ...existingMsg,
+                  content: newState.currentMessage.content,
+                };
+                newState.messages = updatedMessages;
+              }
+            } else {
+              // Message doesn't exist - create new
+              const msg: AGUIMessage = {
+                id: messageId,
+                role: newState.currentMessage.role || AGUIRole.ASSISTANT,
+                content: newState.currentMessage.content,
+              }
+              newState.messages = [...newState.messages, msg]
+              onMessage?.(msg)
+            }
+          }
+          newState.currentMessage = null
+          // Don't clear currentToolCall - tool calls might come after TEXT_MESSAGE_END
+          return newState
+        }
+
+        if (isToolCallStartEvent(event)) {
+          // Runner's ag_ui.core uses snake_case: parent_tool_call_id
+          const parentToolId = (event as unknown as { parent_tool_call_id?: string }).parent_tool_call_id;
+          
+          // Store in pendingToolCalls Map to support parallel tool calls
+          const updatedPending = new Map(newState.pendingToolCalls);
+          updatedPending.set(event.toolCallId, {
+            id: event.toolCallId,
+            name: event.toolCallName || 'unknown_tool',
+            args: '',
+            parentToolUseId: parentToolId,
+          });
+          newState.pendingToolCalls = updatedPending;
+          
+          // Also update currentToolCall for backward compat (UI rendering)
+          newState.currentToolCall = {
+            id: event.toolCallId,
+            name: event.toolCallName,
+            args: '',
+            parentToolUseId: parentToolId,
+          }
+          return newState
+        }
+
+        if (event.type === AGUIEventType.TOOL_CALL_ARGS) {
+          const toolCallId = event.toolCallId;
+          const existing = newState.pendingToolCalls.get(toolCallId);
+          
+          if (existing) {
+            // Update the pending tool call in Map
+            const updatedPending = new Map(newState.pendingToolCalls);
+            updatedPending.set(toolCallId, {
+              ...existing,
+              args: (existing.args || '') + event.delta,
+            });
+            newState.pendingToolCalls = updatedPending;
+          }
+          
+          // Also update currentToolCall for backward compat (if it's the same tool)
+          if (newState.currentToolCall?.id === toolCallId) {
+            newState.currentToolCall = {
+              ...newState.currentToolCall,
+              args: (newState.currentToolCall.args || '') + event.delta,
+            }
+          }
+          return newState
+        }
+
+        if (isToolCallEndEvent(event)) {
+          const toolCallId = event.toolCallId || newState.currentToolCall?.id || crypto.randomUUID()
+          
+          // Get tool info from pendingToolCalls Map (supports parallel tool calls)
+          const pendingTool = newState.pendingToolCalls.get(toolCallId);
+          const toolCallName = pendingTool?.name || newState.currentToolCall?.name || 'unknown_tool'
+          const toolCallArgs = pendingTool?.args || newState.currentToolCall?.args || ''
+          const parentToolUseId = pendingTool?.parentToolUseId || newState.currentToolCall?.parentToolUseId
+          
+          // Defense in depth: Check if this tool already exists (shouldn't happen with fixed backend)
+          const toolAlreadyExists = newState.messages.some(msg => 
+            msg.toolCalls?.some(tc => tc.id === toolCallId)
+          );
+          
+          if (toolAlreadyExists) {
+            console.warn(`[useAGUIStream] BACKEND BUG: Tool ${toolCallName} (${toolCallId.substring(0, 8)}) already exists, skipping duplicate`);
+            // Remove from pending maps and return
+            const updatedPendingTools = new Map(newState.pendingToolCalls);
+            updatedPendingTools.delete(toolCallId);
+            newState.pendingToolCalls = updatedPendingTools;
+            if (newState.currentToolCall?.id === toolCallId) {
+              newState.currentToolCall = null;
+            }
+            return newState;
+          }
+          
+          // Create completed tool call
+          const completedToolCall = {
+            id: toolCallId,
+            name: toolCallName,
+            args: toolCallArgs,
+            result: event.result,
+            status: event.error ? 'error' as const : 'completed' as const,
+            error: event.error,
+            parentToolUseId: parentToolUseId,
+          }
+          
+          const messages = [...newState.messages]
+          
+          // Remove from pendingToolCalls Map
+          const updatedPendingTools = new Map(newState.pendingToolCalls);
+          updatedPendingTools.delete(toolCallId);
+          newState.pendingToolCalls = updatedPendingTools;
+          
+          // If this tool has a parent, try to attach to it
+          if (parentToolUseId) {
+            let foundParent = false
+            
+            // Check if parent is still pending (streaming, not finished yet)
+            if (newState.pendingToolCalls.has(parentToolUseId)) {
+              // Parent is still streaming - store as pending child
+              const updatedPending = new Map(newState.pendingChildren);
+              const pending = updatedPending.get(parentToolUseId) || []
+              updatedPending.set(parentToolUseId, [...pending, {
+                id: crypto.randomUUID(),
+                role: AGUIRole.TOOL,
+                toolCallId: toolCallId,
+                name: toolCallName,
+                content: event.result || event.error || '',
+                toolCalls: [completedToolCall],
+              }])
+              newState.pendingChildren = updatedPending;
+              if (newState.currentToolCall?.id === toolCallId) {
+                newState.currentToolCall = null;
+              }
+              return newState
+            }
+            
+            // Search for parent in messages
+            for (let i = messages.length - 1; i >= 0; i--) {
+              // Check if parent is in this message's toolCalls array
+              if (messages[i].toolCalls) {
+                const parentToolIdx = messages[i].toolCalls!.findIndex(tc => tc.id === parentToolUseId)
+                if (parentToolIdx !== -1) {
+                  // Found parent! Check if child already attached
+                  const childExists = messages[i].toolCalls!.some(tc => tc.id === toolCallId);
+                  if (!childExists) {
+                    const existingToolCalls = messages[i].toolCalls || []
+                    messages[i] = {
+                      ...messages[i],
+                      toolCalls: [...existingToolCalls, completedToolCall]
+                    }
+                  }
+                  foundParent = true
+                  break
+                }
+              }
+            }
+            
+            if (foundParent) {
+              newState.messages = messages
+              if (newState.currentToolCall?.id === toolCallId) {
+                newState.currentToolCall = null;
+              }
+              return newState
+            }
+            
+            // Parent not found - will attach to assistant message below
+            console.warn(`[useAGUIStream] Parent ${parentToolUseId.substring(0, 8)} not found for child ${toolCallName}, attaching to assistant`)
+          }
+          
+          // This is either a top-level tool or parent wasn't found
+          // Attach to last assistant message
+          let foundAssistant = false
+          for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === AGUIRole.ASSISTANT) {
+              const existingToolCalls = messages[i].toolCalls || []
+              
+              // Check if tool already exists in this message
+              if (existingToolCalls.some(tc => tc.id === toolCallId)) {
+                foundAssistant = true;
+                break;
+              }
+              
+              // If this tool just finished and has pending children, attach them all now!
+              const pendingForThisTool = newState.pendingChildren.get(toolCallId) || []
+              const childToolCalls = pendingForThisTool.flatMap(child => child.toolCalls || [])
+              
+              messages[i] = {
+                ...messages[i],
+                toolCalls: [...existingToolCalls, completedToolCall, ...childToolCalls]
+              }
+              
+              if (pendingForThisTool.length > 0) {
+                const updatedPending = new Map(newState.pendingChildren);
+                updatedPending.delete(toolCallId);
+                newState.pendingChildren = updatedPending;
+              }
+              
+              foundAssistant = true
+              break
+            }
+          }
+          
+          // If no assistant, add as standalone
+          if (!foundAssistant) {
+            const toolMessage: AGUIMessage = {
+              id: crypto.randomUUID(),
+              role: AGUIRole.TOOL,
+              content: event.result || event.error || '',
+              toolCallId: toolCallId,
+              name: toolCallName,
+              toolCalls: [completedToolCall],
+            }
+            messages.push(toolMessage)
+          }
+          
+          newState.messages = messages
+          newState.currentToolCall = null
+          return newState
+        }
+
+        if (isStateSnapshotEvent(event)) {
+          newState.state = event.state
+          return newState
+        }
+
+        if (event.type === AGUIEventType.STATE_DELTA) {
+          // Apply state patches
+          const stateClone = { ...newState.state }
+          for (const patch of event.delta) {
+            const key = patch.path.startsWith('/') ? patch.path.slice(1) : patch.path
+            if (patch.op === 'add' || patch.op === 'replace') {
+              stateClone[key] = patch.value
+            } else if (patch.op === 'remove') {
+              delete stateClone[key]
+            }
+          }
+          newState.state = stateClone
+          return newState
+        }
+
+        if (isMessagesSnapshotEvent(event)) {
+          
+          // Filter out hidden messages from snapshot
+          const visibleMessages = event.messages.filter(msg => {
+            const isHidden = hiddenMessageIdsRef.current.has(msg.id)
+            return !isHidden
+          })
+          
+          // CRITICAL: Don't replace messages - merge snapshot with any in-progress streaming messages
+          // Snapshot contains completed messages, but streaming might have started new messages
+          // that aren't in the snapshot yet
+          const snapshotIds = new Set(visibleMessages.map(m => m.id))
+          const streamingMessages = newState.messages.filter(m => !snapshotIds.has(m.id))
+          
+          newState.messages = [...visibleMessages, ...streamingMessages]
+          return newState
+        }
+
+        if (isActivitySnapshotEvent(event)) {
+          newState.activities = event.activities
+          return newState
+        }
+
+        if (event.type === AGUIEventType.ACTIVITY_DELTA) {
+          const activitiesClone = [...newState.activities]
+          for (const patch of event.delta) {
+            if (patch.op === 'add') {
+              activitiesClone.push(patch.activity)
+            } else if (patch.op === 'update') {
+              const idx = activitiesClone.findIndex((a) => a.id === patch.activity.id)
+              if (idx >= 0) {
+                activitiesClone[idx] = patch.activity
+              }
+            } else if (patch.op === 'remove') {
+              const idx = activitiesClone.findIndex((a) => a.id === patch.activity.id)
+              if (idx >= 0) {
+                activitiesClone.splice(idx, 1)
+              }
+            }
+          }
+          newState.activities = activitiesClone
+          return newState
+        }
+
+        // Handle STEP events
+        if (event.type === AGUIEventType.STEP_STARTED) {
+          // Track current step in state
+          newState.state = {
+            ...newState.state,
+            currentStep: {
+              id: (event as AGUIStepStartedEvent).stepId,
+              name: (event as AGUIStepStartedEvent).stepName,
+              status: 'running',
+            },
+          }
+          return newState
+        }
+
+        if (event.type === AGUIEventType.STEP_FINISHED) {
+          // Clear current step
+          const stateClone = { ...newState.state }
+          delete stateClone.currentStep
+          newState.state = stateClone
+          return newState
+        }
+
+        // Handle RAW events (may contain message data or thinking blocks)
+        if (event.type === AGUIEventType.RAW) {
+          // RAW events use "event" field (AG-UI standard), or "data" field (legacy)
+          type RawEventData = { event?: Record<string, unknown>; data?: Record<string, unknown> }
+          const rawEvent = event as unknown as RawEventData
+          const rawData = rawEvent.event || rawEvent.data
+          
+          // Handle message metadata (for hiding auto-sent messages)
+          if (rawData?.type === 'message_metadata' && rawData?.hidden) {
+            const messageId = rawData.messageId as string
+            if (messageId) {
+              hiddenMessageIdsRef.current.add(messageId)
+            }
+            return newState
+          }
+          
+          const actualRawData = rawData
+          
+          // Handle thinking blocks from Claude SDK
+          if (actualRawData?.type === 'thinking_block') {
+            const msg: AGUIMessage = {
+              id: crypto.randomUUID(),
+              role: AGUIRole.ASSISTANT,
+              content: actualRawData.thinking as string || '',
+              metadata: {
+                type: 'thinking_block',
+                thinking: actualRawData.thinking as string,
+                signature: actualRawData.signature as string,
+              },
+            }
+            newState.messages = [...newState.messages, msg]
+            onMessage?.(msg)
+            return newState
+          }
+          
+          // Handle user message echoes from backend
+          if (actualRawData?.role === 'user' && actualRawData?.content) {
+            // Check if this message already exists to prevent duplicates
+            const messageId = (actualRawData.id as string) || crypto.randomUUID()
+            const exists = newState.messages.some(m => m.id === messageId)
+            if (!exists) {
+              const msg: AGUIMessage = {
+                id: messageId,
+                role: AGUIRole.USER,
+                content: actualRawData.content as string,
+              }
+              newState.messages = [...newState.messages, msg]
+              onMessage?.(msg)
+            }
+            return newState
+          }
+          
+          // Handle other message data
+          if (actualRawData?.role && actualRawData?.content) {
+            const msg: AGUIMessage = {
+              id: (actualRawData.id as string) || crypto.randomUUID(),
+              role: actualRawData.role as AGUIMessage['role'],
+              content: actualRawData.content as string,
+            }
+            newState.messages = [...newState.messages, msg]
+            onMessage?.(msg)
+          }
+          return newState
+        }
+
+        return newState
+      })
+    },
+    [onEvent, onMessage, onError],
+  )
+
+  // Connect to the AG-UI event stream
+  const connect = useCallback(
+    (runId?: string) => {
+      // Disconnect existing connection
+      if (eventSourceRef.current) {
+        eventSourceRef.current.close()
+        eventSourceRef.current = null
+      }
+
+      setState((prev) => ({
+        ...prev,
+        status: 'connecting',
+        error: null,
+      }))
+
+      // Build SSE URL through Next.js proxy
+      let url = `/api/projects/${encodeURIComponent(projectName)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/events`
+      if (runId) {
+        url += `?runId=${encodeURIComponent(runId)}`
+      }
+
+      const eventSource = new EventSource(url)
+      eventSourceRef.current = eventSource
+
+      eventSource.onopen = () => {
+        setState((prev) => ({
+          ...prev,
+          status: 'connected',
+        }))
+        onConnected?.()
+      }
+
+      eventSource.onmessage = (e) => {
+        try {
+          const event = JSON.parse(e.data) as AGUIEvent
+          processEvent(event)
+        } catch (err) {
+          console.error('Failed to parse AG-UI event:', err)
+        }
+      }
+
+      eventSource.onerror = (err) => {
+        console.error('AG-UI EventSource error:', err)
+        setState((prev) => ({
+          ...prev,
+          status: 'error',
+          error: 'Connection error',
+        }))
+        onError?.('Connection error')
+        onDisconnected?.()
+
+        // Attempt to reconnect after a delay
+        if (reconnectTimeoutRef.current) {
+          clearTimeout(reconnectTimeoutRef.current)
+        }
+        reconnectTimeoutRef.current = setTimeout(() => {
+          if (eventSourceRef.current === eventSource) {
+            connect(runId)
+          }
+        }, 3000)
+      }
+    },
+    [projectName, sessionName, processEvent, onConnected, onError, onDisconnected],
+  )
+
+  // Disconnect from the event stream
+  const disconnect = useCallback(() => {
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+      reconnectTimeoutRef.current = null
+    }
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close()
+      eventSourceRef.current = null
+    }
+    setState((prev) => ({
+      ...prev,
+      status: 'idle',
+    }))
+    setIsRunActive(false)
+    currentRunIdRef.current = null
+    onDisconnected?.()
+  }, [onDisconnected])
+
+  // Interrupt the current run (stop Claude mid-execution)
+  const interrupt = useCallback(
+    async () => {
+      const runId = currentRunIdRef.current
+      if (!runId) {
+        console.warn('[useAGUIStream] No active run to interrupt')
+        return
+      }
+
+      try {
+        const interruptUrl = `/api/projects/${encodeURIComponent(projectName)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/interrupt`
+
+        const response = await fetch(interruptUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ runId }),
+        })
+
+        if (!response.ok) {
+          throw new Error(`Failed to interrupt: ${response.statusText}`)
+        }
+        
+        // Mark run as inactive immediately (backend will send RUN_FINISHED or RUN_ERROR)
+        setIsRunActive(false)
+        currentRunIdRef.current = null
+        
+      } catch (error) {
+        console.error('[useAGUIStream] Interrupt failed:', error)
+        throw error
+      }
+    },
+    [projectName, sessionName],
+  )
+
+  // Send a message to start/continue the conversation
+  // AG-UI server pattern: POST returns SSE stream directly
+  const sendMessage = useCallback(
+    async (content: string) => {
+      // Set status to connected when starting a new message
+      setState((prev) => ({
+        ...prev,
+        status: 'connected',
+        error: null,
+      }))
+
+      // Send to backend via run endpoint - this returns an SSE stream
+      const runUrl = `/api/projects/${encodeURIComponent(projectName)}/agentic-sessions/${encodeURIComponent(sessionName)}/agui/run`
+
+      const userMessage = {
+        id: crypto.randomUUID(),
+        role: AGUIRole.USER,
+        content,
+      }
+
+
+      try {
+        const response = await fetch(runUrl, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            threadId: state.threadId || sessionName,
+            parentRunId: state.runId,
+            messages: [userMessage],
+          }),
+        })
+
+        if (!response.ok) {
+          const errorText = await response.text()
+          console.error(`[useAGUIStream] /agui/run error: ${errorText}`)
+          setState((prev) => ({
+            ...prev,
+            status: 'error',
+            error: errorText,
+          }))
+          setIsRunActive(false)
+          throw new Error(`Failed to send message: ${errorText}`)
+        }
+
+        // AG-UI middleware pattern: POST creates run and returns metadata immediately
+        // Events are broadcast to GET /agui/events subscribers (avoid concurrent streams)
+        const result = await response.json()
+        
+        // Mark run as active and track runId
+        if (result.runId) {
+          currentRunIdRef.current = result.runId
+          setIsRunActive(true)
+        }
+        
+        // Ensure we're connected to the thread stream to receive events
+        if (state.status !== 'connected') {
+          connect()
+        }
+      } catch (error) {
+        console.error(`[useAGUIStream] sendMessage error:`, error)
+        setState((prev) => ({
+          ...prev,
+          status: 'error',
+          error: error instanceof Error ? error.message : 'Unknown error',
+        }))
+        throw error
+      }
+    },
+    [projectName, sessionName, state.threadId, state.runId, state.status, processEvent, connect],
+  )
+
+  // Auto-connect on mount if enabled (client-side only)
+  const autoConnectAttemptedRef = useRef(false)
+  useEffect(() => {
+    if (typeof window === 'undefined') return // Skip during SSR
+    if (autoConnectAttemptedRef.current) return // Only auto-connect once
+    
+    if (autoConnect && mountedRef.current) {
+      autoConnectAttemptedRef.current = true
+      connect(initialRunId)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoConnect])
+
+  return {
+    state,
+    connect,
+    disconnect,
+    sendMessage,
+    interrupt,
+    isConnected: state.status === 'connected',
+    isStreaming: state.currentMessage !== null || state.currentToolCall !== null || state.pendingToolCalls.size > 0,
+    isRunActive,
+  }
+}
+
diff --git a/components/frontend/src/instrumentation.ts b/components/frontend/src/instrumentation.ts
new file mode 100644
index 000000000..83935f7ff
--- /dev/null
+++ b/components/frontend/src/instrumentation.ts
@@ -0,0 +1,21 @@
+/**
+ * Next.js instrumentation - runs once on server startup
+ * https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+ */
+
+export function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    // Log build information on server startup
+    console.log('==============================================');
+    console.log('Frontend - Build Information');
+    console.log('==============================================');
+    console.log(`Version:     ${process.env.NEXT_PUBLIC_GIT_VERSION || 'unknown'}`);
+    console.log(`Commit:      ${process.env.NEXT_PUBLIC_GIT_COMMIT || 'unknown'}`);
+    console.log(`Branch:      ${process.env.NEXT_PUBLIC_GIT_BRANCH || 'unknown'}`);
+    console.log(`Repository:  ${process.env.NEXT_PUBLIC_GIT_REPO || 'unknown'}`);
+    console.log(`Built:       ${process.env.NEXT_PUBLIC_BUILD_DATE || 'unknown'}`);
+    console.log(`Built by:    ${process.env.NEXT_PUBLIC_BUILD_USER || 'unknown'}`);
+    console.log('==============================================');
+  }
+}
+
diff --git a/components/frontend/src/services/api/sessions.ts b/components/frontend/src/services/api/sessions.ts
index 4c3ec275a..eeea7142b 100644
--- a/components/frontend/src/services/api/sessions.ts
+++ b/components/frontend/src/services/api/sessions.ts
@@ -14,8 +14,6 @@ import type {
   StopAgenticSessionResponse,
   CloneAgenticSessionRequest,
   CloneAgenticSessionResponse,
-  Message,
-  GetSessionMessagesResponse,
   PaginationParams,
 } from '@/types/api';
 
@@ -124,18 +122,7 @@ export async function cloneSession(
   return response.session;
 }
 
-/**
- * Get session messages
- */
-export async function getSessionMessages(
-  projectName: string,
-  sessionName: string
-): Promise<Message[]> {
-  const response = await apiClient.get<GetSessionMessagesResponse>(
-    `/projects/${projectName}/agentic-sessions/${sessionName}/messages`
-  );
-  return response.messages;
-}
+// getSessionMessages removed - replaced by AG-UI protocol
 
 /**
  * Delete a session
@@ -147,33 +134,7 @@ export async function deleteSession(
   await apiClient.delete(`/projects/${projectName}/agentic-sessions/${sessionName}`);
 }
 
-/**
- * Send a chat message to an interactive session
- */
-export async function sendChatMessage(
-  projectName: string,
-  sessionName: string,
-  content: string
-): Promise<void> {
-  await apiClient.post<void, { content: string }>(
-    `/projects/${projectName}/agentic-sessions/${sessionName}/messages`,
-    { content }
-  );
-}
-
-/**
- * Send a control message (interrupt, end_session) to a session
- */
-export async function sendControlMessage(
-  projectName: string,
-  sessionName: string,
-  type: 'interrupt' | 'end_session'
-): Promise<void> {
-  await apiClient.post<void, { type: string }>(
-    `/projects/${projectName}/agentic-sessions/${sessionName}/messages`,
-    { type }
-  );
-}
+// sendChatMessage and sendControlMessage removed - use AG-UI protocol
 
 /**
  * Get K8s resource information (job, pods, PVC) for a session
diff --git a/components/frontend/src/services/queries/use-sessions.ts b/components/frontend/src/services/queries/use-sessions.ts
index 10b78aa8c..088cdb4ea 100644
--- a/components/frontend/src/services/queries/use-sessions.ts
+++ b/components/frontend/src/services/queries/use-sessions.ts
@@ -59,6 +59,8 @@ export function useSession(projectName: string, sessionName: string) {
     queryKey: sessionKeys.detail(projectName, sessionName),
     queryFn: () => sessionsApi.getSession(projectName, sessionName),
     enabled: !!projectName && !!sessionName,
+    retry: 3, // Retry failed requests (useful during backend rollouts)
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 10000), // Exponential backoff
     // Poll for status updates based on session phase
     refetchInterval: (query) => {
       const session = query.state.data as AgenticSession | undefined;
@@ -90,33 +92,7 @@ export function useSession(projectName: string, sessionName: string) {
   });
 }
 
-/**
- * Hook to fetch session messages
- */
-export function useSessionMessages(projectName: string, sessionName: string, sessionPhase?: string) {
-  return useQuery({
-    queryKey: sessionKeys.messages(projectName, sessionName),
-    queryFn: () => sessionsApi.getSessionMessages(projectName, sessionName),
-    enabled: !!projectName && !!sessionName,
-    // Messages are typically handled via WebSocket, so longer stale time
-    staleTime: 5 * 1000, // 5 seconds
-    // Poll for message updates based on session phase
-    refetchInterval: () => {
-      // Transitional states - poll aggressively (every 1 second)
-      const isTransitioning =
-        sessionPhase === 'Stopping' ||
-        sessionPhase === 'Pending' ||
-        sessionPhase === 'Creating';
-      if (isTransitioning) return 1000;
-      
-      // Running state - poll normally (every 5 seconds)
-      if (sessionPhase === 'Running') return 5000;
-      
-      // Terminal states - no polling
-      return false;
-    },
-  });
-}
+// useSessionMessages removed - replaced by AG-UI protocol (useAGUIStream)
 
 /**
  * Hook to create a session
@@ -256,63 +232,7 @@ export function useDeleteSession() {
   });
 }
 
-/**
- * Hook to send chat message to interactive session
- */
-export function useSendChatMessage() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: ({
-      projectName,
-      sessionName,
-      content,
-    }: {
-      projectName: string;
-      sessionName: string;
-      content: string;
-    }) => sessionsApi.sendChatMessage(projectName, sessionName, content),
-    onSuccess: (_data, { projectName, sessionName }) => {
-      // Invalidate messages to refetch
-      queryClient.invalidateQueries({
-        queryKey: sessionKeys.messages(projectName, sessionName),
-      });
-      // Invalidate session to update status
-      queryClient.invalidateQueries({
-        queryKey: sessionKeys.detail(projectName, sessionName),
-      });
-    },
-  });
-}
-
-/**
- * Hook to send control message (interrupt, end_session)
- */
-export function useSendControlMessage() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: ({
-      projectName,
-      sessionName,
-      type,
-    }: {
-      projectName: string;
-      sessionName: string;
-      type: 'interrupt' | 'end_session';
-    }) => sessionsApi.sendControlMessage(projectName, sessionName, type),
-    onSuccess: (_data, { projectName, sessionName }) => {
-      // Invalidate messages to refetch
-      queryClient.invalidateQueries({
-        queryKey: sessionKeys.messages(projectName, sessionName),
-      });
-      // Invalidate session to update status
-      queryClient.invalidateQueries({
-        queryKey: sessionKeys.detail(projectName, sessionName),
-      });
-    },
-  });
-}
+// useSendChatMessage and useSendControlMessage removed - replaced by AG-UI protocol
 
 /**
  * Hook to fetch K8s resources (job, pods, PVC) for a session
diff --git a/components/frontend/src/types/agentic-session.ts b/components/frontend/src/types/agentic-session.ts
index bdaa85701..4deb326cb 100644
--- a/components/frontend/src/types/agentic-session.ts
+++ b/components/frontend/src/types/agentic-session.ts
@@ -93,6 +93,11 @@ export type ToolUseMessages = {
 	resultBlock: ToolResultBlock;
 	timestamp: string;
 }
+
+// Hierarchical tool message with nested children (for subagent rendering)
+export type HierarchicalToolMessage = ToolUseMessages & {
+	children?: ToolUseMessages[];
+}
 	
 // -----------------------------
 // Message Types
diff --git a/components/frontend/src/types/agui.ts b/components/frontend/src/types/agui.ts
new file mode 100644
index 000000000..d650daa74
--- /dev/null
+++ b/components/frontend/src/types/agui.ts
@@ -0,0 +1,371 @@
+/**
+ * AG-UI Protocol Types
+ * TypeScript types for AG-UI events and messages.
+ * 
+ * Reference: https://docs.ag-ui.com/concepts/events
+ * Reference: https://docs.ag-ui.com/concepts/messages
+ */
+
+// AG-UI Event Types
+export const AGUIEventType = {
+  // Lifecycle events
+  RUN_STARTED: 'RUN_STARTED',
+  RUN_FINISHED: 'RUN_FINISHED',
+  RUN_ERROR: 'RUN_ERROR',
+
+  // Step events
+  STEP_STARTED: 'STEP_STARTED',
+  STEP_FINISHED: 'STEP_FINISHED',
+
+  // Text message events (streaming)
+  TEXT_MESSAGE_START: 'TEXT_MESSAGE_START',
+  TEXT_MESSAGE_CONTENT: 'TEXT_MESSAGE_CONTENT',
+  TEXT_MESSAGE_END: 'TEXT_MESSAGE_END',
+
+  // Tool call events (streaming)
+  TOOL_CALL_START: 'TOOL_CALL_START',
+  TOOL_CALL_ARGS: 'TOOL_CALL_ARGS',
+  TOOL_CALL_END: 'TOOL_CALL_END',
+
+  // State management events
+  STATE_SNAPSHOT: 'STATE_SNAPSHOT',
+  STATE_DELTA: 'STATE_DELTA',
+
+  // Message snapshot for restore/reconnect
+  MESSAGES_SNAPSHOT: 'MESSAGES_SNAPSHOT',
+
+  // Activity events
+  ACTIVITY_SNAPSHOT: 'ACTIVITY_SNAPSHOT',
+  ACTIVITY_DELTA: 'ACTIVITY_DELTA',
+
+  // Raw event
+  RAW: 'RAW',
+} as const
+
+export type AGUIEventTypeValue = (typeof AGUIEventType)[keyof typeof AGUIEventType]
+
+// AG-UI Message Roles
+export const AGUIRole = {
+  USER: 'user',
+  ASSISTANT: 'assistant',
+  SYSTEM: 'system',
+  TOOL: 'tool',
+  DEVELOPER: 'developer',
+  ACTIVITY: 'activity',
+} as const
+
+export type AGUIRoleValue = (typeof AGUIRole)[keyof typeof AGUIRole]
+
+// Base event structure
+export type AGUIBaseEvent = {
+  type: AGUIEventTypeValue
+  threadId: string
+  runId: string
+  timestamp: string
+  messageId?: string
+  parentRunId?: string
+}
+
+// Run input/output types
+export type AGUIRunAgentInput = {
+  threadId?: string
+  runId?: string
+  parentRunId?: string
+  messages?: AGUIMessage[]
+  state?: Record<string, unknown>
+  tools?: AGUIToolDefinition[]
+  context?: Record<string, unknown>
+}
+
+export type AGUIRunAgentOutput = {
+  threadId: string
+  runId: string
+  parentRunId?: string
+  streamUrl?: string
+}
+
+// Message type
+export type AGUIMessage = {
+  id: string
+  role: AGUIRoleValue
+  content?: string
+  toolCalls?: AGUIToolCall[]
+  toolCallId?: string
+  name?: string
+  timestamp?: string
+  metadata?: unknown
+  parentToolUseId?: string  // For hierarchical tool calls (sub-agents)
+  children?: AGUIMessage[]  // Nested tool calls under this tool
+}
+
+// Tool types
+export type AGUIToolCall = {
+  id: string
+  name: string
+  args: string
+  type?: string
+  parentToolUseId?: string  // For parent-child relationships (sub-agents)
+  result?: string
+  status?: 'pending' | 'running' | 'completed' | 'error'
+  error?: string
+  duration?: number
+}
+
+export type AGUIToolDefinition = {
+  name: string
+  description?: string
+  parameters?: Record<string, unknown>
+}
+
+// Lifecycle events
+export type AGUIRunStartedEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.RUN_STARTED
+  input?: AGUIRunAgentInput
+}
+
+export type AGUIRunFinishedEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.RUN_FINISHED
+  output?: unknown
+}
+
+export type AGUIRunErrorEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.RUN_ERROR
+  error: string
+  code?: string
+  details?: string
+}
+
+// Step events
+export type AGUIStepStartedEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.STEP_STARTED
+  stepId: string
+  stepName: string
+}
+
+export type AGUIStepFinishedEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.STEP_FINISHED
+  stepId: string
+  stepName: string
+  duration?: number
+}
+
+// Text message events
+export type AGUITextMessageStartEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.TEXT_MESSAGE_START
+  role: AGUIRoleValue
+}
+
+export type AGUITextMessageContentEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.TEXT_MESSAGE_CONTENT
+  delta: string
+}
+
+export type AGUITextMessageEndEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.TEXT_MESSAGE_END
+}
+
+// Tool call events
+export type AGUIToolCallStartEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.TOOL_CALL_START
+  toolCallId: string
+  toolCallName: string
+  parentMessageId?: string
+  parentToolUseId?: string
+}
+
+export type AGUIToolCallArgsEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.TOOL_CALL_ARGS
+  toolCallId: string
+  delta: string
+}
+
+export type AGUIToolCallEndEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.TOOL_CALL_END
+  toolCallId: string
+  result?: string
+  error?: string
+  duration?: number
+}
+
+// State events
+export type AGUIStateSnapshotEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.STATE_SNAPSHOT
+  state: Record<string, unknown>
+}
+
+export type AGUIStateDeltaEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.STATE_DELTA
+  delta: AGUIStatePatch[]
+}
+
+export type AGUIStatePatch = {
+  op: 'add' | 'remove' | 'replace'
+  path: string
+  value?: unknown
+}
+
+// Message snapshot event
+export type AGUIMessagesSnapshotEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.MESSAGES_SNAPSHOT
+  messages: AGUIMessage[]
+}
+
+// Activity types
+export type AGUIActivity = {
+  id: string
+  type: string
+  title?: string
+  status?: 'pending' | 'running' | 'completed' | 'error'
+  progress?: number
+  data?: Record<string, unknown>
+}
+
+export type AGUIActivitySnapshotEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.ACTIVITY_SNAPSHOT
+  activities: AGUIActivity[]
+}
+
+export type AGUIActivityDeltaEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.ACTIVITY_DELTA
+  delta: AGUIActivityPatch[]
+}
+
+export type AGUIActivityPatch = {
+  op: 'add' | 'update' | 'remove'
+  activity: AGUIActivity
+}
+
+// Raw event
+export type AGUIRawEvent = AGUIBaseEvent & {
+  type: typeof AGUIEventType.RAW
+  data: unknown
+}
+
+// Union of all event types
+export type AGUIEvent =
+  | AGUIRunStartedEvent
+  | AGUIRunFinishedEvent
+  | AGUIRunErrorEvent
+  | AGUIStepStartedEvent
+  | AGUIStepFinishedEvent
+  | AGUITextMessageStartEvent
+  | AGUITextMessageContentEvent
+  | AGUITextMessageEndEvent
+  | AGUIToolCallStartEvent
+  | AGUIToolCallArgsEvent
+  | AGUIToolCallEndEvent
+  | AGUIStateSnapshotEvent
+  | AGUIStateDeltaEvent
+  | AGUIMessagesSnapshotEvent
+  | AGUIActivitySnapshotEvent
+  | AGUIActivityDeltaEvent
+  | AGUIRawEvent
+
+// Run metadata type
+export type AGUIRunMetadata = {
+  threadId: string
+  runId: string
+  parentRunId?: string
+  sessionName: string
+  projectName: string
+  startedAt: string
+  finishedAt?: string
+  status: 'running' | 'completed' | 'error'
+  eventCount?: number
+  restartCount?: number
+}
+
+// History response type
+export type AGUIHistoryResponse = {
+  threadId: string
+  runId?: string
+  messages: AGUIMessage[]
+  runs: AGUIRunMetadata[]
+}
+
+// Runs response type
+export type AGUIRunsResponse = {
+  threadId: string
+  runs: AGUIRunMetadata[]
+}
+
+// Pending tool call being streamed
+export type PendingToolCall = {
+  id: string
+  name: string
+  args: string
+  parentToolUseId?: string
+}
+
+// Client state for AG-UI streaming
+export type AGUIClientState = {
+  threadId: string | null
+  runId: string | null
+  status: 'idle' | 'connecting' | 'connected' | 'error' | 'completed'
+  messages: AGUIMessage[]
+  state: Record<string, unknown>
+  activities: AGUIActivity[]
+  currentMessage: {
+    id: string | null
+    role: AGUIRoleValue | null
+    content: string
+  } | null
+  // DEPRECATED: Use pendingToolCalls instead for parallel tool call support
+  currentToolCall: {
+    id: string | null
+    name: string | null
+    args: string
+    parentToolUseId?: string
+  } | null
+  // Track ALL in-progress tool calls (supports parallel tool execution)
+  pendingToolCalls: Map<string, PendingToolCall>
+  // Track child tools that finished before their parent
+  pendingChildren: Map<string, AGUIMessage[]>
+  error: string | null
+}
+
+// Type guard functions
+export function isRunStartedEvent(event: AGUIEvent): event is AGUIRunStartedEvent {
+  return event.type === AGUIEventType.RUN_STARTED
+}
+
+export function isRunFinishedEvent(event: AGUIEvent): event is AGUIRunFinishedEvent {
+  return event.type === AGUIEventType.RUN_FINISHED
+}
+
+export function isRunErrorEvent(event: AGUIEvent): event is AGUIRunErrorEvent {
+  return event.type === AGUIEventType.RUN_ERROR
+}
+
+export function isTextMessageStartEvent(event: AGUIEvent): event is AGUITextMessageStartEvent {
+  return event.type === AGUIEventType.TEXT_MESSAGE_START
+}
+
+export function isTextMessageContentEvent(event: AGUIEvent): event is AGUITextMessageContentEvent {
+  return event.type === AGUIEventType.TEXT_MESSAGE_CONTENT
+}
+
+export function isTextMessageEndEvent(event: AGUIEvent): event is AGUITextMessageEndEvent {
+  return event.type === AGUIEventType.TEXT_MESSAGE_END
+}
+
+export function isToolCallStartEvent(event: AGUIEvent): event is AGUIToolCallStartEvent {
+  return event.type === AGUIEventType.TOOL_CALL_START
+}
+
+export function isToolCallEndEvent(event: AGUIEvent): event is AGUIToolCallEndEvent {
+  return event.type === AGUIEventType.TOOL_CALL_END
+}
+
+export function isStateSnapshotEvent(event: AGUIEvent): event is AGUIStateSnapshotEvent {
+  return event.type === AGUIEventType.STATE_SNAPSHOT
+}
+
+export function isMessagesSnapshotEvent(event: AGUIEvent): event is AGUIMessagesSnapshotEvent {
+  return event.type === AGUIEventType.MESSAGES_SNAPSHOT
+}
+
+export function isActivitySnapshotEvent(event: AGUIEvent): event is AGUIActivitySnapshotEvent {
+  return event.type === AGUIEventType.ACTIVITY_SNAPSHOT
+}
+
diff --git a/components/frontend/src/types/index.ts b/components/frontend/src/types/index.ts
index 24b77db30..9cea54ff4 100644
--- a/components/frontend/src/types/index.ts
+++ b/components/frontend/src/types/index.ts
@@ -1,5 +1,8 @@
 // Core types for RFE Workflows and GitHub integration
 
+// AG-UI Protocol types
+export * from './agui'
+
 export interface Project {
   name: string;
   displayName: string;
diff --git a/components/manifests/overlays/production/kustomization.yaml b/components/manifests/overlays/production/kustomization.yaml
index 324543b64..14b3e3e64 100644
--- a/components/manifests/overlays/production/kustomization.yaml
+++ b/components/manifests/overlays/production/kustomization.yaml
@@ -37,23 +37,23 @@ images:
   newName: quay.io/ambient_code/vteam_backend
   newTag: latest
 - name: quay.io/ambient_code/vteam_backend:latest
-  newName: quay.io/ambient_code/vteam_backend
+  newName: quay.io/gkrumbach07/vteam_backend
   newTag: latest
 - name: quay.io/ambient_code/vteam_claude_runner
   newName: quay.io/ambient_code/vteam_claude_runner
   newTag: latest
 - name: quay.io/ambient_code/vteam_claude_runner:latest
-  newName: quay.io/ambient_code/vteam_claude_runner
+  newName: quay.io/gkrumbach07/vteam_claude_runner
   newTag: latest
 - name: quay.io/ambient_code/vteam_frontend
   newName: quay.io/ambient_code/vteam_frontend
   newTag: latest
 - name: quay.io/ambient_code/vteam_frontend:latest
-  newName: quay.io/ambient_code/vteam_frontend
+  newName: quay.io/gkrumbach07/vteam_frontend
   newTag: latest
 - name: quay.io/ambient_code/vteam_operator
   newName: quay.io/ambient_code/vteam_operator
   newTag: latest
 - name: quay.io/ambient_code/vteam_operator:latest
-  newName: quay.io/ambient_code/vteam_operator
+  newName: quay.io/gkrumbach07/vteam_operator
   newTag: latest
diff --git a/components/operator/Dockerfile b/components/operator/Dockerfile
index 2cdd8a33b..04472f6d6 100644
--- a/components/operator/Dockerfile
+++ b/components/operator/Dockerfile
@@ -1,6 +1,14 @@
 # Build stage
 FROM registry.access.redhat.com/ubi9/go-toolset:1.24 AS builder
 
+# Build arguments for metadata
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
 USER 0
 WORKDIR /app
 
@@ -13,19 +21,48 @@ RUN go mod download
 # Copy the source code
 COPY . .
 
-# Build the application (with flags to avoid segfault)
-RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o operator .
+# Build the application with embedded version info
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -ldflags="-s -w \
+    -X main.GitCommit=${GIT_COMMIT} \
+    -X main.GitBranch=${GIT_BRANCH} \
+    -X main.GitVersion=${GIT_VERSION} \
+    -X main.BuildDate=${BUILD_DATE}" \
+    -o operator .
 
 # Final stage
 FROM registry.access.redhat.com/ubi9/ubi-minimal:latest
 
+# Build arguments (need to redeclare for final stage)
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
+# Add labels to force cache invalidation and provide metadata
+LABEL git.commit="${GIT_COMMIT}"
+LABEL git.branch="${GIT_BRANCH}"
+LABEL git.version="${GIT_VERSION}"
+LABEL build.date="${BUILD_DATE}"
+LABEL build.user="${BUILD_USER}"
+
 WORKDIR /app
 
 RUN microdnf install -y procps && microdnf clean all
 
-# Copy the binary from builder stage
+# Copy the binary from builder stage (binary has metadata embedded via ldflags)
 COPY --from=builder /app/operator .
 
+# Build metadata as environment variables (fallback, primary source is embedded in binary)
+ENV GIT_COMMIT=${GIT_COMMIT}
+ENV GIT_BRANCH=${GIT_BRANCH}
+ENV GIT_REPO=${GIT_REPO}
+ENV GIT_VERSION=${GIT_VERSION}
+ENV BUILD_DATE=${BUILD_DATE}
+ENV BUILD_USER=${BUILD_USER}
+
 # Set executable permissions and make accessible to any user
 RUN chmod +x ./operator && chmod 775 /app
 
diff --git a/components/operator/internal/handlers/sessions.go b/components/operator/internal/handlers/sessions.go
index 9a27e320d..862d82027 100644
--- a/components/operator/internal/handlers/sessions.go
+++ b/components/operator/internal/handlers/sessions.go
@@ -444,7 +444,6 @@ func handleAgenticSessionEvent(obj *unstructured.Unstructured) error {
 
 	// Handle Running phase - check for generation changes (spec updates)
 	if phase == "Running" {
-		log.Printf("[Reconcile] Session %s/%s is Running, checking for spec changes", sessionNamespace, name)
 
 		currentGeneration := currentObj.GetGeneration()
 		observedGeneration := int64(0)
@@ -457,9 +456,6 @@ func handleAgenticSessionEvent(obj *unstructured.Unstructured) error {
 		}
 
 		if currentGeneration > observedGeneration {
-			log.Printf("[Reconcile] Session %s/%s: detected spec change (generation %d > observed %d), reconciling repos and workflow",
-				sessionNamespace, name, currentGeneration, observedGeneration)
-
 			spec, _, _ := unstructured.NestedMap(currentObj.Object, "spec")
 			reposErr := reconcileSpecReposWithPatch(sessionNamespace, name, spec, currentObj, statusPatch)
 			if reposErr != nil {
@@ -500,9 +496,6 @@ func handleAgenticSessionEvent(obj *unstructured.Unstructured) error {
 			if err := statusPatch.Apply(); err != nil {
 				log.Printf("[Reconcile] Warning: failed to apply status patch: %v", err)
 			}
-			log.Printf("[Reconcile] Session %s/%s: updated observedGeneration to %d after successful reconciliation", sessionNamespace, name, currentGeneration)
-		} else {
-			log.Printf("[Reconcile] Session %s/%s: no spec changes detected (generation %d == observed %d)", sessionNamespace, name, currentGeneration, observedGeneration)
 		}
 
 		return nil
@@ -1100,6 +1093,13 @@ func handleAgenticSessionEvent(obj *unstructured.Unstructured) error {
 								},
 							},
 
+							// Expose AG-UI server port for backend proxy
+							Ports: []corev1.ContainerPort{{
+								Name:          "agui",
+								ContainerPort: 8000,
+								Protocol:      corev1.ProtocolTCP,
+							}},
+
 							VolumeMounts: []corev1.VolumeMount{
 								{Name: "workspace", MountPath: "/workspace", ReadOnly: false},
 								// Mount .claude directory for session state persistence
@@ -1150,12 +1150,12 @@ func handleAgenticSessionEvent(obj *unstructured.Unstructured) error {
 									corev1.EnvVar{Name: "LLM_MODEL", Value: model},
 									corev1.EnvVar{Name: "LLM_TEMPERATURE", Value: fmt.Sprintf("%.2f", temperature)},
 									corev1.EnvVar{Name: "LLM_MAX_TOKENS", Value: fmt.Sprintf("%d", maxTokens)},
+									corev1.EnvVar{Name: "USE_AGUI", Value: "true"},
 									corev1.EnvVar{Name: "TIMEOUT", Value: fmt.Sprintf("%d", timeout)},
 									corev1.EnvVar{Name: "AUTO_PUSH_ON_COMPLETE", Value: fmt.Sprintf("%t", autoPushOnComplete)},
 									corev1.EnvVar{Name: "BACKEND_API_URL", Value: fmt.Sprintf("http://backend-service.%s.svc.cluster.local:8080/api", appConfig.BackendNamespace)},
-									// WebSocket URL used by runner-shell to connect back to backend
-									corev1.EnvVar{Name: "WEBSOCKET_URL", Value: fmt.Sprintf("ws://backend-service.%s.svc.cluster.local:8080/api/projects/%s/sessions/%s/ws", appConfig.BackendNamespace, sessionNamespace, name)},
-									// S3 disabled; backend persists messages
+									// LEGACY: WEBSOCKET_URL removed - runner now uses AG-UI server pattern (FastAPI)
+									// Backend proxies to runner's HTTP endpoint instead of WebSocket
 								)
 
 								// Platform-wide Langfuse observability configuration
@@ -1479,6 +1479,41 @@ func handleAgenticSessionEvent(obj *unstructured.Unstructured) error {
 		log.Printf("Failed to create per-job content service for %s: %v", name, serr)
 	}
 
+	// Create AG-UI Service pointing to the runner's FastAPI server
+	// Backend proxies AG-UI requests to this service endpoint
+	aguiSvc := &corev1.Service{
+		ObjectMeta: v1.ObjectMeta{
+			Name:      fmt.Sprintf("session-%s", name),
+			Namespace: sessionNamespace,
+			Labels: map[string]string{
+				"app":             "ambient-code",
+				"agentic-session": name,
+			},
+			OwnerReferences: []v1.OwnerReference{{
+				APIVersion: "batch/v1",
+				Kind:       "Job",
+				Name:       jobName,
+				UID:        createdJob.UID,
+				Controller: boolPtr(true),
+			}},
+		},
+		Spec: corev1.ServiceSpec{
+			Type:     corev1.ServiceTypeClusterIP,
+			Selector: map[string]string{"job-name": jobName},
+			Ports: []corev1.ServicePort{{
+				Name:       "agui",
+				Protocol:   corev1.ProtocolTCP,
+				Port:       8000,
+				TargetPort: intstr.FromInt(8000),
+			}},
+		},
+	}
+	if _, serr := config.K8sClient.CoreV1().Services(sessionNamespace).Create(context.TODO(), aguiSvc, v1.CreateOptions{}); serr != nil && !errors.IsAlreadyExists(serr) {
+		log.Printf("Failed to create AG-UI service for %s: %v", name, serr)
+	} else {
+		log.Printf("Created AG-UI service session-%s for AgenticSession %s", name, name)
+	}
+
 	// Start monitoring the job (only if not already being monitored)
 	monitorKey := fmt.Sprintf("%s/%s", sessionNamespace, jobName)
 	monitoredJobsMu.Lock()
@@ -1500,7 +1535,6 @@ func handleAgenticSessionEvent(obj *unstructured.Unstructured) error {
 func reconcileSpecReposWithPatch(sessionNamespace, sessionName string, spec map[string]interface{}, session *unstructured.Unstructured, statusPatch *StatusPatch) error {
 	repoSlice, found, _ := unstructured.NestedSlice(spec, "repos")
 	if !found {
-		log.Printf("[Reconcile] Session %s/%s: no repos defined in spec", sessionNamespace, sessionName)
 		statusPatch.DeleteField("reconciledRepos")
 		statusPatch.AddCondition(conditionUpdate{
 			Type:    conditionReposReconciled,
@@ -1580,52 +1614,70 @@ func reconcileSpecReposWithPatch(sessionNamespace, sessionName string, spec map[
 	}
 
 	if len(toAdd) == 0 && len(toRemove) == 0 {
-		log.Printf("[Reconcile] Session %s/%s: repos already reconciled (%d repos)", sessionNamespace, sessionName, len(specRepos))
 		return nil
 	}
 
-	log.Printf("[Reconcile] Session %s/%s: detected repo drift - adding %d, removing %d", sessionNamespace, sessionName, len(toAdd), len(toRemove))
-
-	// Send WebSocket messages via backend to trigger runner actions
-	backendURL := getBackendAPIURL(sessionNamespace)
+	// AG-UI pattern: Call runner's REST endpoints to update configuration
+	// Runner will restart Claude SDK client with new repo configuration
+	runnerBaseURL := fmt.Sprintf("http://session-%s.%s.svc.cluster.local:8000", sessionName, sessionNamespace)
 
 	// Add repos
 	for _, repo := range toAdd {
 		repoName := deriveRepoNameFromURL(repo["url"])
-		log.Printf("[Reconcile] Session %s/%s: sending repo_added message for %s (%s@%s)", sessionNamespace, sessionName, repoName, repo["url"], repo["branch"])
-		if err := sendWebSocketMessageViaBackend(sessionNamespace, sessionName, backendURL, map[string]interface{}{
-			"type":   "repo_added",
+
+		payload := map[string]interface{}{
 			"url":    repo["url"],
 			"branch": repo["branch"],
 			"name":   repoName,
-		}); err != nil {
-			log.Printf("[Reconcile] Failed to send repo_added message: %v", err)
-			statusPatch.AddCondition(conditionUpdate{
-				Type:    conditionReposReconciled,
-				Status:  "False",
-				Reason:  "MessageFailed",
-				Message: fmt.Sprintf("Failed to notify runner: %v", err),
-			})
-			return fmt.Errorf("failed to send repo_added message: %w", err)
+		}
+		payloadBytes, _ := json.Marshal(payload)
+
+		req, err := http.NewRequest("POST", runnerBaseURL+"/repos/add", bytes.NewReader(payloadBytes))
+		if err != nil {
+			log.Printf("[Reconcile] Failed to create repo add request: %v", err)
+			continue
+		}
+		req.Header.Set("Content-Type", "application/json")
+
+		client := &http.Client{Timeout: 10 * time.Second}
+		resp, err := client.Do(req)
+		if err != nil {
+			log.Printf("[Reconcile] Failed to add repo via runner: %v", err)
+			continue
+		}
+		resp.Body.Close()
+
+		if resp.StatusCode != http.StatusOK {
+			log.Printf("[Reconcile] Runner returned %d for repo add", resp.StatusCode)
 		}
 	}
 
 	// Remove repos
 	for _, repo := range toRemove {
 		repoName := deriveRepoNameFromURL(repo["url"])
-		log.Printf("[Reconcile] Session %s/%s: sending repo_removed message for %s", sessionNamespace, sessionName, repoName)
-		if err := sendWebSocketMessageViaBackend(sessionNamespace, sessionName, backendURL, map[string]interface{}{
-			"type": "repo_removed",
+
+		payload := map[string]interface{}{
 			"name": repoName,
-		}); err != nil {
-			log.Printf("[Reconcile] Failed to send repo_removed message: %v", err)
-			statusPatch.AddCondition(conditionUpdate{
-				Type:    conditionReposReconciled,
-				Status:  "False",
-				Reason:  "MessageFailed",
-				Message: fmt.Sprintf("Failed to notify runner: %v", err),
-			})
-			return fmt.Errorf("failed to send repo_removed message: %w", err)
+		}
+		payloadBytes, _ := json.Marshal(payload)
+
+		req, err := http.NewRequest("POST", runnerBaseURL+"/repos/remove", bytes.NewReader(payloadBytes))
+		if err != nil {
+			log.Printf("[Reconcile] Failed to create repo remove request: %v", err)
+			continue
+		}
+		req.Header.Set("Content-Type", "application/json")
+
+		client := &http.Client{Timeout: 10 * time.Second}
+		resp, err := client.Do(req)
+		if err != nil {
+			log.Printf("[Reconcile] Failed to remove repo via runner: %v", err)
+			continue
+		}
+		resp.Body.Close()
+
+		if resp.StatusCode != http.StatusOK {
+			log.Printf("[Reconcile] Runner returned %d for repo remove", resp.StatusCode)
 		}
 	}
 
@@ -1647,7 +1699,6 @@ func reconcileSpecReposWithPatch(sessionNamespace, sessionName string, spec map[
 		Message: fmt.Sprintf("Reconciled %d repos (added: %d, removed: %d)", len(specRepos), len(toAdd), len(toRemove)),
 	})
 
-	log.Printf("[Reconcile] Session %s/%s: successfully reconciled repos", sessionNamespace, sessionName)
 	return nil
 }
 
@@ -1655,7 +1706,6 @@ func reconcileSpecReposWithPatch(sessionNamespace, sessionName string, spec map[
 func reconcileActiveWorkflowWithPatch(sessionNamespace, sessionName string, spec map[string]interface{}, session *unstructured.Unstructured, statusPatch *StatusPatch) error {
 	workflow, found, _ := unstructured.NestedMap(spec, "activeWorkflow")
 	if !found || len(workflow) == 0 {
-		log.Printf("[Reconcile] Session %s/%s: no workflow defined in spec", sessionNamespace, sessionName)
 		statusPatch.DeleteField("reconciledWorkflow")
 		statusPatch.AddCondition(conditionUpdate{
 			Type:    conditionWorkflowReconciled,
@@ -1674,7 +1724,6 @@ func reconcileActiveWorkflowWithPatch(sessionNamespace, sessionName string, spec
 	path, _ := workflow["path"].(string)
 
 	if strings.TrimSpace(gitURL) == "" {
-		log.Printf("[Reconcile] Session %s/%s: workflow gitUrl is empty", sessionNamespace, sessionName)
 		return nil
 	}
 
@@ -1686,31 +1735,51 @@ func reconcileActiveWorkflowWithPatch(sessionNamespace, sessionName string, spec
 
 	// Detect drift: workflow changed
 	if reconciledGitURL == gitURL && reconciledBranch == branch {
-		log.Printf("[Reconcile] Session %s/%s: workflow already reconciled (%s@%s)", sessionNamespace, sessionName, gitURL, branch)
 		return nil
 	}
 
-	log.Printf("[Reconcile] Session %s/%s: detected workflow drift - switching from %s@%s to %s@%s",
-		sessionNamespace, sessionName, reconciledGitURL, reconciledBranch, gitURL, branch)
+	// AG-UI pattern: Call runner's /workflow endpoint to update configuration
+	// Runner will restart Claude SDK client with new workflow
+	runnerURL := fmt.Sprintf("http://session-%s.%s.svc.cluster.local:8000/workflow", sessionName, sessionNamespace)
 
-	// Send WebSocket message via backend to trigger runner workflow switch
-	backendURL := getBackendAPIURL(sessionNamespace)
-	log.Printf("[Reconcile] Session %s/%s: sending workflow_change message for %s@%s (path: %s)", sessionNamespace, sessionName, gitURL, branch, path)
-
-	if err := sendWebSocketMessageViaBackend(sessionNamespace, sessionName, backendURL, map[string]interface{}{
-		"type":   "workflow_change",
+	payload := map[string]interface{}{
 		"gitUrl": gitURL,
 		"branch": branch,
 		"path":   path,
-	}); err != nil {
-		log.Printf("[Reconcile] Failed to send workflow_change message: %v", err)
+	}
+	payloadBytes, _ := json.Marshal(payload)
+
+	req, err := http.NewRequest("POST", runnerURL, bytes.NewReader(payloadBytes))
+	if err != nil {
+		log.Printf("[Reconcile] Failed to create workflow request: %v", err)
+		return fmt.Errorf("failed to create workflow request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		log.Printf("[Reconcile] Failed to send workflow change to runner: %v", err)
 		statusPatch.AddCondition(conditionUpdate{
 			Type:    conditionWorkflowReconciled,
 			Status:  "False",
-			Reason:  "MessageFailed",
+			Reason:  "UpdateFailed",
 			Message: fmt.Sprintf("Failed to notify runner: %v", err),
 		})
-		return fmt.Errorf("failed to send workflow_selected message: %w", err)
+		return fmt.Errorf("failed to update runner workflow: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		log.Printf("[Reconcile] Runner returned non-200 for workflow change: %d - %s", resp.StatusCode, string(body))
+		statusPatch.AddCondition(conditionUpdate{
+			Type:    conditionWorkflowReconciled,
+			Status:  "False",
+			Reason:  "UpdateFailed",
+			Message: fmt.Sprintf("Runner returned %d", resp.StatusCode),
+		})
+		return fmt.Errorf("runner workflow update failed: %d", resp.StatusCode)
 	}
 
 	// Update status to reflect the reconciled state (via statusPatch)
@@ -1728,7 +1797,6 @@ func reconcileActiveWorkflowWithPatch(sessionNamespace, sessionName string, spec
 		Message: fmt.Sprintf("Switched to workflow %s@%s", gitURL, branch),
 	})
 
-	log.Printf("[Reconcile] Session %s/%s: successfully reconciled workflow", sessionNamespace, sessionName)
 	return nil
 }
 
@@ -2355,58 +2423,8 @@ func reconcileTempContentPodWithPatch(sessionNamespace, sessionName, tempPodName
 	return nil
 }
 
-// getBackendAPIURL returns the backend API URL for the given namespace
-func getBackendAPIURL(namespace string) string {
-	appConfig := config.LoadConfig()
-	return fmt.Sprintf("http://backend-service.%s.svc.cluster.local:8080/api", appConfig.BackendNamespace)
-}
-
-// sendWebSocketMessageViaBackend sends a WebSocket message to the runner via the backend's message endpoint
-func sendWebSocketMessageViaBackend(namespace, sessionName, backendURL string, message map[string]interface{}) error {
-	// The backend exposes POST /api/projects/:project/sessions/:sessionName/messages
-	// Format: { "type": "repo_added", "payload": {...}, ...other fields }
-	// Backend will extract "type" and wrap remaining fields under "payload" if needed
-	url := fmt.Sprintf("%s/projects/%s/sessions/%s/messages", backendURL, namespace, sessionName)
-
-	payload, err := json.Marshal(message)
-	if err != nil {
-		return fmt.Errorf("failed to marshal message: %w", err)
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-
-	// Use operator's service account token for authentication
-	// The backend accepts internal calls from the operator namespace
-	// Get the operator's SA token from the mounted service account
-	tokenBytes, err := os.ReadFile("/var/run/secrets/kubernetes.io/serviceaccount/token")
-	if err == nil && len(tokenBytes) > 0 {
-		req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", string(tokenBytes)))
-	} else {
-		log.Printf("[WebSocket] Warning: could not read operator SA token, request may fail: %v", err)
-	}
-
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
-	if err != nil {
-		return fmt.Errorf("failed to send request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusAccepted {
-		body, _ := io.ReadAll(resp.Body)
-		return fmt.Errorf("backend returned status %d: %s", resp.StatusCode, string(body))
-	}
-
-	log.Printf("[WebSocket] Successfully sent message type=%s to session %s/%s via backend", message["type"], namespace, sessionName)
-	return nil
-}
+// LEGACY: getBackendAPIURL removed - AG-UI migration
+// Workflow and repo changes now call runner's REST endpoints directly
 
 // deriveRepoNameFromURL extracts the repository name from a git URL
 func deriveRepoNameFromURL(repoURL string) string {
diff --git a/components/operator/main.go b/components/operator/main.go
index a31b0913e..df9c31821 100644
--- a/components/operator/main.go
+++ b/components/operator/main.go
@@ -9,7 +9,39 @@ import (
 	"ambient-code-operator/internal/preflight"
 )
 
+// Build-time metadata (set via -ldflags -X during build)
+// These are embedded directly in the binary, so they're always accurate
+var (
+	GitCommit  = "unknown"
+	GitBranch  = "unknown"
+	GitVersion = "unknown"
+	BuildDate  = "unknown"
+)
+
+func logBuildInfo() {
+	log.Println("==============================================")
+	log.Println("Agentic Session Operator - Build Information")
+	log.Println("==============================================")
+	log.Printf("Version:     %s", GitVersion)
+	log.Printf("Commit:      %s", GitCommit)
+	log.Printf("Branch:      %s", GitBranch)
+	log.Printf("Repository:  %s", getEnvOrDefault("GIT_REPO", "unknown"))
+	log.Printf("Built:       %s", BuildDate)
+	log.Printf("Built by:    %s", getEnvOrDefault("BUILD_USER", "unknown"))
+	log.Println("==============================================")
+}
+
+func getEnvOrDefault(key, defaultValue string) string {
+	if value := os.Getenv(key); value != "" {
+		return value
+	}
+	return defaultValue
+}
+
 func main() {
+	// Log build information
+	logBuildInfo()
+
 	// Initialize Kubernetes clients
 	if err := config.InitK8sClients(); err != nil {
 		log.Fatalf("Failed to initialize Kubernetes clients: %v", err)
diff --git a/components/runners/claude-code-runner/Dockerfile b/components/runners/claude-code-runner/Dockerfile
index 5af17b0c8..fc468d68a 100644
--- a/components/runners/claude-code-runner/Dockerfile
+++ b/components/runners/claude-code-runner/Dockerfile
@@ -1,5 +1,20 @@
 FROM registry.access.redhat.com/ubi9/python-311@sha256:d0b35f779ca0ae87deaf17cd1923461904f52d3ef249a53dbd487e02bdabdde6
 
+# Build arguments for metadata
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
+# Add labels to force cache invalidation and provide metadata
+LABEL git.commit="${GIT_COMMIT}"
+LABEL git.branch="${GIT_BRANCH}"
+LABEL git.version="${GIT_VERSION}"
+LABEL build.date="${BUILD_DATE}"
+LABEL build.user="${BUILD_USER}"
+
 USER 0
 
 # Add GitHub CLI repository and install packages
@@ -15,16 +30,11 @@ RUN pip install --no-cache-dir uv
 # Create working directory
 WORKDIR /app
 
-# Copy and install runner-shell package (expects build context at components/runners)
-COPY runner-shell /app/runner-shell
-RUN cd /app/runner-shell && pip install --no-cache-dir .
-
-# Copy claude-runner specific files
+# Copy claude-runner package (no separate runner-shell needed)
 COPY claude-code-runner /app/claude-runner
 
-# Install runner wrapper as a package (pulls dependencies like claude-agent-sdk)
-RUN pip install --no-cache-dir /app/claude-runner[observability] \
-    && pip install --no-cache-dir aiofiles
+# Install runner as a package (pulls dependencies including AG-UI SDK)
+RUN pip install --no-cache-dir /app/claude-runner
 
 # Set environment variables
 ENV PYTHONUNBUFFERED=1
@@ -33,6 +43,15 @@ ENV RUNNER_TYPE=claude
 ENV HOME=/app
 ENV SHELL=/bin/bash
 ENV TERM=xterm-256color
+ENV AGUI_PORT=8000
+
+# Build metadata as environment variables
+ENV GIT_COMMIT=${GIT_COMMIT}
+ENV GIT_BRANCH=${GIT_BRANCH}
+ENV GIT_REPO=${GIT_REPO}
+ENV GIT_VERSION=${GIT_VERSION}
+ENV BUILD_DATE=${BUILD_DATE}
+ENV BUILD_USER=${BUILD_USER}
 
 # Set umask to make files readable by other containers (fixes content service access)
 # 0022 creates files as rw-r--r-- (644) instead of default rw------- (600)
@@ -45,5 +64,9 @@ RUN chmod -R g=u /app && chmod -R g=u /usr/local && chmod g=u /etc/passwd
 # Run as UID 1001 to match content service (fixes permission issues)
 USER 1001
 
-# Default command - run via runner-shell
-CMD ["/bin/bash", "-c", "umask 0022 && python /app/claude-runner/wrapper.py"]
+# Expose AG-UI server port
+EXPOSE 8000
+
+# Start FastAPI AG-UI server using uvicorn
+# The main module is installed as part of the package
+CMD ["/bin/bash", "-c", "umask 0022 && cd /app/claude-runner && uvicorn main:app --host 0.0.0.0 --port 8000"]
diff --git a/components/runners/claude-code-runner/adapter.py b/components/runners/claude-code-runner/adapter.py
new file mode 100644
index 000000000..15800ba49
--- /dev/null
+++ b/components/runners/claude-code-runner/adapter.py
@@ -0,0 +1,1483 @@
+#!/usr/bin/env python3
+"""
+Claude Code Adapter for AG-UI Server.
+
+Refactored from wrapper.py to use async generators that yield AG-UI events
+instead of WebSocket messaging. This is the core adapter that wraps the
+Claude Code SDK and produces a stream of AG-UI protocol events.
+"""
+
+import asyncio
+import os
+import sys
+import logging
+import json as _json
+import re
+import shutil
+import uuid
+from pathlib import Path
+from typing import AsyncIterator, Optional, Any
+from urllib.parse import urlparse, urlunparse
+from urllib import request as _urllib_request, error as _urllib_error
+from datetime import datetime, timezone
+
+# Set umask to make files readable by content service container
+os.umask(0o022)
+
+# AG-UI Protocol Events
+from ag_ui.core import (
+    EventType,
+    RunAgentInput,
+    BaseEvent,
+    RunStartedEvent,
+    RunFinishedEvent,
+    RunErrorEvent,
+    TextMessageStartEvent,
+    TextMessageContentEvent,
+    TextMessageEndEvent,
+    ToolCallStartEvent,
+    ToolCallArgsEvent,
+    ToolCallEndEvent,
+    StepStartedEvent,
+    StepFinishedEvent,
+    StateSnapshotEvent,
+    StateDeltaEvent,
+    RawEvent,
+)
+
+from context import RunnerContext
+
+logger = logging.getLogger(__name__)
+
+
+class PrerequisiteError(RuntimeError):
+    """Raised when slash-command prerequisites are missing."""
+    pass
+
+
+class ClaudeCodeAdapter:
+    """
+    Adapter that wraps the Claude Code SDK for AG-UI server.
+    
+    Produces AG-UI events via async generator instead of WebSocket.
+    """
+
+    def __init__(self):
+        self.context: Optional[RunnerContext] = None
+        self.last_exit_code = 1
+        self._restart_requested = False
+        self._first_run = True
+        self._skip_resume_on_restart = False
+        self._turn_count = 0
+
+        # AG-UI streaming state
+        self._current_message_id: Optional[str] = None
+        self._current_tool_id: Optional[str] = None
+        self._current_run_id: Optional[str] = None
+        self._current_thread_id: Optional[str] = None
+        
+        # Active Claude SDK client for interrupt support
+        self._active_client: Optional[Any] = None
+        self._active_client_ctx: Optional[Any] = None
+
+    async def initialize(self, context: RunnerContext):
+        """Initialize the adapter with context."""
+        self.context = context
+        logger.info(f"Initialized Claude Code adapter for session {context.session_id}")
+
+        # Copy Google OAuth credentials from mounted Secret to writable workspace location
+        await self._setup_google_credentials()
+        
+        # Prepare workspace from input repo if provided
+        async for event in self._prepare_workspace():
+            yield event
+            
+        # Initialize workflow if ACTIVE_WORKFLOW env vars are set
+        async for event in self._initialize_workflow_if_set():
+            yield event
+            
+        # Validate prerequisite files exist for phase-based commands
+        try:
+            await self._validate_prerequisites()
+        except PrerequisiteError as exc:
+            self.last_exit_code = 2
+            logger.error("Prerequisite validation failed during initialization: %s", exc)
+            raise
+
+    def _timestamp(self) -> str:
+        """Return current UTC timestamp in ISO format."""
+        return datetime.now(timezone.utc).isoformat()
+
+    async def process_run(self, input_data: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        """
+        Process a run and yield AG-UI events.
+        
+        This is the main entry point called by the FastAPI server.
+        
+        Args:
+            input_data: RunAgentInput with thread_id, run_id, messages, tools
+            
+        Yields:
+            AG-UI events (RunStartedEvent, TextMessageContentEvent, etc.)
+        """
+        thread_id = input_data.thread_id or self.context.session_id
+        run_id = input_data.run_id or str(uuid.uuid4())
+        
+        self._current_thread_id = thread_id
+        self._current_run_id = run_id
+        
+        try:
+            # Emit RUN_STARTED
+            yield RunStartedEvent(
+                type=EventType.RUN_STARTED,
+                thread_id=thread_id,
+                run_id=run_id,
+            )
+            
+            # Echo user messages as events (for history/display)
+            for msg in input_data.messages or []:
+                msg_dict = msg if isinstance(msg, dict) else (msg.model_dump() if hasattr(msg, 'model_dump') else {})
+                role = msg_dict.get('role', '')
+                
+                if role == 'user':
+                    msg_id = msg_dict.get('id', str(uuid.uuid4()))
+                    content = msg_dict.get('content', '')
+                    msg_metadata = msg_dict.get('metadata', {})
+                    
+                    # Check if message should be hidden from UI
+                    is_hidden = isinstance(msg_metadata, dict) and msg_metadata.get('hidden', False)
+                    if is_hidden:
+                        logger.info(f"Message {msg_id[:8]} marked as hidden (auto-sent initial/workflow prompt)")
+                    
+                    # Emit user message as TEXT_MESSAGE events
+                    # Include metadata in RAW event for frontend filtering
+                    if is_hidden:
+                        yield RawEvent(
+                            type=EventType.RAW,
+                            thread_id=thread_id,
+                            run_id=run_id,
+                            event={
+                                "type": "message_metadata",
+                                "messageId": msg_id,
+                                "metadata": msg_metadata,
+                                "hidden": True,
+                            }
+                        )
+                    
+                    yield TextMessageStartEvent(
+                        type=EventType.TEXT_MESSAGE_START,
+                        thread_id=thread_id,
+                        run_id=run_id,
+                        message_id=msg_id,
+                        role='user',
+                    )
+                    
+                    if content:
+                        yield TextMessageContentEvent(
+                            type=EventType.TEXT_MESSAGE_CONTENT,
+                            thread_id=thread_id,
+                            run_id=run_id,
+                            message_id=msg_id,
+                            delta=content,
+                        )
+                    
+                    yield TextMessageEndEvent(
+                        type=EventType.TEXT_MESSAGE_END,
+                        thread_id=thread_id,
+                        run_id=run_id,
+                        message_id=msg_id,
+                    )
+            
+            # Extract user message from input
+            logger.info(f"Extracting user message from {len(input_data.messages)} messages")
+            user_message = self._extract_user_message(input_data)
+            logger.info(f"Extracted user message: '{user_message[:100] if user_message else '(empty)'}...'")
+            
+            if not user_message:
+                logger.warning("No user message found in input")
+                yield RawEvent(
+                    type=EventType.RAW,
+                    thread_id=thread_id,
+                    run_id=run_id,
+                    event={"type": "system_log", "message": "No user message provided"}
+                )
+                yield RunFinishedEvent(
+                    type=EventType.RUN_FINISHED,
+                    thread_id=thread_id,
+                    run_id=run_id,
+                )
+                return
+            
+            # Run Claude SDK and yield events
+            logger.info(f"Starting Claude SDK with prompt: '{user_message[:50]}...'")
+            async for event in self._run_claude_agent_sdk(user_message, thread_id, run_id):
+                yield event
+            logger.info(f"Claude SDK processing completed for run {run_id}")
+            
+            # Emit RUN_FINISHED
+            yield RunFinishedEvent(
+                type=EventType.RUN_FINISHED,
+                thread_id=thread_id,
+                run_id=run_id,
+            )
+            
+            self.last_exit_code = 0
+            
+        except PrerequisiteError as e:
+            self.last_exit_code = 2
+            logger.error(f"Prerequisite validation failed: {e}")
+            yield RunErrorEvent(
+                type=EventType.RUN_ERROR,
+                thread_id=thread_id,
+                run_id=run_id,
+                message=str(e),
+            )
+        except Exception as e:
+            self.last_exit_code = 1
+            logger.error(f"Error in process_run: {e}")
+            yield RunErrorEvent(
+                type=EventType.RUN_ERROR,
+                thread_id=thread_id,
+                run_id=run_id,
+                message=str(e),
+            )
+
+    def _extract_user_message(self, input_data: RunAgentInput) -> str:
+        """Extract user message text from RunAgentInput."""
+        messages = input_data.messages or []
+        logger.info(f"Extracting from {len(messages)} messages, types: {[type(m).__name__ for m in messages]}")
+        
+        # Find the last user message
+        for msg in reversed(messages):
+            logger.debug(f"Checking message: type={type(msg).__name__}, hasattr(role)={hasattr(msg, 'role')}")
+            
+            if hasattr(msg, 'role') and msg.role == 'user':
+                # Handle different content formats
+                content = getattr(msg, 'content', '')
+                if isinstance(content, str):
+                    logger.info(f"Found user message (object format): '{content[:50]}...'")
+                    return content
+                elif isinstance(content, list):
+                    # Content blocks format
+                    for block in content:
+                        if hasattr(block, 'text'):
+                            return block.text
+                        elif isinstance(block, dict) and 'text' in block:
+                            return block['text']
+            elif isinstance(msg, dict):
+                logger.debug(f"Dict message: role={msg.get('role')}, content={msg.get('content', '')[:30]}...")
+                if msg.get('role') == 'user':
+                    content = msg.get('content', '')
+                    if isinstance(content, str):
+                        logger.info(f"Found user message (dict format): '{content[:50]}...'")
+                        return content
+        
+        logger.warning("No user message found!")
+        return ""
+
+    async def _run_claude_agent_sdk(
+        self, prompt: str, thread_id: str, run_id: str
+    ) -> AsyncIterator[BaseEvent]:
+        """Execute the Claude Code SDK with the given prompt and yield AG-UI events."""
+        logger.info(f"_run_claude_agent_sdk called with prompt length={len(prompt)}")
+        try:
+            # Check for authentication method
+            logger.info("Checking authentication configuration...")
+            api_key = self.context.get_env('ANTHROPIC_API_KEY', '')
+            use_vertex = self.context.get_env('CLAUDE_CODE_USE_VERTEX', '').strip() == '1'
+            
+            logger.info(f"Auth config: api_key={'set' if api_key else 'not set'}, use_vertex={use_vertex}")
+
+            if not api_key and not use_vertex:
+                raise RuntimeError("Either ANTHROPIC_API_KEY or CLAUDE_CODE_USE_VERTEX=1 must be set")
+
+            # Set environment variables BEFORE importing SDK
+            if api_key:
+                os.environ['ANTHROPIC_API_KEY'] = api_key
+                logger.info("Using Anthropic API key authentication")
+
+            # Configure Vertex AI if requested
+            if use_vertex:
+                vertex_credentials = await self._setup_vertex_credentials()
+                if 'ANTHROPIC_API_KEY' in os.environ:
+                    logger.info("Clearing ANTHROPIC_API_KEY to force Vertex AI mode")
+                    del os.environ['ANTHROPIC_API_KEY']
+
+                os.environ['CLAUDE_CODE_USE_VERTEX'] = '1'
+                os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = vertex_credentials.get('credentials_path', '')
+                os.environ['ANTHROPIC_VERTEX_PROJECT_ID'] = vertex_credentials.get('project_id', '')
+                os.environ['CLOUD_ML_REGION'] = vertex_credentials.get('region', '')
+
+            # NOW we can safely import the SDK
+            from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
+            from claude_agent_sdk import (
+                AssistantMessage,
+                UserMessage,
+                SystemMessage,
+                ResultMessage,
+                TextBlock,
+                ThinkingBlock,
+                ToolUseBlock,
+                ToolResultBlock,
+            )
+            from claude_agent_sdk.types import StreamEvent
+
+            from observability import ObservabilityManager
+
+            # Extract and sanitize user context for observability
+            raw_user_id = os.getenv('USER_ID', '').strip()
+            raw_user_name = os.getenv('USER_NAME', '').strip()
+            user_id, user_name = self._sanitize_user_context(raw_user_id, raw_user_name)
+
+            # Get model configuration
+            model = self.context.get_env('LLM_MODEL')
+            configured_model = model or 'claude-sonnet-4-5@20250929'
+
+            if use_vertex and model:
+                configured_model = self._map_to_vertex_model(model)
+
+            # Initialize observability
+            obs = ObservabilityManager(
+                session_id=self.context.session_id,
+                user_id=user_id,
+                user_name=user_name
+            )
+            await obs.initialize(
+                prompt=prompt,
+                namespace=self.context.get_env('AGENTIC_SESSION_NAMESPACE', 'unknown'),
+                model=configured_model
+            )
+            obs._pending_initial_prompt = prompt
+
+            # Check if continuing from previous session
+            parent_session_id = self.context.get_env('PARENT_SESSION_ID', '').strip()
+            is_continuation = bool(parent_session_id)
+
+            # Determine cwd and additional dirs
+            repos_cfg = self._get_repos_config()
+            cwd_path = self.context.workspace_path
+            add_dirs = []
+            derived_name = None
+
+            # Check for active workflow first
+            active_workflow_url = (os.getenv('ACTIVE_WORKFLOW_GIT_URL') or '').strip()
+            if active_workflow_url:
+                cwd_path, add_dirs, derived_name = self._setup_workflow_paths(
+                    active_workflow_url, repos_cfg
+                )
+            elif repos_cfg:
+                cwd_path, add_dirs = self._setup_multi_repo_paths(repos_cfg)
+            else:
+                cwd_path = str(Path(self.context.workspace_path) / "artifacts")
+
+            # Load ambient.json configuration
+            ambient_config = self._load_ambient_config(cwd_path) if active_workflow_url else {}
+
+            # Ensure working directory exists
+            cwd_path_obj = Path(cwd_path)
+            if not cwd_path_obj.exists():
+                logger.warning(f"Working directory does not exist, creating: {cwd_path}")
+                try:
+                    cwd_path_obj.mkdir(parents=True, exist_ok=True)
+                except Exception as e:
+                    logger.error(f"Failed to create working directory: {e}")
+                    cwd_path = self.context.workspace_path
+
+            logger.info(f"Claude SDK CWD: {cwd_path}")
+            logger.info(f"Claude SDK additional directories: {add_dirs}")
+
+            # Load MCP server configuration
+            mcp_servers = self._load_mcp_config(cwd_path)
+            allowed_tools = ["Read", "Write", "Bash", "Glob", "Grep", "Edit", "MultiEdit", "WebSearch", "WebFetch"]
+            if mcp_servers:
+                for server_name in mcp_servers.keys():
+                    allowed_tools.append(f"mcp__{server_name}")
+                logger.info(f"MCP tool permissions granted for servers: {list(mcp_servers.keys())}")
+
+            # Build workspace context system prompt
+            workspace_prompt = self._build_workspace_context_prompt(
+                repos_cfg=repos_cfg,
+                workflow_name=derived_name if active_workflow_url else None,
+                artifacts_path="artifacts",
+                ambient_config=ambient_config
+            )
+            system_prompt_config = {"type": "text", "text": workspace_prompt}
+
+            # Configure SDK options
+            options = ClaudeAgentOptions(
+                cwd=cwd_path,
+                permission_mode="acceptEdits",
+                allowed_tools=allowed_tools,
+                mcp_servers=mcp_servers,
+                setting_sources=["project"],
+                system_prompt=system_prompt_config,
+                include_partial_messages=True,
+            )
+
+            # Enable continue_conversation for session resumption
+            if not self._first_run or is_continuation:
+                try:
+                    options.continue_conversation = True
+                    logger.info("Enabled continue_conversation for session resumption")
+                    yield RawEvent(
+                        type=EventType.RAW,
+                        thread_id=thread_id,
+                        run_id=run_id,
+                        event={"type": "system_log", "message": "🔄 Continuing conversation from previous state"}
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to set continue_conversation: {e}")
+
+            if self._skip_resume_on_restart:
+                self._skip_resume_on_restart = False
+
+            # Set additional options
+            try:
+                if add_dirs:
+                    options.add_dirs = add_dirs
+            except Exception:
+                pass
+
+            if model:
+                try:
+                    options.model = configured_model
+                except Exception:
+                    pass
+
+            max_tokens_env = self.context.get_env('LLM_MAX_TOKENS') or self.context.get_env('MAX_TOKENS')
+            if max_tokens_env:
+                try:
+                    options.max_tokens = int(max_tokens_env)
+                except Exception:
+                    pass
+
+            temperature_env = self.context.get_env('LLM_TEMPERATURE') or self.context.get_env('TEMPERATURE')
+            if temperature_env:
+                try:
+                    options.temperature = float(temperature_env)
+                except Exception:
+                    pass
+
+            result_payload = None
+            current_message = None
+            sdk_session_id = None
+
+            def create_sdk_client(opts, disable_continue=False):
+                if disable_continue and hasattr(opts, 'continue_conversation'):
+                    opts.continue_conversation = False
+                return ClaudeSDKClient(options=opts)
+
+            # Create SDK client with retry logic
+            try:
+                logger.info("Creating ClaudeSDKClient context manager...")
+                client_ctx = create_sdk_client(options)
+                logger.info("Entering ClaudeSDKClient context (initializing subprocess)...")
+                client = await client_ctx.__aenter__()
+                logger.info("ClaudeSDKClient initialized successfully!")
+            except Exception as resume_error:
+                error_str = str(resume_error).lower()
+                if "no conversation found" in error_str or "session" in error_str:
+                    logger.warning(f"Conversation continuation failed: {resume_error}")
+                    yield RawEvent(
+                        type=EventType.RAW,
+                        thread_id=thread_id,
+                        run_id=run_id,
+                        event={"type": "system_log", "message": "⚠️ Could not continue conversation, starting fresh..."}
+                    )
+                    client_ctx = create_sdk_client(options, disable_continue=True)
+                    client = await client_ctx.__aenter__()
+                else:
+                    raise
+
+            # Store active client for interrupt support
+            self._active_client = client
+            self._active_client_ctx = client_ctx
+
+            try:
+                if not self._first_run:
+                    yield RawEvent(
+                        type=EventType.RAW,
+                        thread_id=thread_id,
+                        run_id=run_id,
+                        event={"type": "system_log", "message": "✅ Continuing conversation"}
+                    )
+                    logger.info("SDK continuing conversation from local state")
+
+                # Process the prompt
+                step_id = str(uuid.uuid4())
+                yield StepStartedEvent(
+                    type=EventType.STEP_STARTED,
+                    thread_id=thread_id,
+                    run_id=run_id,
+                    step_id=step_id,
+                    step_name="processing_prompt",
+                )
+
+                logger.info(f"Sending query to Claude SDK: '{prompt[:100]}...'")
+                await client.query(prompt)
+                logger.info("Query sent, waiting for response stream...")
+
+                # Process response stream
+                async for message in client.receive_response():
+                    logger.info(f"[ClaudeSDKClient]: {message}")
+
+                    # Handle StreamEvent for real-time streaming chunks
+                    if isinstance(message, StreamEvent):
+                        event_data = message.event
+                        event_type = event_data.get('type')
+
+                        if event_type == 'message_start':
+                            self._current_message_id = str(uuid.uuid4())
+                            yield TextMessageStartEvent(
+                                type=EventType.TEXT_MESSAGE_START,
+                                thread_id=thread_id,
+                                run_id=run_id,
+                                message_id=self._current_message_id,
+                                role="assistant",
+                            )
+
+                        elif event_type == 'content_block_delta':
+                            delta_data = event_data.get('delta', {})
+                            if delta_data.get('type') == 'text_delta':
+                                text_chunk = delta_data.get('text', '')
+                                if text_chunk:
+                                    yield TextMessageContentEvent(
+                                        type=EventType.TEXT_MESSAGE_CONTENT,
+                                        thread_id=thread_id,
+                                        run_id=run_id,
+                                        message_id=self._current_message_id,
+                                        delta=text_chunk,
+                                    )
+                        continue
+
+                    # Capture SDK session ID from init message
+                    if isinstance(message, SystemMessage):
+                        if message.subtype == 'init' and message.data.get('session_id'):
+                            sdk_session_id = message.data.get('session_id')
+                            logger.info(f"Captured SDK session ID: {sdk_session_id}")
+
+                    if isinstance(message, (AssistantMessage, UserMessage)):
+                        if isinstance(message, AssistantMessage):
+                            current_message = message
+                            obs.start_turn(configured_model, user_input=prompt)
+
+                        # Process all blocks in the message
+                        for block in getattr(message, 'content', []) or []:
+                            if isinstance(block, TextBlock):
+                                text_piece = getattr(block, 'text', None)
+                                if text_piece:
+                                    logger.info(f"TextBlock received (complete), text length={len(text_piece)}")
+
+                            elif isinstance(block, ToolUseBlock):
+                                tool_name = getattr(block, 'name', '') or 'unknown'
+                                tool_input = getattr(block, 'input', {}) or {}
+                                tool_id = getattr(block, 'id', None) or str(uuid.uuid4())
+                                parent_tool_use_id = getattr(message, 'parent_tool_use_id', None)
+
+                                logger.info(f"ToolUseBlock detected: {tool_name} (id={tool_id[:12]})")
+
+                                yield ToolCallStartEvent(
+                                    type=EventType.TOOL_CALL_START,
+                                    thread_id=thread_id,
+                                    run_id=run_id,
+                                    tool_call_id=tool_id,
+                                    tool_call_name=tool_name,
+                                    parent_tool_call_id=parent_tool_use_id,
+                                )
+
+                                if tool_input:
+                                    args_json = _json.dumps(tool_input)
+                                    yield ToolCallArgsEvent(
+                                        type=EventType.TOOL_CALL_ARGS,
+                                        thread_id=thread_id,
+                                        run_id=run_id,
+                                        tool_call_id=tool_id,
+                                        delta=args_json,
+                                    )
+
+                                obs.track_tool_use(tool_name, tool_id, tool_input)
+
+                            elif isinstance(block, ToolResultBlock):
+                                tool_use_id = getattr(block, 'tool_use_id', None)
+                                content = getattr(block, 'content', None)
+                                is_error = getattr(block, 'is_error', None)
+                                result_text = getattr(block, 'text', None)
+                                result_content = content if content is not None else result_text
+
+                                if result_content is not None:
+                                    try:
+                                        result_str = _json.dumps(result_content)
+                                    except (TypeError, ValueError):
+                                        result_str = str(result_content)
+                                else:
+                                    result_str = ""
+
+                                if tool_use_id:
+                                    yield ToolCallEndEvent(
+                                        type=EventType.TOOL_CALL_END,
+                                        thread_id=thread_id,
+                                        run_id=run_id,
+                                        tool_call_id=tool_use_id,
+                                        result=result_str if not is_error else None,
+                                        error=result_str if is_error else None,
+                                    )
+
+                                obs.track_tool_result(tool_use_id, result_content, is_error or False)
+
+                            elif isinstance(block, ThinkingBlock):
+                                thinking_text = getattr(block, 'thinking', '')
+                                signature = getattr(block, 'signature', '')
+                                yield RawEvent(
+                                    type=EventType.RAW,
+                                    thread_id=thread_id,
+                                    run_id=run_id,
+                                    event={
+                                        "type": "thinking_block",
+                                        "thinking": thinking_text,
+                                        "signature": signature,
+                                    }
+                                )
+
+                        # End text message after processing all blocks
+                        if getattr(message, 'content', []) and self._current_message_id:
+                            yield TextMessageEndEvent(
+                                type=EventType.TEXT_MESSAGE_END,
+                                thread_id=thread_id,
+                                run_id=run_id,
+                                message_id=self._current_message_id,
+                            )
+                            self._current_message_id = None
+
+                    elif isinstance(message, SystemMessage):
+                        text = getattr(message, 'text', None)
+                        if text:
+                            yield RawEvent(
+                                type=EventType.RAW,
+                                thread_id=thread_id,
+                                run_id=run_id,
+                                event={"type": "system_log", "level": "debug", "message": str(text)}
+                            )
+
+                    elif isinstance(message, ResultMessage):
+                        usage_raw = getattr(message, 'usage', None)
+                        sdk_num_turns = getattr(message, 'num_turns', None)
+
+                        logger.info(f"ResultMessage: num_turns={sdk_num_turns}, usage={usage_raw}")
+
+                        # Convert usage object to dict if needed
+                        if usage_raw is not None and not isinstance(usage_raw, dict):
+                            try:
+                                if hasattr(usage_raw, '__dict__'):
+                                    usage_raw = usage_raw.__dict__
+                                elif hasattr(usage_raw, 'model_dump'):
+                                    usage_raw = usage_raw.model_dump()
+                            except Exception as e:
+                                logger.warning(f"Could not convert usage object to dict: {e}")
+
+                        # Update turn count
+                        if sdk_num_turns is not None and sdk_num_turns > self._turn_count:
+                            self._turn_count = sdk_num_turns
+
+                        # Complete turn tracking
+                        if current_message:
+                            obs.end_turn(self._turn_count, current_message, usage_raw if isinstance(usage_raw, dict) else None)
+                            current_message = None
+
+                        result_payload = {
+                            "subtype": getattr(message, 'subtype', None),
+                            "duration_ms": getattr(message, 'duration_ms', None),
+                            "is_error": getattr(message, 'is_error', None),
+                            "num_turns": getattr(message, 'num_turns', None),
+                            "total_cost_usd": getattr(message, 'total_cost_usd', None),
+                            "usage": usage_raw,
+                            "result": getattr(message, 'result', None),
+                        }
+
+                        # Emit state delta with result
+                        yield StateDeltaEvent(
+                            type=EventType.STATE_DELTA,
+                            thread_id=thread_id,
+                            run_id=run_id,
+                            delta=[{"op": "replace", "path": "/lastResult", "value": result_payload}],
+                        )
+
+                # End step
+                yield StepFinishedEvent(
+                    type=EventType.STEP_FINISHED,
+                    thread_id=thread_id,
+                    run_id=run_id,
+                    step_id=step_id,
+                    step_name="processing_prompt",
+                )
+
+                # Mark first run complete
+                self._first_run = False
+
+            finally:
+                await client_ctx.__aexit__(None, None, None)
+                # Clear active client reference
+                self._active_client = None
+                self._active_client_ctx = None
+
+            # Finalize observability
+            await obs.finalize()
+
+        except Exception as e:
+            logger.error(f"Failed to run Claude Code SDK: {e}")
+            # Clear active client on error
+            self._active_client = None
+            self._active_client_ctx = None
+            if 'obs' in locals():
+                await obs.cleanup_on_error(e)
+            raise
+    
+    async def interrupt(self) -> None:
+        """
+        Interrupt the active Claude SDK execution.
+        
+        Sends interrupt signal to stop Claude mid-execution.
+        See: https://platform.claude.com/docs/en/agent-sdk/python#methods
+        """
+        if not self._active_client:
+            logger.warning("Interrupt requested but no active client")
+            return
+        
+        try:
+            logger.info("Sending interrupt signal to Claude SDK client...")
+            await self._active_client.interrupt()
+            logger.info("Interrupt signal sent successfully")
+        except Exception as e:
+            logger.error(f"Failed to interrupt Claude SDK: {e}")
+
+    def _setup_workflow_paths(self, active_workflow_url: str, repos_cfg: list) -> tuple[str, list, str]:
+        """Setup paths for workflow mode."""
+        add_dirs = []
+        derived_name = None
+        cwd_path = self.context.workspace_path
+
+        try:
+            owner, repo, _ = self._parse_owner_repo(active_workflow_url)
+            derived_name = repo or ''
+            if not derived_name:
+                p = urlparse(active_workflow_url)
+                parts = [pt for pt in (p.path or '').split('/') if pt]
+                if parts:
+                    derived_name = parts[-1]
+            derived_name = (derived_name or '').removesuffix('.git').strip()
+
+            if derived_name:
+                workflow_path = str(Path(self.context.workspace_path) / "workflows" / derived_name)
+                if Path(workflow_path).exists():
+                    cwd_path = workflow_path
+                    logger.info(f"Using workflow as CWD: {derived_name}")
+                else:
+                    logger.warning(f"Workflow directory not found: {workflow_path}, using default")
+                    cwd_path = str(Path(self.context.workspace_path) / "workflows" / "default")
+            else:
+                cwd_path = str(Path(self.context.workspace_path) / "workflows" / "default")
+        except Exception as e:
+            logger.warning(f"Failed to derive workflow name: {e}, using default")
+            cwd_path = str(Path(self.context.workspace_path) / "workflows" / "default")
+
+        # Add all repos as additional directories
+        for r in repos_cfg:
+            name = (r.get('name') or '').strip()
+            if name:
+                repo_path = str(Path(self.context.workspace_path) / name)
+                if repo_path not in add_dirs:
+                    add_dirs.append(repo_path)
+
+        # Add artifacts and file-uploads directories
+        artifacts_path = str(Path(self.context.workspace_path) / "artifacts")
+        if artifacts_path not in add_dirs:
+            add_dirs.append(artifacts_path)
+
+        file_uploads_path = str(Path(self.context.workspace_path) / "file-uploads")
+        if file_uploads_path not in add_dirs:
+            add_dirs.append(file_uploads_path)
+
+        return cwd_path, add_dirs, derived_name
+
+    def _setup_multi_repo_paths(self, repos_cfg: list) -> tuple[str, list]:
+        """Setup paths for multi-repo mode."""
+        add_dirs = []
+        
+        main_name = (os.getenv('MAIN_REPO_NAME') or '').strip()
+        if not main_name:
+            idx_raw = (os.getenv('MAIN_REPO_INDEX') or '').strip()
+            try:
+                idx_val = int(idx_raw) if idx_raw else 0
+            except Exception:
+                idx_val = 0
+            if idx_val < 0 or idx_val >= len(repos_cfg):
+                idx_val = 0
+            main_name = (repos_cfg[idx_val].get('name') or '').strip()
+
+        cwd_path = str(Path(self.context.workspace_path) / main_name) if main_name else self.context.workspace_path
+
+        for r in repos_cfg:
+            name = (r.get('name') or '').strip()
+            if not name:
+                continue
+            p = str(Path(self.context.workspace_path) / name)
+            if p != cwd_path:
+                add_dirs.append(p)
+
+        # Add artifacts and file-uploads directories
+        artifacts_path = str(Path(self.context.workspace_path) / "artifacts")
+        if artifacts_path not in add_dirs:
+            add_dirs.append(artifacts_path)
+
+        file_uploads_path = str(Path(self.context.workspace_path) / "file-uploads")
+        if file_uploads_path not in add_dirs:
+            add_dirs.append(file_uploads_path)
+
+        return cwd_path, add_dirs
+
+    @staticmethod
+    def _sanitize_user_context(user_id: str, user_name: str) -> tuple[str, str]:
+        """Validate and sanitize user context fields to prevent injection attacks."""
+        if user_id:
+            user_id = str(user_id).strip()
+            if len(user_id) > 255:
+                user_id = user_id[:255]
+            sanitized_id = re.sub(r'[^a-zA-Z0-9@._-]', '', user_id)
+            user_id = sanitized_id
+
+        if user_name:
+            user_name = str(user_name).strip()
+            if len(user_name) > 255:
+                user_name = user_name[:255]
+            sanitized_name = re.sub(r'[\x00-\x1f\x7f-\x9f]', '', user_name)
+            user_name = sanitized_name
+
+        return user_id, user_name
+
+    def _map_to_vertex_model(self, model: str) -> str:
+        """Map Anthropic API model names to Vertex AI model names."""
+        model_map = {
+            'claude-opus-4-5': 'claude-opus-4-5@20251101',
+            'claude-opus-4-1': 'claude-opus-4-1@20250805',
+            'claude-sonnet-4-5': 'claude-sonnet-4-5@20250929',
+            'claude-haiku-4-5': 'claude-haiku-4-5@20251001',
+        }
+        return model_map.get(model, model)
+
+    async def _setup_vertex_credentials(self) -> dict:
+        """Set up Google Cloud Vertex AI credentials from service account."""
+        service_account_path = self.context.get_env('GOOGLE_APPLICATION_CREDENTIALS', '').strip()
+        project_id = self.context.get_env('ANTHROPIC_VERTEX_PROJECT_ID', '').strip()
+        region = self.context.get_env('CLOUD_ML_REGION', '').strip()
+
+        if not service_account_path:
+            raise RuntimeError("GOOGLE_APPLICATION_CREDENTIALS must be set when CLAUDE_CODE_USE_VERTEX=1")
+        if not project_id:
+            raise RuntimeError("ANTHROPIC_VERTEX_PROJECT_ID must be set when CLAUDE_CODE_USE_VERTEX=1")
+        if not region:
+            raise RuntimeError("CLOUD_ML_REGION must be set when CLAUDE_CODE_USE_VERTEX=1")
+
+        if not Path(service_account_path).exists():
+            raise RuntimeError(f"Service account key file not found at {service_account_path}")
+
+        logger.info(f"Vertex AI configured: project={project_id}, region={region}")
+        return {
+            'credentials_path': service_account_path,
+            'project_id': project_id,
+            'region': region,
+        }
+
+    async def _prepare_workspace(self) -> AsyncIterator[BaseEvent]:
+        """Clone input repo/branch into workspace and configure git remotes."""
+        workspace = Path(self.context.workspace_path)
+        workspace.mkdir(parents=True, exist_ok=True)
+
+        parent_session_id = self.context.get_env('PARENT_SESSION_ID', '').strip()
+        reusing_workspace = bool(parent_session_id)
+
+        logger.info(f"Workspace preparation: parent_session_id={parent_session_id[:8] if parent_session_id else 'None'}, reusing={reusing_workspace}")
+
+        repos_cfg = self._get_repos_config()
+        if repos_cfg:
+            async for event in self._prepare_multi_repo_workspace(workspace, repos_cfg, reusing_workspace):
+                yield event
+            return
+
+        # Single-repo legacy flow
+        input_repo = os.getenv("INPUT_REPO_URL", "").strip()
+        if not input_repo:
+            logger.info("No INPUT_REPO_URL configured, skipping single-repo setup")
+            return
+
+        input_branch = os.getenv("INPUT_BRANCH", "").strip() or "main"
+        output_repo = os.getenv("OUTPUT_REPO_URL", "").strip()
+
+        token = await self._fetch_token_for_url(input_repo)
+        workspace_has_git = (workspace / ".git").exists()
+
+        try:
+            if not workspace_has_git:
+                yield RawEvent(
+                    type=EventType.RAW,
+                    thread_id=self._current_thread_id or self.context.session_id,
+                    run_id=self._current_run_id or "init",
+                    event={"type": "system_log", "message": "📥 Cloning input repository..."}
+                )
+                clone_url = self._url_with_token(input_repo, token) if token else input_repo
+                await self._run_cmd(["git", "clone", "--branch", input_branch, "--single-branch", clone_url, str(workspace)], cwd=str(workspace.parent))
+                await self._run_cmd(["git", "remote", "set-url", "origin", clone_url], cwd=str(workspace), ignore_errors=True)
+            elif reusing_workspace:
+                yield RawEvent(
+                    type=EventType.RAW,
+                    thread_id=self._current_thread_id or self.context.session_id,
+                    run_id=self._current_run_id or "init",
+                    event={"type": "system_log", "message": "✓ Preserving workspace (continuation)"}
+                )
+                await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(input_repo, token) if token else input_repo], cwd=str(workspace), ignore_errors=True)
+            else:
+                yield RawEvent(
+                    type=EventType.RAW,
+                    thread_id=self._current_thread_id or self.context.session_id,
+                    run_id=self._current_run_id or "init",
+                    event={"type": "system_log", "message": "🔄 Resetting workspace to clean state"}
+                )
+                await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(input_repo, token) if token else input_repo], cwd=str(workspace))
+                await self._run_cmd(["git", "fetch", "origin", input_branch], cwd=str(workspace))
+                await self._run_cmd(["git", "checkout", input_branch], cwd=str(workspace))
+                await self._run_cmd(["git", "reset", "--hard", f"origin/{input_branch}"], cwd=str(workspace))
+
+            # Git identity
+            user_name = os.getenv("GIT_USER_NAME", "").strip() or "Ambient Code Bot"
+            user_email = os.getenv("GIT_USER_EMAIL", "").strip() or "bot@ambient-code.local"
+            await self._run_cmd(["git", "config", "user.name", user_name], cwd=str(workspace))
+            await self._run_cmd(["git", "config", "user.email", user_email], cwd=str(workspace))
+
+            if output_repo:
+                out_url = self._url_with_token(output_repo, token) if token else output_repo
+                await self._run_cmd(["git", "remote", "remove", "output"], cwd=str(workspace), ignore_errors=True)
+                await self._run_cmd(["git", "remote", "add", "output", out_url], cwd=str(workspace))
+
+        except Exception as e:
+            logger.error(f"Failed to prepare workspace: {e}")
+            yield RawEvent(
+                type=EventType.RAW,
+                thread_id=self._current_thread_id or self.context.session_id,
+                run_id=self._current_run_id or "init",
+                event={"type": "system_log", "message": f"Workspace preparation failed: {e}"}
+            )
+
+        # Create artifacts directory
+        try:
+            artifacts_dir = workspace / "artifacts"
+            artifacts_dir.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            logger.warning(f"Failed to create artifacts directory: {e}")
+
+    async def _prepare_multi_repo_workspace(
+        self, workspace: Path, repos_cfg: list, reusing_workspace: bool
+    ) -> AsyncIterator[BaseEvent]:
+        """Prepare workspace for multi-repo mode."""
+        try:
+            for r in repos_cfg:
+                name = (r.get('name') or '').strip()
+                inp = r.get('input') or {}
+                url = (inp.get('url') or '').strip()
+                branch = (inp.get('branch') or '').strip() or 'main'
+                if not name or not url:
+                    continue
+
+                repo_dir = workspace / name
+                token = await self._fetch_token_for_url(url)
+                repo_exists = repo_dir.exists() and (repo_dir / ".git").exists()
+
+                if not repo_exists:
+                    yield RawEvent(
+                        type=EventType.RAW,
+                        thread_id=self._current_thread_id or self.context.session_id,
+                        run_id=self._current_run_id or "init",
+                        event={"type": "system_log", "message": f"📥 Cloning {name}..."}
+                    )
+                    clone_url = self._url_with_token(url, token) if token else url
+                    await self._run_cmd(["git", "clone", "--branch", branch, "--single-branch", clone_url, str(repo_dir)], cwd=str(workspace))
+                    await self._run_cmd(["git", "remote", "set-url", "origin", clone_url], cwd=str(repo_dir), ignore_errors=True)
+                elif reusing_workspace:
+                    yield RawEvent(
+                        type=EventType.RAW,
+                        thread_id=self._current_thread_id or self.context.session_id,
+                        run_id=self._current_run_id or "init",
+                        event={"type": "system_log", "message": f"✓ Preserving {name} (continuation)"}
+                    )
+                    await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(url, token) if token else url], cwd=str(repo_dir), ignore_errors=True)
+                else:
+                    yield RawEvent(
+                        type=EventType.RAW,
+                        thread_id=self._current_thread_id or self.context.session_id,
+                        run_id=self._current_run_id or "init",
+                        event={"type": "system_log", "message": f"🔄 Resetting {name} to clean state"}
+                    )
+                    await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(url, token) if token else url], cwd=str(repo_dir), ignore_errors=True)
+                    await self._run_cmd(["git", "fetch", "origin", branch], cwd=str(repo_dir))
+                    await self._run_cmd(["git", "checkout", branch], cwd=str(repo_dir))
+                    await self._run_cmd(["git", "reset", "--hard", f"origin/{branch}"], cwd=str(repo_dir))
+
+                # Git identity
+                user_name = os.getenv("GIT_USER_NAME", "").strip() or "Ambient Code Bot"
+                user_email = os.getenv("GIT_USER_EMAIL", "").strip() or "bot@ambient-code.local"
+                await self._run_cmd(["git", "config", "user.name", user_name], cwd=str(repo_dir))
+                await self._run_cmd(["git", "config", "user.email", user_email], cwd=str(repo_dir))
+
+                # Configure output remote
+                out = r.get('output') or {}
+                out_url_raw = (out.get('url') or '').strip()
+                if out_url_raw:
+                    out_url = self._url_with_token(out_url_raw, token) if token else out_url_raw
+                    await self._run_cmd(["git", "remote", "remove", "output"], cwd=str(repo_dir), ignore_errors=True)
+                    await self._run_cmd(["git", "remote", "add", "output", out_url], cwd=str(repo_dir))
+
+        except Exception as e:
+            logger.error(f"Failed to prepare multi-repo workspace: {e}")
+            yield RawEvent(
+                type=EventType.RAW,
+                thread_id=self._current_thread_id or self.context.session_id,
+                run_id=self._current_run_id or "init",
+                event={"type": "system_log", "message": f"Workspace preparation failed: {e}"}
+            )
+
+    async def _validate_prerequisites(self):
+        """Validate prerequisite files exist for phase-based slash commands."""
+        prompt = self.context.get_env("INITIAL_PROMPT", "")
+        if not prompt:
+            return
+
+        prompt_lower = prompt.strip().lower()
+
+        prerequisites = {
+            "/speckit.plan": ("spec.md", "Specification file (spec.md) not found. Please run /speckit.specify first."),
+            "/speckit.tasks": ("plan.md", "Planning file (plan.md) not found. Please run /speckit.plan first."),
+            "/speckit.implement": ("tasks.md", "Tasks file (tasks.md) not found. Please run /speckit.tasks first.")
+        }
+
+        for cmd, (required_file, error_msg) in prerequisites.items():
+            if prompt_lower.startswith(cmd):
+                workspace = Path(self.context.workspace_path)
+                found = False
+
+                if (workspace / required_file).exists():
+                    found = True
+                    break
+
+                for subdir in workspace.rglob("specs/*/"):
+                    if (subdir / required_file).exists():
+                        found = True
+                        break
+
+                if not found:
+                    raise PrerequisiteError(error_msg)
+                break
+
+    async def _initialize_workflow_if_set(self) -> AsyncIterator[BaseEvent]:
+        """Initialize workflow on startup if ACTIVE_WORKFLOW env vars are set."""
+        active_workflow_url = (os.getenv('ACTIVE_WORKFLOW_GIT_URL') or '').strip()
+        if not active_workflow_url:
+            return
+
+        active_workflow_branch = (os.getenv('ACTIVE_WORKFLOW_BRANCH') or 'main').strip()
+        active_workflow_path = (os.getenv('ACTIVE_WORKFLOW_PATH') or '').strip()
+
+        try:
+            owner, repo, _ = self._parse_owner_repo(active_workflow_url)
+            derived_name = repo or ''
+            if not derived_name:
+                p = urlparse(active_workflow_url)
+                parts = [pt for pt in (p.path or '').split('/') if pt]
+                if parts:
+                    derived_name = parts[-1]
+            derived_name = (derived_name or '').removesuffix('.git').strip()
+
+            if not derived_name:
+                logger.warning("Could not derive workflow name from URL, skipping initialization")
+                return
+
+            workflow_dir = Path(self.context.workspace_path) / "workflows" / derived_name
+
+            if workflow_dir.exists():
+                logger.info(f"Workflow {derived_name} already exists, skipping initialization")
+                return
+
+            logger.info(f"Initializing workflow {derived_name} from CR spec on startup")
+            async for event in self._clone_workflow_repository(active_workflow_url, active_workflow_branch, active_workflow_path, derived_name):
+                yield event
+
+        except Exception as e:
+            logger.error(f"Failed to initialize workflow on startup: {e}")
+
+    async def _clone_workflow_repository(
+        self, git_url: str, branch: str, path: str, workflow_name: str
+    ) -> AsyncIterator[BaseEvent]:
+        """Clone workflow repository."""
+        workspace = Path(self.context.workspace_path)
+        workflow_dir = workspace / "workflows" / workflow_name
+        temp_clone_dir = workspace / "workflows" / f"{workflow_name}-clone-temp"
+
+        if workflow_dir.exists():
+            yield RawEvent(
+                type=EventType.RAW,
+                thread_id=self._current_thread_id or self.context.session_id,
+                run_id=self._current_run_id or "init",
+                event={"type": "system_log", "message": f"✓ Workflow {workflow_name} already loaded"}
+            )
+            return
+
+        token = await self._fetch_token_for_url(git_url)
+
+        yield RawEvent(
+            type=EventType.RAW,
+            thread_id=self._current_thread_id or self.context.session_id,
+            run_id=self._current_run_id or "init",
+            event={"type": "system_log", "message": f"📥 Cloning workflow {workflow_name}..."}
+        )
+
+        clone_url = self._url_with_token(git_url, token) if token else git_url
+        await self._run_cmd(["git", "clone", "--branch", branch, "--single-branch", clone_url, str(temp_clone_dir)], cwd=str(workspace))
+
+        if path and path.strip():
+            subdir_path = temp_clone_dir / path.strip()
+            if subdir_path.exists() and subdir_path.is_dir():
+                shutil.copytree(subdir_path, workflow_dir)
+                shutil.rmtree(temp_clone_dir)
+                yield RawEvent(
+                    type=EventType.RAW,
+                    thread_id=self._current_thread_id or self.context.session_id,
+                    run_id=self._current_run_id or "init",
+                    event={"type": "system_log", "message": f"✓ Extracted workflow from: {path}"}
+                )
+            else:
+                temp_clone_dir.rename(workflow_dir)
+                yield RawEvent(
+                    type=EventType.RAW,
+                    thread_id=self._current_thread_id or self.context.session_id,
+                    run_id=self._current_run_id or "init",
+                    event={"type": "system_log", "message": f"⚠️ Path '{path}' not found, using full repository"}
+                )
+        else:
+            temp_clone_dir.rename(workflow_dir)
+
+        yield RawEvent(
+            type=EventType.RAW,
+            thread_id=self._current_thread_id or self.context.session_id,
+            run_id=self._current_run_id or "init",
+            event={"type": "system_log", "message": f"✅ Workflow {workflow_name} ready"}
+        )
+
+    async def _run_cmd(self, cmd, cwd=None, capture_stdout=False, ignore_errors=False):
+        """Run a subprocess command asynchronously."""
+        cmd_safe = [self._redact_secrets(str(arg)) for arg in cmd]
+        logger.info(f"Running command: {' '.join(cmd_safe)}")
+
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd or self.context.workspace_path,
+        )
+        stdout_data, stderr_data = await proc.communicate()
+        stdout_text = stdout_data.decode("utf-8", errors="replace")
+        stderr_text = stderr_data.decode("utf-8", errors="replace")
+
+        if stdout_text.strip():
+            logger.info(f"Command stdout: {self._redact_secrets(stdout_text.strip())}")
+        if stderr_text.strip():
+            logger.info(f"Command stderr: {self._redact_secrets(stderr_text.strip())}")
+
+        if proc.returncode != 0 and not ignore_errors:
+            raise RuntimeError(stderr_text or f"Command failed: {' '.join(cmd_safe)}")
+
+        if capture_stdout:
+            return stdout_text
+        return ""
+
+    def _url_with_token(self, url: str, token: str) -> str:
+        """Add authentication token to URL."""
+        if not token or not url.lower().startswith("http"):
+            return url
+        try:
+            parsed = urlparse(url)
+            netloc = parsed.netloc
+            if "@" in netloc:
+                netloc = netloc.split("@", 1)[1]
+
+            hostname = parsed.hostname or ""
+            if 'gitlab' in hostname.lower():
+                auth = f"oauth2:{token}@"
+            else:
+                auth = f"x-access-token:{token}@"
+
+            new_netloc = auth + netloc
+            return urlunparse((parsed.scheme, new_netloc, parsed.path,
+                               parsed.params, parsed.query, parsed.fragment))
+        except Exception:
+            return url
+
+    def _redact_secrets(self, text: str) -> str:
+        """Redact tokens and secrets from text for safe logging."""
+        if not text:
+            return text
+
+        text = re.sub(r'gh[pousr]_[a-zA-Z0-9]{36,255}', 'gh*_***REDACTED***', text)
+        text = re.sub(r'sk-ant-[a-zA-Z0-9\-_]{30,200}', 'sk-ant-***REDACTED***', text)
+        text = re.sub(r'pk-lf-[a-zA-Z0-9\-_]{10,100}', 'pk-lf-***REDACTED***', text)
+        text = re.sub(r'sk-lf-[a-zA-Z0-9\-_]{10,100}', 'sk-lf-***REDACTED***', text)
+        text = re.sub(r'x-access-token:[^@\s]+@', 'x-access-token:***REDACTED***@', text)
+        text = re.sub(r'oauth2:[^@\s]+@', 'oauth2:***REDACTED***@', text)
+        text = re.sub(r'://[^:@\s]+:[^@\s]+@', '://***REDACTED***@', text)
+        text = re.sub(
+            r'(ANTHROPIC_API_KEY|LANGFUSE_SECRET_KEY|LANGFUSE_PUBLIC_KEY|BOT_TOKEN|GIT_TOKEN)\s*=\s*[^\s\'"]+',
+            r'\1=***REDACTED***',
+            text
+        )
+        return text
+
+    async def _fetch_token_for_url(self, url: str) -> str:
+        """Fetch appropriate token based on repository URL."""
+        try:
+            parsed = urlparse(url)
+            hostname = parsed.hostname or ""
+
+            if 'gitlab' in hostname.lower():
+                token = os.getenv("GITLAB_TOKEN", "").strip()
+                if token:
+                    logger.info(f"Using GITLAB_TOKEN for {hostname}")
+                    return token
+                else:
+                    logger.warning(f"No GITLAB_TOKEN found for GitLab URL: {url}")
+                    return ""
+
+            token = os.getenv("GITHUB_TOKEN") or await self._fetch_github_token()
+            if token:
+                logger.info(f"Using GitHub token for {hostname}")
+            return token
+
+        except Exception as e:
+            logger.warning(f"Failed to parse URL {url}: {e}, falling back to GitHub token")
+            return os.getenv("GITHUB_TOKEN") or await self._fetch_github_token()
+
+    async def _fetch_github_token(self) -> str:
+        """Fetch GitHub token from backend API or environment."""
+        cached = os.getenv("GITHUB_TOKEN", "").strip()
+        if cached:
+            logger.info("Using GITHUB_TOKEN from environment")
+            return cached
+
+        # Build mint URL from environment
+        base = os.getenv('BACKEND_API_URL', '').rstrip('/')
+        project = os.getenv('PROJECT_NAME', '').strip()
+        session_id = self.context.session_id
+
+        if not base or not project or not session_id:
+            logger.warning("Cannot fetch GitHub token: missing environment variables")
+            return ""
+
+        url = f"{base}/projects/{project}/agentic-sessions/{session_id}/github/token"
+        logger.info(f"Fetching GitHub token from: {url}")
+
+        req = _urllib_request.Request(url, data=b"{}", headers={'Content-Type': 'application/json'}, method='POST')
+        bot = (os.getenv('BOT_TOKEN') or '').strip()
+        if bot:
+            req.add_header('Authorization', f'Bearer {bot}')
+
+        loop = asyncio.get_event_loop()
+
+        def _do_req():
+            try:
+                with _urllib_request.urlopen(req, timeout=10) as resp:
+                    return resp.read().decode('utf-8', errors='replace')
+            except Exception as e:
+                logger.warning(f"GitHub token fetch failed: {e}")
+                return ''
+
+        resp_text = await loop.run_in_executor(None, _do_req)
+        if not resp_text:
+            return ""
+
+        try:
+            data = _json.loads(resp_text)
+            token = str(data.get('token') or '')
+            if token:
+                logger.info("Successfully fetched GitHub token from backend")
+            return token
+        except Exception as e:
+            logger.error(f"Failed to parse token response: {e}")
+            return ""
+
+    def _parse_owner_repo(self, url: str) -> tuple[str, str, str]:
+        """Return (owner, name, host) from various URL formats."""
+        s = (url or "").strip()
+        s = s.removesuffix(".git")
+        host = "github.com"
+        try:
+            if s.startswith("http://") or s.startswith("https://"):
+                p = urlparse(s)
+                host = p.netloc
+                parts = [pt for pt in p.path.split("/") if pt]
+                if len(parts) >= 2:
+                    return parts[0], parts[1], host
+            if s.startswith("git@") or ":" in s:
+                s2 = s
+                if s2.startswith("git@"):
+                    s2 = s2.replace(":", "/", 1)
+                    s2 = s2.replace("git@", "ssh://git@", 1)
+                p = urlparse(s2)
+                host = p.hostname or host
+                parts = [pt for pt in (p.path or "").split("/") if pt]
+                if len(parts) >= 2:
+                    return parts[-2], parts[-1], host
+            parts = [pt for pt in s.split("/") if pt]
+            if len(parts) == 2:
+                return parts[0], parts[1], host
+        except Exception:
+            return "", "", host
+        return "", "", host
+
+    def _get_repos_config(self) -> list[dict]:
+        """Read repos mapping from REPOS_JSON env if present."""
+        try:
+            raw = os.getenv('REPOS_JSON', '').strip()
+            if not raw:
+                return []
+            data = _json.loads(raw)
+            if isinstance(data, list):
+                out = []
+                for it in data:
+                    if not isinstance(it, dict):
+                        continue
+                    name = str(it.get('name') or '').strip()
+                    input_obj = it.get('input') or {}
+                    output_obj = it.get('output') or None
+                    url = str((input_obj or {}).get('url') or '').strip()
+                    if not name and url:
+                        try:
+                            owner, repo, _ = self._parse_owner_repo(url)
+                            derived = repo or ''
+                            if not derived:
+                                p = urlparse(url)
+                                parts = [pt for pt in (p.path or '').split('/') if pt]
+                                if parts:
+                                    derived = parts[-1]
+                            name = (derived or '').removesuffix('.git').strip()
+                        except Exception:
+                            name = ''
+                    if name and isinstance(input_obj, dict) and url:
+                        out.append({'name': name, 'input': input_obj, 'output': output_obj})
+                return out
+        except Exception:
+            return []
+        return []
+
+    def _load_mcp_config(self, cwd_path: str) -> Optional[dict]:
+        """Load MCP server configuration from the ambient runner's .mcp.json file."""
+        try:
+            runner_mcp_file = Path("/app/claude-runner/.mcp.json")
+
+            if runner_mcp_file.exists() and runner_mcp_file.is_file():
+                logger.info(f"Loading MCP config from runner directory: {runner_mcp_file}")
+                with open(runner_mcp_file, 'r') as f:
+                    config = _json.load(f)
+                    return config.get('mcpServers', {})
+            else:
+                logger.info("No .mcp.json file found in runner directory")
+                return None
+
+        except _json.JSONDecodeError as e:
+            logger.error(f"Failed to parse .mcp.json: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Error loading MCP config: {e}")
+            return None
+
+    def _load_ambient_config(self, cwd_path: str) -> dict:
+        """Load ambient.json configuration from workflow directory."""
+        try:
+            config_path = Path(cwd_path) / ".ambient" / "ambient.json"
+
+            if not config_path.exists():
+                logger.info(f"No ambient.json found at {config_path}, using defaults")
+                return {}
+
+            with open(config_path, 'r') as f:
+                config = _json.load(f)
+                logger.info(f"Loaded ambient.json: name={config.get('name')}")
+                return config
+
+        except _json.JSONDecodeError as e:
+            logger.error(f"Failed to parse ambient.json: {e}")
+            return {}
+        except Exception as e:
+            logger.error(f"Error loading ambient.json: {e}")
+            return {}
+
+    def _build_workspace_context_prompt(self, repos_cfg, workflow_name, artifacts_path, ambient_config):
+        """Generate comprehensive system prompt describing workspace layout."""
+        prompt = "You are Claude Code working in a structured development workspace.\n\n"
+
+        if workflow_name:
+            prompt += "## Current Workflow\n"
+            prompt += f"Working directory: workflows/{workflow_name}/\n"
+            prompt += "This directory contains workflow logic and automation scripts.\n\n"
+
+        prompt += "## User-Uploaded Files (IMPORTANT)\n"
+        prompt += "Location: file-uploads/\n"
+        prompt += "Purpose: User-uploaded context files (screenshots, documents, images, PDFs, specs, designs).\n"
+        prompt += "ALWAYS check this directory when starting a new task - it often contains critical context.\n\n"
+
+        file_uploads_path = Path(self.context.workspace_path) / "file-uploads"
+        if file_uploads_path.exists() and file_uploads_path.is_dir():
+            try:
+                files = sorted([f.name for f in file_uploads_path.iterdir() if f.is_file()])
+                if files:
+                    prompt += f"Currently uploaded files ({len(files)}):\n"
+                    for filename in files:
+                        prompt += f"  - {filename}\n"
+                    prompt += "READ THESE FILES if they're relevant to the user's task!\n"
+            except Exception:
+                pass
+
+        prompt += "\n## Shared Artifacts Directory\n"
+        prompt += f"Location: {artifacts_path}\n"
+        prompt += "Purpose: Create all output artifacts (documents, specs, reports) here.\n\n"
+
+        if repos_cfg:
+            prompt += "## Available Code Repositories\n"
+            for i, repo in enumerate(repos_cfg):
+                name = repo.get('name', f'repo-{i}')
+                prompt += f"- {name}/\n"
+            prompt += "\nThese repositories contain source code you can read or modify.\n\n"
+
+        if ambient_config.get("systemPrompt"):
+            prompt += f"## Workflow Instructions\n{ambient_config['systemPrompt']}\n\n"
+
+        prompt += "## Navigation\n"
+        prompt += "All directories are accessible via relative or absolute paths.\n"
+
+        return prompt
+
+
+    async def _setup_google_credentials(self):
+        """Copy Google OAuth credentials from mounted Secret to writable workspace location."""
+        # Check if Google OAuth secret is mounted
+        secret_path = Path("/app/.google_workspace_mcp/credentials/credentials.json")
+        if not secret_path.exists():
+            logging.debug("Google OAuth credentials not found at %s, skipping setup", secret_path)
+            return
+
+        # Create writable credentials directory in workspace
+        workspace_creds_dir = Path("/workspace/.google_workspace_mcp/credentials")
+        workspace_creds_dir.mkdir(parents=True, exist_ok=True)
+
+        # Copy credentials from read-only Secret mount to writable workspace
+        dest_path = workspace_creds_dir / "credentials.json"
+        try:
+            shutil.copy2(secret_path, dest_path)
+            # Make it writable so workspace-mcp can update tokens
+            dest_path.chmod(0o644)
+            logging.info("✓ Copied Google OAuth credentials from Secret to writable workspace at %s", dest_path)
+        except Exception as e:
+            logging.error("Failed to copy Google OAuth credentials: %s", e)
\ No newline at end of file
diff --git a/components/runners/runner-shell/runner_shell/core/context.py b/components/runners/claude-code-runner/context.py
similarity index 95%
rename from components/runners/runner-shell/runner_shell/core/context.py
rename to components/runners/claude-code-runner/context.py
index 816dd4bff..4e95abf37 100644
--- a/components/runners/runner-shell/runner_shell/core/context.py
+++ b/components/runners/claude-code-runner/context.py
@@ -35,4 +35,5 @@ def set_metadata(self, key: str, value: Any):
 
     def get_metadata(self, key: str, default: Any = None) -> Any:
         """Get metadata value."""
-        return self.metadata.get(key, default)
\ No newline at end of file
+        return self.metadata.get(key, default)
+
diff --git a/components/runners/claude-code-runner/main.py b/components/runners/claude-code-runner/main.py
new file mode 100644
index 000000000..631c303a4
--- /dev/null
+++ b/components/runners/claude-code-runner/main.py
@@ -0,0 +1,475 @@
+"""
+AG-UI Server entry point for Claude Code runner.
+Implements the official AG-UI server pattern.
+"""
+import asyncio
+import os
+import json
+import logging
+from contextlib import asynccontextmanager
+from typing import Optional, List, Dict, Any, Union
+
+from fastapi import FastAPI, Request, HTTPException
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+import uvicorn
+
+from ag_ui.core import RunAgentInput
+from ag_ui.encoder import EventEncoder
+
+from context import RunnerContext
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# Flexible input model that matches what our frontend actually sends
+class RunnerInput(BaseModel):
+    """Input model for runner with optional AG-UI fields."""
+    threadId: Optional[str] = None
+    thread_id: Optional[str] = None  # Support both camelCase and snake_case
+    runId: Optional[str] = None
+    run_id: Optional[str] = None
+    parentRunId: Optional[str] = None
+    parent_run_id: Optional[str] = None
+    messages: List[Dict[str, Any]]
+    state: Optional[Dict[str, Any]] = None
+    tools: Optional[List[Any]] = None
+    context: Optional[Union[List[Any], Dict[str, Any]]] = None  # Accept both list and dict, convert to list
+    forwardedProps: Optional[Dict[str, Any]] = None
+    environment: Optional[Dict[str, str]] = None
+    metadata: Optional[Dict[str, Any]] = None
+    
+    def to_run_agent_input(self) -> RunAgentInput:
+        """Convert to official RunAgentInput model."""
+        import uuid
+        
+        # Normalize field names (prefer camelCase for AG-UI)
+        thread_id = self.threadId or self.thread_id
+        run_id = self.runId or self.run_id
+        parent_run_id = self.parentRunId or self.parent_run_id
+        
+        # Generate runId if not provided
+        if not run_id:
+            run_id = str(uuid.uuid4())
+            logger.info(f"Generated run_id: {run_id}")
+        
+        # Context should be a list, not a dict
+        context_list = self.context if isinstance(self.context, list) else []
+        
+        return RunAgentInput(
+            thread_id=thread_id,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            messages=self.messages,
+            state=self.state or {},
+            tools=self.tools or [],
+            context=context_list,
+            forwarded_props=self.forwardedProps or {},
+        )
+
+# Global context and adapter
+context: Optional[RunnerContext] = None
+adapter = None  # Will be ClaudeCodeAdapter after initialization
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize and cleanup application resources."""
+    global context, adapter
+    
+    # Import adapter here to avoid circular imports
+    from adapter import ClaudeCodeAdapter
+    
+    # Initialize context from environment
+    session_id = os.getenv("SESSION_ID", "unknown")
+    workspace_path = os.getenv("WORKSPACE_PATH", "/workspace")
+    
+    logger.info(f"Initializing AG-UI server for session {session_id}")
+    
+    context = RunnerContext(
+        session_id=session_id,
+        workspace_path=workspace_path,
+    )
+    
+    adapter = ClaudeCodeAdapter()
+    adapter.context = context
+    
+    # Check for INITIAL_PROMPT and auto-execute on startup
+    # Runner knows when it's ready, so this is more reliable than backend timing
+    initial_prompt = os.getenv("INITIAL_PROMPT", "").strip()
+    if initial_prompt:
+        logger.info(f"INITIAL_PROMPT detected ({len(initial_prompt)} chars), will auto-execute after server starts")
+        # Schedule auto-execution after server is ready
+        import asyncio
+        asyncio.create_task(auto_execute_initial_prompt(initial_prompt, session_id))
+    
+    logger.info(f"AG-UI server ready for session {session_id}")
+    
+    yield
+    
+    # Cleanup
+    logger.info("Shutting down AG-UI server")
+
+
+async def auto_execute_initial_prompt(prompt: str, session_id: str):
+    """Auto-execute INITIAL_PROMPT by POSTing to backend after server is ready."""
+    import uuid
+    import aiohttp
+    
+    # Wait for FastAPI server to be fully ready
+    await asyncio.sleep(2)
+    
+    logger.info(f"Auto-executing INITIAL_PROMPT via backend POST...")
+    
+    try:
+        # Get backend URL from environment
+        backend_url = os.getenv("BACKEND_API_URL", "").rstrip("/")
+        project_name = os.getenv("PROJECT_NAME", "").strip() or os.getenv("AGENTIC_SESSION_NAMESPACE", "").strip()
+        
+        if not backend_url or not project_name:
+            logger.error("Cannot auto-execute INITIAL_PROMPT: BACKEND_API_URL or PROJECT_NAME not set")
+            return
+        
+        url = f"{backend_url}/projects/{project_name}/agentic-sessions/{session_id}/agui/run"
+        
+        payload = {
+            "threadId": session_id,
+            "runId": str(uuid.uuid4()),
+            "messages": [{
+                "id": str(uuid.uuid4()),
+                "role": "user",
+                "content": prompt,
+                "metadata": {
+                    "hidden": True,
+                    "autoSent": True,
+                    "source": "runner_auto_execute"
+                }
+            }]
+        }
+        
+        # Get BOT_TOKEN for auth
+        bot_token = os.getenv("BOT_TOKEN", "").strip()
+        headers = {"Content-Type": "application/json"}
+        if bot_token:
+            headers["Authorization"] = f"Bearer {bot_token}"
+        
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, json=payload, headers=headers) as resp:
+                if resp.status == 200:
+                    result = await resp.json()
+                    logger.info(f"INITIAL_PROMPT auto-execution started: {result}")
+                else:
+                    error_text = await resp.text()
+                    logger.error(f"INITIAL_PROMPT auto-execution failed: {resp.status} - {error_text}")
+    
+    except Exception as e:
+        logger.error(f"Failed to auto-execute INITIAL_PROMPT: {e}")
+
+
+app = FastAPI(
+    title="Claude Code AG-UI Server",
+    version="0.2.0",
+    lifespan=lifespan
+)
+
+
+# Track if adapter has been initialized
+_adapter_initialized = False
+
+
+@app.post("/")
+async def run_agent(input_data: RunnerInput, request: Request):
+    """
+    AG-UI compatible run endpoint.
+    
+    Accepts flexible input with thread_id, run_id, messages.
+    Optional fields: state, tools, context, forwardedProps.
+    Returns SSE stream of AG-UI events.
+    """
+    global _adapter_initialized
+    
+    if not adapter:
+        raise HTTPException(status_code=503, detail="Adapter not initialized")
+    
+    # Convert to official RunAgentInput
+    run_agent_input = input_data.to_run_agent_input()
+    
+    # Get Accept header for encoder
+    accept_header = request.headers.get("accept", "text/event-stream")
+    encoder = EventEncoder(accept=accept_header)
+    
+    logger.info(f"Processing run: thread_id={run_agent_input.thread_id}, run_id={run_agent_input.run_id}")
+    
+    async def event_generator():
+        """Generate AG-UI events from adapter."""
+        global _adapter_initialized
+        
+        try:
+            logger.info("Event generator started")
+            
+            # Initialize adapter on first run (yields setup events)
+            if not _adapter_initialized:
+                logger.info("First run - initializing adapter with workspace preparation")
+                async for event in adapter.initialize(context):
+                    logger.debug(f"Yielding initialization event: {event.type}")
+                    yield encoder.encode(event)
+                logger.info("Adapter initialization complete")
+                _adapter_initialized = True
+            
+            logger.info("Starting adapter.process_run()...")
+            # Process the actual run
+            async for event in adapter.process_run(run_agent_input):
+                logger.debug(f"Yielding run event: {event.type}")
+                yield encoder.encode(event)
+            logger.info("adapter.process_run() completed")
+        except Exception as e:
+            logger.error(f"Error in event generator: {e}")
+            # Yield error event
+            from ag_ui.core import RunErrorEvent, EventType
+            error_event = RunErrorEvent(
+                type=EventType.RUN_ERROR,
+                thread_id=run_agent_input.thread_id or context.session_id,
+                run_id=run_agent_input.run_id or "unknown",
+                message=str(e)
+            )
+            yield encoder.encode(error_event)
+    
+    return StreamingResponse(
+        event_generator(),
+        media_type=encoder.get_content_type(),
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        }
+    )
+
+
+@app.post("/interrupt")
+async def interrupt_run():
+    """
+    Interrupt the current Claude SDK execution.
+    
+    Sends interrupt signal to Claude subprocess to stop mid-execution.
+    See: https://platform.claude.com/docs/en/agent-sdk/python#methods
+    """
+    if not adapter:
+        raise HTTPException(status_code=503, detail="Adapter not initialized")
+    
+    logger.info("Interrupt request received")
+    
+    try:
+        # Call adapter's interrupt method which signals the active Claude SDK client
+        await adapter.interrupt()
+        
+        return {"message": "Interrupt signal sent to Claude SDK"}
+    except Exception as e:
+        logger.error(f"Interrupt failed: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/workflow")
+async def change_workflow(request: Request):
+    """
+    Change active workflow - triggers Claude SDK client restart and new greeting.
+    
+    Accepts: {"gitUrl": "...", "branch": "...", "path": "..."}
+    """
+    global _adapter_initialized
+    
+    if not adapter:
+        raise HTTPException(status_code=503, detail="Adapter not initialized")
+    
+    body = await request.json()
+    git_url = body.get("gitUrl", "")
+    branch = body.get("branch", "main")
+    path = body.get("path", "")
+    
+    logger.info(f"Workflow change request: {git_url}@{branch} (path: {path})")
+    
+    # Update environment variables
+    os.environ["ACTIVE_WORKFLOW_GIT_URL"] = git_url
+    os.environ["ACTIVE_WORKFLOW_BRANCH"] = branch
+    os.environ["ACTIVE_WORKFLOW_PATH"] = path
+    
+    # Reset adapter state to force reinitialization on next run
+    _adapter_initialized = False
+    adapter._first_run = True
+    
+    logger.info("Workflow updated, triggering new run with workflow greeting")
+    
+    # Trigger a new run to greet user with workflow context
+    # This runs in background via backend POST
+    import asyncio
+    asyncio.create_task(trigger_workflow_greeting(git_url, branch, path))
+    
+    return {"message": "Workflow updated", "gitUrl": git_url, "branch": branch, "path": path}
+
+
+async def trigger_workflow_greeting(git_url: str, branch: str, path: str):
+    """Trigger workflow greeting after workflow change."""
+    import uuid
+    import aiohttp
+    
+    # Wait a moment for workflow to be cloned/initialized
+    await asyncio.sleep(3)
+    
+    logger.info("Triggering workflow greeting...")
+    
+    try:
+        backend_url = os.getenv("BACKEND_API_URL", "").rstrip("/")
+        project_name = os.getenv("AGENTIC_SESSION_NAMESPACE", "").strip()
+        session_id = context.session_id if context else "unknown"
+        
+        if not backend_url or not project_name:
+            logger.error("Cannot trigger workflow greeting: BACKEND_API_URL or PROJECT_NAME not set")
+            return
+        
+        url = f"{backend_url}/projects/{project_name}/agentic-sessions/{session_id}/agui/run"
+        
+        # Extract workflow name for greeting
+        workflow_name = git_url.split("/")[-1].removesuffix(".git")
+        if path:
+            workflow_name = path.split("/")[-1]
+        
+        greeting = f"Greet the user and explain that the {workflow_name} workflow is now active. Briefly describe what this workflow helps with based on the systemPrompt in ambient.json. Keep it concise and friendly."
+        
+        payload = {
+            "threadId": session_id,
+            "runId": str(uuid.uuid4()),
+            "messages": [{
+                "id": str(uuid.uuid4()),
+                "role": "user",
+                "content": greeting,
+                "metadata": {
+                    "hidden": True,
+                    "autoSent": True,
+                    "source": "workflow_activation"
+                }
+            }]
+        }
+        
+        bot_token = os.getenv("BOT_TOKEN", "").strip()
+        headers = {"Content-Type": "application/json"}
+        if bot_token:
+            headers["Authorization"] = f"Bearer {bot_token}"
+        
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, json=payload, headers=headers) as resp:
+                if resp.status == 200:
+                    result = await resp.json()
+                    logger.info(f"Workflow greeting started: {result}")
+                else:
+                    error_text = await resp.text()
+                    logger.error(f"Workflow greeting failed: {resp.status} - {error_text}")
+    
+    except Exception as e:
+        logger.error(f"Failed to trigger workflow greeting: {e}")
+
+
+@app.post("/repos/add")
+async def add_repo(request: Request):
+    """
+    Add repository - triggers Claude SDK client restart.
+    
+    Accepts: {"url": "...", "branch": "...", "name": "..."}
+    """
+    global _adapter_initialized
+    
+    if not adapter:
+        raise HTTPException(status_code=503, detail="Adapter not initialized")
+    
+    body = await request.json()
+    logger.info(f"Add repo request: {body}")
+    
+    # Update REPOS_JSON env var
+    repos_json = os.getenv("REPOS_JSON", "[]")
+    try:
+        repos = json.loads(repos_json) if repos_json else []
+    except:
+        repos = []
+    
+    # Add new repo
+    repos.append({
+        "name": body.get("name", ""),
+        "input": {
+            "url": body.get("url", ""),
+            "branch": body.get("branch", "main")
+        }
+    })
+    
+    os.environ["REPOS_JSON"] = json.dumps(repos)
+    
+    # Reset adapter state
+    _adapter_initialized = False
+    adapter._first_run = True
+    
+    logger.info(f"Repo added, adapter will reinitialize on next run")
+    
+    return {"message": "Repository added"}
+
+
+@app.post("/repos/remove")
+async def remove_repo(request: Request):
+    """
+    Remove repository - triggers Claude SDK client restart.
+    
+    Accepts: {"name": "..."}
+    """
+    global _adapter_initialized
+    
+    if not adapter:
+        raise HTTPException(status_code=503, detail="Adapter not initialized")
+    
+    body = await request.json()
+    repo_name = body.get("name", "")
+    logger.info(f"Remove repo request: {repo_name}")
+    
+    # Update REPOS_JSON env var
+    repos_json = os.getenv("REPOS_JSON", "[]")
+    try:
+        repos = json.loads(repos_json) if repos_json else []
+    except:
+        repos = []
+    
+    # Remove repo by name
+    repos = [r for r in repos if r.get("name") != repo_name]
+    
+    os.environ["REPOS_JSON"] = json.dumps(repos)
+    
+    # Reset adapter state
+    _adapter_initialized = False
+    adapter._first_run = True
+    
+    logger.info(f"Repo removed, adapter will reinitialize on next run")
+    
+    return {"message": "Repository removed"}
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {
+        "status": "healthy",
+        "session_id": context.session_id if context else None,
+    }
+
+
+def main():
+    """Start the AG-UI server."""
+    port = int(os.getenv("AGUI_PORT", "8000"))
+    host = os.getenv("AGUI_HOST", "0.0.0.0")
+    
+    logger.info(f"Starting Claude Code AG-UI server on {host}:{port}")
+    
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()
+
diff --git a/components/runners/claude-code-runner/observability.py b/components/runners/claude-code-runner/observability.py
index fe315fb97..5ff085bc9 100644
--- a/components/runners/claude-code-runner/observability.py
+++ b/components/runners/claude-code-runner/observability.py
@@ -339,8 +339,12 @@ def end_turn(self, turn_count: int, message: Any, usage: dict | None = None) ->
             message: AssistantMessage from Claude SDK
             usage: Usage dict from ResultMessage with input_tokens, output_tokens, cache tokens, etc.
         """
+        # Return silently if Langfuse not initialized
+        if not self.langfuse_client:
+            return
+            
         if not self._current_turn_generation:
-            logging.warning(f"Langfuse: end_turn called but no active turn for turn {turn_count}")
+            logging.debug(f"Langfuse: end_turn called but no active turn for turn {turn_count} (may not be initialized)")
             return
 
         try:
diff --git a/components/runners/claude-code-runner/pyproject.toml b/components/runners/claude-code-runner/pyproject.toml
index 918fd3fe5..5faafe4ac 100644
--- a/components/runners/claude-code-runner/pyproject.toml
+++ b/components/runners/claude-code-runner/pyproject.toml
@@ -1,19 +1,34 @@
 [project]
 name = "claude-code-runner"
-version = "0.1.0"
-description = "Runner that streams via Claude Code SDK and syncs workspace via PVC proxy"
+version = "0.2.0"
+description = "AG-UI Server for Claude Code SDK"
 readme = "CLAUDE.md"
 requires-python = ">=3.11"
 authors = [
   { name = "vTeam" }
 ]
 dependencies = [
-  "requests>=2.31.0",
-  "aiohttp>=3.8.0",
-  "pyjwt>=2.8.0",
+  # AG-UI Server
+  "fastapi>=0.100.0",
+  "uvicorn[standard]>=0.23.0",
+  
+  # AG-UI Protocol SDK (official)
+  "ag-ui-protocol>=0.1.0",
+  
+  # Claude SDK
   "anthropic[vertex]>=0.68.0",
   "claude-agent-sdk>=0.1.12",
+  
+  # Observability
   "langfuse>=3.0.0",
+  
+  # Utilities
+  "pydantic>=2.0.0",
+  "aiohttp>=3.8.0",
+  "requests>=2.31.0",
+  "pyjwt>=2.8.0",
+  
+  # MCP integrations
   "mcp-atlassian>=0.11.9",
 ]
 
@@ -24,10 +39,11 @@ dev-dependencies = [
   "pytest-cov>=4.1.0",
   "ruff>=0.1.0",
   "black>=23.0.0",
+  "httpx>=0.24.0",
 ]
 
 [tool.setuptools]
-py-modules = ["wrapper", "observability", "security_utils"]
+py-modules = ["main", "adapter", "context", "observability", "security_utils"]
 
 [build-system]
 requires = ["setuptools>=61.0"]
diff --git a/components/runners/claude-code-runner/wrapper.py b/components/runners/claude-code-runner/wrapper.py
deleted file mode 100644
index e94f9e02c..000000000
--- a/components/runners/claude-code-runner/wrapper.py
+++ /dev/null
@@ -1,2147 +0,0 @@
-#!/usr/bin/env python3
-"""
-Claude Code CLI wrapper for runner-shell integration.
-Bridges the existing Claude Code CLI with the standardized runner-shell framework.
-"""
-
-import asyncio
-import os
-import sys
-import logging
-import json as _json
-import re
-import shutil
-from pathlib import Path
-from urllib.parse import urlparse, urlunparse
-from urllib import request as _urllib_request, error as _urllib_error
-
-# Set umask to make files readable by content service container
-# Creates files with mode 644 (rw-r--r--) instead of default 600 (rw-------)
-os.umask(0o022)
-
-# Add runner-shell to Python path
-# Required: runner-shell is installed in /app/runner-shell and contains the core RunnerShell framework
-# that this wrapper depends on. Must be imported before runner_shell module below.
-sys.path.insert(0, '/app/runner-shell')
-
-from runner_shell.core.shell import RunnerShell
-from runner_shell.core.protocol import MessageType, PartialInfo
-from runner_shell.core.context import RunnerContext
-
-
-class PrerequisiteError(RuntimeError):
-    """Raised when slash-command prerequisites are missing."""
-    pass
-
-
-class ClaudeCodeAdapter:
-    """Adapter that wraps the existing Claude Code CLI for runner-shell."""
-
-    def __init__(self):
-        self.context = None
-        self.shell = None
-        self.last_exit_code = 1
-        self.claude_process = None
-        self._incoming_queue: "asyncio.Queue[dict]" = asyncio.Queue()
-        self._restart_requested = False
-        self._first_run = True  # Track if this is the first SDK run or a mid-session restart
-        self._skip_resume_on_restart = False  # When true, don't try to resume SDK session
-
-    async def initialize(self, context: RunnerContext):
-        """Initialize the adapter with context."""
-        self.context = context
-        logging.info(f"Initialized Claude Code adapter for session {context.session_id}")
-        # Copy Google OAuth credentials from mounted Secret to writable workspace location
-        await self._setup_google_credentials()
-        # Prepare workspace from input repo if provided
-        await self._prepare_workspace()
-        # Initialize workflow if ACTIVE_WORKFLOW env vars are set
-        await self._initialize_workflow_if_set()
-        # Validate prerequisite files exist for phase-based commands
-        try:
-            await self._validate_prerequisites()
-        except PrerequisiteError as exc:
-            self.last_exit_code = 2
-            logging.error("Prerequisite validation failed during initialization: %s", exc)
-            raise
-
-    @staticmethod
-    def _sanitize_user_context(user_id: str, user_name: str) -> tuple[str, str]:
-        """Validate and sanitize user context fields to prevent injection attacks.
-
-        This function enforces STRICT validation for values sent to external APIs
-        (Langfuse trace metadata, database queries, URL parameters).
-
-        Differs from validate_and_sanitize_for_logging() which is lenient and only
-        removes control characters for safe logging. This function uses strict pattern
-        matching to ensure API compatibility and prevent query injection.
-
-        Returns:
-            Tuple of (sanitized_user_id, sanitized_user_name)
-        """
-        # Validate user_id: alphanumeric, dash, underscore, at sign only
-        # Max 255 characters (email addresses can be up to 254 chars)
-        if user_id:
-            user_id = str(user_id).strip()
-            if len(user_id) > 255:
-                logging.warning(f"User ID exceeds max length (255), truncating: {len(user_id)} chars")
-                user_id = user_id[:255]
-            # Remove any characters that could cause injection issues
-            import re
-            sanitized_id = re.sub(r'[^a-zA-Z0-9@._-]', '', user_id)
-            if sanitized_id != user_id:
-                logging.warning(f"User ID contained invalid characters, sanitized from {len(user_id)} to {len(sanitized_id)} chars")
-            user_id = sanitized_id
-
-        # Validate user_name: printable ASCII, no control characters
-        # Max 255 characters
-        if user_name:
-            user_name = str(user_name).strip()
-            if len(user_name) > 255:
-                logging.warning(f"User name exceeds max length (255), truncating: {len(user_name)} chars")
-                user_name = user_name[:255]
-            # Remove control characters and non-printable characters
-            import re
-            sanitized_name = re.sub(r'[\x00-\x1f\x7f-\x9f]', '', user_name)
-            if sanitized_name != user_name:
-                logging.warning(f"User name contained control characters, sanitized from {len(user_name)} to {len(sanitized_name)} chars")
-            user_name = sanitized_name
-
-        return user_id, user_name
-
-    async def run(self):
-        """Run the Claude Code CLI session."""
-        try:
-            # Wait for WebSocket connection to be established before sending messages
-            # The shell.start() call happens before this method, but the WS connection is async
-            # and may not be ready yet. Retry first message send to ensure connection is up.
-            await self._wait_for_ws_connection()
-
-            # Get prompt from environment
-            prompt = self.context.get_env("INITIAL_PROMPT", "")
-            if not prompt:
-                prompt = self.context.get_metadata("prompt", "Hello! How can I help you today?")
-
-            # Send progress update
-            await self._send_log("Starting Claude Code session...")
-
-            # Append token to websocket URL if available (to pass SA token to backend)
-            try:
-                if self.shell and getattr(self.shell, 'transport', None):
-                    ws = getattr(self.shell.transport, 'url', '') or ''
-                    bot = (os.getenv('BOT_TOKEN') or '').strip()
-                    if bot and ws and '?' not in ws:
-                        # Safe to append token as query for backend to map into Authorization
-                        setattr(self.shell.transport, 'url', ws + f"?token={bot}")
-            except Exception:
-                pass
-
-            # Execute Claude Code CLI with restart support for workflow switching
-            result = None
-            while True:
-                result = await self._run_claude_agent_sdk(prompt)
-
-                # Check if restart was requested (workflow changed)
-                if self._restart_requested:
-                    self._restart_requested = False
-                    self._skip_resume_on_restart = True  # Don't try to resume - session is invalidated
-                    await self._send_log("🔄 Restarting Claude with new workflow...")
-                    logging.info("Restarting Claude SDK due to workflow change")
-                    # Loop will call _run_claude_agent_sdk again with updated env vars
-                    continue
-
-                # Normal exit - no restart requested
-                break
-
-            success = not (isinstance(result, dict) and result.get("success") is False)
-            if success:
-                await self._send_log("Claude Code session completed")
-            else:
-                await self._send_log("Claude Code session completed with issues")
-
-            try:
-                auto_push = str(self.context.get_env('AUTO_PUSH_ON_COMPLETE', 'false')).strip().lower() in ('1','true','yes')
-            except Exception:
-                auto_push = False
-            if auto_push and success:
-                await self._push_results_if_any()
-
-            self.last_exit_code = 0 if success else 1
-            return result
-
-        except PrerequisiteError as e:
-            self.last_exit_code = 2
-            logging.error(f"Prerequisite validation failed: {e}")
-            return {
-                "success": False,
-                "error": str(e),
-            }
-        except Exception as e:
-            self.last_exit_code = 1
-            logging.error(f"Claude Code adapter failed: {e}")
-            return {
-                "success": False,
-                "error": str(e)
-            }
-
-    async def _run_claude_agent_sdk(self, prompt: str):
-        """Execute the Claude Code SDK with the given prompt."""
-        try:
-            # Check for authentication method: API key or service account
-            # IMPORTANT: Must check and set env vars BEFORE importing SDK
-            api_key = self.context.get_env('ANTHROPIC_API_KEY', '')
-            # SDK official flag is CLAUDE_CODE_USE_VERTEX=1
-            use_vertex = (
-                self.context.get_env('CLAUDE_CODE_USE_VERTEX', '').strip() == '1'
-                )
-
-            # Determine which authentication method to use
-            if not api_key and not use_vertex:
-                raise RuntimeError("Either ANTHROPIC_API_KEY or CLAUDE_CODE_USE_VERTEX=1 must be set")
-
-            # Set environment variables BEFORE importing SDK
-            # The Anthropic SDK checks these during initialization
-            if api_key:
-                os.environ['ANTHROPIC_API_KEY'] = api_key
-                logging.info("Using Anthropic API key authentication")
-
-            # Configure Vertex AI if requested
-            if use_vertex:
-                vertex_credentials = await self._setup_vertex_credentials()
-
-                # Clear API key if set, to force Vertex AI mode
-                if 'ANTHROPIC_API_KEY' in os.environ:
-                    logging.info("Clearing ANTHROPIC_API_KEY to force Vertex AI mode")
-                    del os.environ['ANTHROPIC_API_KEY']
-
-                # Set the SDK's official Vertex AI flag
-                os.environ['CLAUDE_CODE_USE_VERTEX'] = '1'
-
-                # Set Vertex AI environment variables
-                os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = vertex_credentials.get('credentials_path', '')
-                os.environ['ANTHROPIC_VERTEX_PROJECT_ID'] = vertex_credentials.get('project_id', '')
-                os.environ['CLOUD_ML_REGION'] = vertex_credentials.get('region', '')
-
-                logging.info(f"Vertex AI environment configured:")
-                logging.info(f"  CLAUDE_CODE_USE_VERTEX: {os.environ.get('CLAUDE_CODE_USE_VERTEX')}")
-                logging.info(f"  GOOGLE_APPLICATION_CREDENTIALS: {os.environ.get('GOOGLE_APPLICATION_CREDENTIALS')}")
-                logging.info(f"  ANTHROPIC_VERTEX_PROJECT_ID: {os.environ.get('ANTHROPIC_VERTEX_PROJECT_ID')}")
-                logging.info(f"  CLOUD_ML_REGION: {os.environ.get('CLOUD_ML_REGION')}")
-
-            # NOW we can safely import the SDK with the correct environment set
-            from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
-
-            from observability import ObservabilityManager
-
-            # Extract and sanitize user context for observability (used by Langfuse)
-            # This prevents trace poisoning, log injection, and other security issues
-            raw_user_id = os.getenv('USER_ID', '').strip()
-            raw_user_name = os.getenv('USER_NAME', '').strip()
-            user_id, user_name = self._sanitize_user_context(raw_user_id, raw_user_name)
-
-            # Get model configuration early for observability tracking
-            model = self.context.get_env('LLM_MODEL')
-            configured_model = model or 'claude-sonnet-4-5@20250929'  # Default model for tracking
-
-            # Map to Vertex model if using Vertex
-            if use_vertex and model:
-                configured_model = self._map_to_vertex_model(model)
-
-            # Initialize observability (Langfuse) with model metadata
-            obs = ObservabilityManager(session_id=self.context.session_id, user_id=user_id, user_name=user_name)
-            await obs.initialize(
-                prompt=prompt,
-                namespace=self.context.get_env('AGENTIC_SESSION_NAMESPACE', 'unknown'),
-                model=configured_model
-            )
-
-            # Store initial prompt for turn 1 (will be used when AssistantMessage arrives)
-            obs._pending_initial_prompt = prompt
-
-            # Check if continuing from previous session
-            # If PARENT_SESSION_ID is set, use SDK's built-in resume functionality
-            parent_session_id = self.context.get_env('PARENT_SESSION_ID', '').strip()
-            is_continuation = bool(parent_session_id)
-
-            # Determine cwd and additional dirs from multi-repo config or workflow
-            repos_cfg = self._get_repos_config()
-            cwd_path = self.context.workspace_path
-            add_dirs = []
-            derived_name = None  # Track workflow name for system prompt
-
-            # Check for active workflow first
-            active_workflow_url = (os.getenv('ACTIVE_WORKFLOW_GIT_URL') or '').strip()
-            if active_workflow_url:
-                # Derive workflow name from URL
-                try:
-                    owner, repo, _ = self._parse_owner_repo(active_workflow_url)
-                    derived_name = repo or ''
-                    if not derived_name:
-                        p = urlparse(active_workflow_url)
-                        parts = [p for p in (p.path or '').split('/') if p]
-                        if parts:
-                            derived_name = parts[-1]
-                    derived_name = (derived_name or '').removesuffix('.git').strip()
-
-                    if derived_name:
-                        workflow_path = str(Path(self.context.workspace_path) / "workflows" / derived_name)
-                        # NOTE: Don't append ACTIVE_WORKFLOW_PATH here - we already extracted
-                        # the subdirectory during clone, so workflow_path is the final location
-
-                        if Path(workflow_path).exists():
-                            cwd_path = workflow_path
-                            logging.info(f"Using workflow as CWD: {derived_name}")
-                        else:
-                            logging.warning(f"Workflow directory not found: {workflow_path}, using default")
-                            cwd_path = str(Path(self.context.workspace_path) / "workflows" / "default")
-                    else:
-                        cwd_path = str(Path(self.context.workspace_path) / "workflows" / "default")
-                except Exception as e:
-                    logging.warning(f"Failed to derive workflow name: {e}, using default")
-                    cwd_path = str(Path(self.context.workspace_path) / "workflows" / "default")
-
-                # Add all repos as additional directories so they're accessible to Claude
-                for r in repos_cfg:
-                    name = (r.get('name') or '').strip()
-                    if name:
-                        repo_path = str(Path(self.context.workspace_path) / name)
-                        if repo_path not in add_dirs:
-                            add_dirs.append(repo_path)
-                            logging.info(f"Added repo as additional directory: {name}")
-
-                # Add artifacts directory
-                artifacts_path = str(Path(self.context.workspace_path) / "artifacts")
-                if artifacts_path not in add_dirs:
-                    add_dirs.append(artifacts_path)
-                    logging.info("Added artifacts directory as additional directory")
-
-                # Add file-uploads directory
-                file_uploads_path = str(Path(self.context.workspace_path) / "file-uploads")
-                if file_uploads_path not in add_dirs:
-                    add_dirs.append(file_uploads_path)
-                    logging.info("Added file-uploads directory as additional directory")
-            elif repos_cfg:
-                # Multi-repo mode: Prefer explicit MAIN_REPO_NAME, else use MAIN_REPO_INDEX, else default to 0
-                main_name = (os.getenv('MAIN_REPO_NAME') or '').strip()
-                if not main_name:
-                    idx_raw = (os.getenv('MAIN_REPO_INDEX') or '').strip()
-                    try:
-                        idx_val = int(idx_raw) if idx_raw else 0
-                    except Exception:
-                        idx_val = 0
-                    if idx_val < 0 or idx_val >= len(repos_cfg):
-                        idx_val = 0
-                    main_name = (repos_cfg[idx_val].get('name') or '').strip()
-                # CWD becomes main repo folder under workspace
-                if main_name:
-                    cwd_path = str(Path(self.context.workspace_path) / main_name)
-                # Add other repos as additional directories
-                for r in repos_cfg:
-                    name = (r.get('name') or '').strip()
-                    if not name:
-                        continue
-                    p = str(Path(self.context.workspace_path) / name)
-                    if p != cwd_path:
-                        add_dirs.append(p)
-
-                # Add artifacts directory for repos mode too
-                artifacts_path = str(Path(self.context.workspace_path) / "artifacts")
-                if artifacts_path not in add_dirs:
-                    add_dirs.append(artifacts_path)
-                    logging.info("Added artifacts directory as additional directory")
-
-                # Add file-uploads directory for repos mode too
-                file_uploads_path = str(Path(self.context.workspace_path) / "file-uploads")
-                if file_uploads_path not in add_dirs:
-                    add_dirs.append(file_uploads_path)
-                    logging.info("Added file-uploads directory as additional directory")
-            else:
-                # No workflow and no repos: start in artifacts directory for ad-hoc work
-                cwd_path = str(Path(self.context.workspace_path) / "artifacts")
-
-            # Load ambient.json configuration (only if workflow is active)
-            ambient_config = self._load_ambient_config(cwd_path) if active_workflow_url else {}
-
-            # Ensure the working directory exists before passing to SDK
-            cwd_path_obj = Path(cwd_path)
-            if not cwd_path_obj.exists():
-                logging.warning(f"Working directory does not exist, creating: {cwd_path}")
-                try:
-                    cwd_path_obj.mkdir(parents=True, exist_ok=True)
-                    logging.info(f"Created working directory: {cwd_path}")
-                except Exception as e:
-                    logging.error(f"Failed to create working directory: {e}")
-                    # Fall back to workspace root
-                    cwd_path = self.context.workspace_path
-                    logging.info(f"Falling back to workspace root: {cwd_path}")
-
-            # Log working directory and additional directories for debugging
-            logging.info(f"Claude SDK CWD: {cwd_path}")
-            logging.info(f"Claude SDK additional directories: {add_dirs}")
-
-            # Load MCP server configuration from .mcp.json if present
-            mcp_servers = self._load_mcp_config(cwd_path)
-            # Build allowed_tools list with MCP server
-            allowed_tools = ["Read","Write","Bash","Glob","Grep","Edit","MultiEdit","WebSearch","WebFetch"]
-            if mcp_servers:
-                # Add permissions for all tools from each MCP server
-                for server_name in mcp_servers.keys():
-                    allowed_tools.append(f"mcp__{server_name}")
-                logging.info(f"MCP tool permissions granted for servers: {list(mcp_servers.keys())}")
-
-            # Build comprehensive workspace context system prompt
-            workspace_prompt = self._build_workspace_context_prompt(
-                repos_cfg=repos_cfg,
-                workflow_name=derived_name if active_workflow_url else None,
-                artifacts_path="artifacts",
-                ambient_config=ambient_config
-            )
-            system_prompt_config = {
-                "type": "text",
-                "text": workspace_prompt
-            }
-            logging.info(f"Applied workspace context system prompt (length: {len(workspace_prompt)} chars)")
-
-            # Configure SDK options with session resumption if continuing
-            options = ClaudeAgentOptions(
-                cwd=cwd_path,
-                permission_mode="acceptEdits",
-                allowed_tools=allowed_tools,
-                mcp_servers=mcp_servers,
-                setting_sources=["project"],
-                system_prompt=system_prompt_config
-                )
-
-            # Use SDK's built-in continue_conversation feature
-            # The CLI stores session state in /app/.claude which is persisted in PVC
-            # This automatically resumes the conversation without needing to track session IDs
-            # Always enable on restarts so conversation context is preserved
-            if not self._first_run or is_continuation:
-                try:
-                    options.continue_conversation = True  # type: ignore[attr-defined]
-                    logging.info("Enabled continue_conversation for session resumption")
-                    await self._send_log("🔄 Continuing conversation from previous state")
-                except Exception as e:
-                    logging.warning(f"Failed to set continue_conversation: {e}")
-            
-            # Reset skip flag if it was set
-            if self._skip_resume_on_restart:
-                self._skip_resume_on_restart = False
-
-            # Best-effort set add_dirs if supported by SDK version
-            try:
-                if add_dirs:
-                    options.add_dirs = add_dirs  # type: ignore[attr-defined]
-            except Exception:
-                pass
-            # Model settings - use configured_model that was already set for observability
-            if model:
-                try:
-                    # Apply the model configuration to SDK options
-                    # Note: configured_model already has Vertex mapping applied if needed
-                    if use_vertex:
-                        logging.info(f"Using Vertex AI model: {configured_model}")
-                    options.model = configured_model  # type: ignore[attr-defined]
-                except Exception:
-                    pass
-            max_tokens_env = (
-                self.context.get_env('LLM_MAX_TOKENS') or
-                self.context.get_env('MAX_TOKENS')
-            )
-            if max_tokens_env:
-                try:
-                    options.max_tokens = int(max_tokens_env)  # type: ignore[attr-defined]
-                except Exception:
-                    pass
-            temperature_env = (
-                self.context.get_env('LLM_TEMPERATURE') or
-                self.context.get_env('TEMPERATURE')
-            )
-            if temperature_env:
-                try:
-                    options.temperature = float(temperature_env)  # type: ignore[attr-defined]
-                except Exception:
-                    pass
-
-            result_payload = None
-            self._turn_count = 0
-            # Store current message and usage for tracking
-            current_message = None
-            current_usage = None
-
-            # Import SDK message and content types for accurate mapping
-            from claude_agent_sdk import (
-                AssistantMessage,
-                UserMessage,
-                SystemMessage,
-                ResultMessage,
-                TextBlock,
-                ThinkingBlock,
-                ToolUseBlock,
-                ToolResultBlock,
-            )
-            # Determine interactive mode once for this run
-            interactive = str(self.context.get_env('INTERACTIVE', 'false')).strip().lower() in ('1', 'true', 'yes')
-
-            sdk_session_id = None
-
-            async def process_response_stream(client_obj):
-                nonlocal result_payload, sdk_session_id, current_message, current_usage
-                async for message in client_obj.receive_response():
-                    logging.info(f"[ClaudeSDKClient]: {message}")
-
-                    # Capture SDK session ID from init message
-                    if isinstance(message, SystemMessage):
-                        if message.subtype == 'init' and message.data.get('session_id'):
-                            sdk_session_id = message.data.get('session_id')
-                            logging.info(f"Captured SDK session ID: {sdk_session_id}")
-                            # Store it in annotations (not status - status gets cleared on restart)
-                            try:
-                                await self._update_cr_annotation("ambient-code.io/sdk-session-id", sdk_session_id)
-                            except Exception as e:
-                                logging.warning(f"Failed to store SDK session ID in CR annotations: {e}")
-
-                    if isinstance(message, (AssistantMessage, UserMessage)):
-                        # Store AssistantMessage for tracking after we get usage from ResultMessage
-                        if isinstance(message, AssistantMessage):
-                            current_message = message
-                            # Start turn tracking NOW so tools can be parented to it
-                            # Turn number will be added to metadata when ResultMessage arrives with SDK's authoritative num_turns
-                            logging.info(f"Langfuse: AssistantMessage received, starting turn trace (current _turn_count={self._turn_count})")
-                            obs.start_turn(configured_model)
-
-                        for block in getattr(message, 'content', []) or []:
-                            if isinstance(block, TextBlock):
-                                text_piece = getattr(block, 'text', None)
-                                if text_piece:
-                                    await self.shell._send_message(
-                                        MessageType.AGENT_MESSAGE,
-                                        {"type": "agent_message", "content": {"type": "text_block", "text": text_piece}},
-                                    )
-                            elif isinstance(block, ToolUseBlock):
-                                tool_name = getattr(block, 'name', '') or 'unknown'
-                                tool_input = getattr(block, 'input', {}) or {}
-                                tool_id = getattr(block, 'id', None)
-                                await self.shell._send_message(
-                                    MessageType.AGENT_MESSAGE,
-                                    {"tool": tool_name, "input": tool_input, "id": tool_id},
-                                )
-                                # Don't increment turn count here - tools are part of the same turn
-                                # Track tool use in Langfuse (without usage data)
-                                obs.track_tool_use(tool_name, tool_id, tool_input)
-                            elif isinstance(block, ToolResultBlock):
-                                tool_use_id = getattr(block, 'tool_use_id', None)
-                                content = getattr(block, 'content', None)
-                                is_error = getattr(block, 'is_error', None)
-                                result_text = getattr(block, 'text', None)
-
-                                await self.shell._send_message(
-                                    MessageType.AGENT_MESSAGE,
-                                    {
-                                        "tool_result": {
-                                            "tool_use_id": tool_use_id,
-                                            "content": content if content is not None else result_text,
-                                            "is_error": is_error,
-                                        }
-                                    },
-                                )
-                                # Track tool result in Langfuse (without usage data)
-                                obs.track_tool_result(tool_use_id, content if content is not None else result_text, is_error or False)
-                                if interactive:
-                                    await self.shell._send_message(MessageType.WAITING_FOR_INPUT, {})
-                                # Don't increment turn count here - tool results are part of the same turn
-                            elif isinstance(block, ThinkingBlock):
-                                await self._send_log({"level": "debug", "message": "Model is reasoning..."})
-                    elif isinstance(message, (SystemMessage)):
-                        text = getattr(message, 'text', None)
-                        if text:
-                            await self._send_log({"level": "debug", "message": str(text)})
-                    elif isinstance(message, (ResultMessage)):
-                        # Extract usage from ResultMessage
-                        usage_raw = getattr(message, 'usage', None)
-                        sdk_num_turns = getattr(message, 'num_turns', None)
-                        subtype = getattr(message, 'subtype', None)
-
-                        logging.info(f"ResultMessage: subtype={subtype}, num_turns={sdk_num_turns}, usage={usage_raw}")
-
-                        # Convert usage object to dict if needed
-                        if usage_raw is not None and not isinstance(usage_raw, dict):
-                            try:
-                                if hasattr(usage_raw, '__dict__'):
-                                    usage_raw = usage_raw.__dict__
-                                elif hasattr(usage_raw, 'model_dump'):
-                                    usage_raw = usage_raw.model_dump()
-                            except Exception as e:
-                                logging.warning(f"Could not convert usage object to dict: {e}")
-
-                        # Update turn count from SDK's authoritative num_turns
-                        # This ensures we stay in sync with the SDK's turn tracking
-                        if sdk_num_turns is not None and sdk_num_turns > self._turn_count:
-                            old_count = self._turn_count
-                            self._turn_count = sdk_num_turns
-                            logging.info(f"Updated turn count from {old_count} to SDK's num_turns: {self._turn_count}")
-                        elif sdk_num_turns is not None:
-                            logging.info(f"SDK num_turns={sdk_num_turns} matches or is less than current _turn_count={self._turn_count}, keeping current value")
-
-                        # Complete turn tracking with usage data
-                        # Only end turn if we have a current message (AssistantMessage was received)
-                        if current_message:
-                            logging.info(f"Langfuse: Calling end_turn for turn {self._turn_count} (SDK num_turns={sdk_num_turns}) with current_message present")
-                            obs.end_turn(self._turn_count, current_message, usage_raw if isinstance(usage_raw, dict) else None)
-                            logging.info(f"Langfuse: end_turn completed for turn {self._turn_count}, clearing current_message")
-                            current_message = None  # Clear after tracking
-                        else:
-                            logging.warning(
-                                f"Langfuse: ResultMessage received for turn {self._turn_count} (SDK num_turns={sdk_num_turns}) "
-                                f"but no current_message stored - trace {self._turn_count} will remain incomplete. "
-                                f"This usually means AssistantMessage was not received before ResultMessage."
-                            )
-
-                        result_payload = {
-                            "subtype": getattr(message, 'subtype', None),
-                            "duration_ms": getattr(message, 'duration_ms', None),
-                            "duration_api_ms": getattr(message, 'duration_api_ms', None),
-                            "is_error": getattr(message, 'is_error', None),
-                            "num_turns": getattr(message, 'num_turns', None),
-                            "session_id": getattr(message, 'session_id', None),
-                            "total_cost_usd": getattr(message, 'total_cost_usd', None),
-                            "usage": usage_raw,  # Per-query usage (will be replaced with cumulative at session end)
-                            "result": getattr(message, 'result', None),
-                        }
-
-                        logging.info(f"Built result_payload with per-query usage: {result_payload.get('usage')}")
-
-                        if not interactive:
-                            await self.shell._send_message(
-                                MessageType.AGENT_MESSAGE,
-                                {"type": "result.message", "payload": result_payload},
-                            )
-
-            # Use async with - SDK will use continue_conversation to resume from local state
-            # Wrap in retry logic to handle conversation not found errors
-            def create_sdk_client(opts, disable_continue=False):
-                """Create SDK client, optionally disabling continue_conversation on retry."""
-                if disable_continue and hasattr(opts, 'continue_conversation'):
-                    opts.continue_conversation = False  # type: ignore[attr-defined]
-                return ClaudeSDKClient(options=opts)
-
-            # First attempt - may fail if conversation state is corrupted
-            try:
-                client_ctx = create_sdk_client(options)
-                client = await client_ctx.__aenter__()
-            except Exception as resume_error:
-                error_str = str(resume_error).lower()
-                if "no conversation found" in error_str or "session" in error_str:
-                    logging.warning(f"Conversation continuation failed: {resume_error}")
-                    await self._send_log("⚠️ Could not continue conversation, starting fresh...")
-                    # Retry without continue_conversation
-                    client_ctx = create_sdk_client(options, disable_continue=True)
-                    client = await client_ctx.__aenter__()
-                else:
-                    raise
-
-            try:
-                if not self._first_run:
-                    await self._send_log("✅ Continuing conversation")
-                    logging.info("SDK continuing conversation from local state")
-
-                async def process_one_prompt(text: str):
-                    await self.shell._send_message(MessageType.AGENT_RUNNING, {})
-                    await client.query(text)
-                    await process_response_stream(client)
-
-                # Handle startup prompts
-                # Only send startupPrompt from workflow on restart (not first run)
-                # This way workflow greeting appears when you switch TO a workflow mid-session
-                if not is_continuation:
-                    if ambient_config.get("startupPrompt") and not self._first_run:
-                        # Workflow was just activated - show its greeting
-                        startup_msg = ambient_config["startupPrompt"]
-                        await process_one_prompt(startup_msg)
-                        logging.info(f"Sent workflow startupPrompt ({len(startup_msg)} chars)")
-                    elif prompt and prompt.strip() and self._first_run:
-                        # First run with explicit prompt - use it
-                        await process_one_prompt(prompt)
-                        logging.info("Sent initial prompt to bootstrap session")
-                    else:
-                        logging.info("No initial prompt - Claude will greet based on system prompt")
-                else:
-                    logging.info("Skipping prompts - SDK resuming with full context")
-
-                # Mark that first run is complete
-                self._first_run = False
-
-                if interactive:
-                    await self._send_log({"level": "system", "message": "Chat ready"})
-                    # Consume incoming user messages until end_session
-                    while True:
-                        incoming = await self._incoming_queue.get()
-                        # Normalize mtype: backend can send 'user_message' or 'user.message'
-                        mtype_raw = str(incoming.get('type') or '').strip()
-                        mtype = mtype_raw.replace('.', '_')
-                        payload = incoming.get('payload') or {}
-                        if mtype in ('user_message', 'user_message'):
-                            text = str(payload.get('content') or payload.get('text') or '').strip()
-                            if text:
-                                await process_one_prompt(text)
-                        elif mtype in ('end_session', 'terminate', 'stop'):
-                            await self._send_log({"level": "system", "message": "interactive.ended"})
-                            break
-                        elif mtype == 'workflow_change':
-                            # Handle workflow selection during interactive session
-                            git_url = str(payload.get('gitUrl') or '').strip()
-                            branch = str(payload.get('branch') or 'main').strip()
-                            path = str(payload.get('path') or '').strip()
-                            if git_url:
-                                await self._handle_workflow_selection(git_url, branch, path)
-                                # Break out of interactive loop to trigger restart
-                                break
-                            else:
-                                await self._send_log("⚠️ Workflow change request missing gitUrl")
-                        elif mtype == 'repo_added':
-                            # Handle dynamic repo addition
-                            await self._handle_repo_added(payload)
-                            # Break out of interactive loop to trigger restart
-                            break
-                        elif mtype == 'repo_removed':
-                            # Handle dynamic repo removal
-                            await self._handle_repo_removed(payload)
-                            # Break out of interactive loop to trigger restart
-                            break
-                        elif mtype == 'interrupt':
-                            try:
-                                await client.interrupt()  # type: ignore[attr-defined]
-                                await self._send_log({"level": "info", "message": "interrupt.sent"})
-                            except Exception as e:
-                                await self._send_log({"level": "warn", "message": f"interrupt.failed: {e}"})
-                        else:
-                            await self._send_log({"level": "debug", "message": f"ignored.message: {mtype_raw}"})
-            finally:
-                # Clean up the SDK client context
-                await client_ctx.__aexit__(None, None, None)
-
-            # Note: All output is streamed via WebSocket, not collected here
-            await self._check_pr_intent("")
-
-            # Finalize observability (flush data to Langfuse)
-            await obs.finalize()
-
-            # Return success - result_payload may be None if SDK didn't send ResultMessage
-            # (which can happen legitimately for some operations like git push)
-            return {
-                "success": True,
-                "result": result_payload,
-                "returnCode": 0,
-                "stdout": "",
-                "stderr": ""
-            }
-        except Exception as e:
-            logging.error(f"Failed to run Claude Code SDK: {e}")
-            # Clean up observability spans on error path
-            if 'obs' in locals():
-                await obs.cleanup_on_error(e)
-            return {
-                "success": False,
-                "error": str(e)
-            }
-
-    def _map_to_vertex_model(self, model: str) -> str:
-        """Map Anthropic API model names to Vertex AI model names.
-
-        Args:
-            model: Anthropic API model name (e.g., 'claude-sonnet-4-5')
-
-        Returns:
-            Vertex AI model name (e.g., 'claude-sonnet-4-5@20250929')
-        """
-        # Model mapping from Anthropic API to Vertex AI
-        # Reference: https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude
-        model_map = {
-            'claude-opus-4-5': 'claude-opus-4-5@20251101',
-            'claude-opus-4-1': 'claude-opus-4-1@20250805',
-            'claude-sonnet-4-5': 'claude-sonnet-4-5@20250929',
-            'claude-haiku-4-5': 'claude-haiku-4-5@20251001',
-        }
-
-        mapped = model_map.get(model, model)
-        if mapped != model:
-            logging.info(f"Model mapping: {model} → {mapped}")
-        return mapped
-
-    async def _setup_vertex_credentials(self) -> dict:
-        """Set up Google Cloud Vertex AI credentials from service account.
-
-        Returns:
-            dict with 'credentials_path', 'project_id', and 'region'
-
-        Raises:
-            RuntimeError: If required Vertex AI configuration is missing
-        """
-        # Get service account configuration from environment
-        # These are passed by the operator from its own environment
-        service_account_path = self.context.get_env('GOOGLE_APPLICATION_CREDENTIALS', '').strip()
-        project_id = self.context.get_env('ANTHROPIC_VERTEX_PROJECT_ID', '').strip()
-        region = self.context.get_env('CLOUD_ML_REGION', '').strip()
-
-        # Validate required fields
-        if not service_account_path:
-            raise RuntimeError("GOOGLE_APPLICATION_CREDENTIALS must be set when CLAUDE_CODE_USE_VERTEX=1")
-        if not project_id:
-            raise RuntimeError("ANTHROPIC_VERTEX_PROJECT_ID must be set when CLAUDE_CODE_USE_VERTEX=1")
-        if not region:
-            raise RuntimeError("CLOUD_ML_REGION must be set when CLAUDE_CODE_USE_VERTEX=1")
-
-        # Verify service account file exists
-        if not Path(service_account_path).exists():
-            raise RuntimeError(f"Service account key file not found at {service_account_path}")
-
-        logging.info(f"Vertex AI configured: project={project_id}, region={region}")
-        await self._send_log(f"Using Vertex AI with project {project_id} in {region}")
-
-        return {
-            'credentials_path': service_account_path,
-            'project_id': project_id,
-            'region': region,
-        }
-
-    async def _setup_google_credentials(self):
-        """Copy Google OAuth credentials from mounted Secret to writable workspace location."""
-        # Check if Google OAuth secret is mounted
-        secret_path = Path("/app/.google_workspace_mcp/credentials/credentials.json")
-        if not secret_path.exists():
-            logging.debug("Google OAuth credentials not found at %s, skipping setup", secret_path)
-            return
-
-        # Create writable credentials directory in workspace
-        workspace_creds_dir = Path("/workspace/.google_workspace_mcp/credentials")
-        workspace_creds_dir.mkdir(parents=True, exist_ok=True)
-
-        # Copy credentials from read-only Secret mount to writable workspace
-        dest_path = workspace_creds_dir / "credentials.json"
-        try:
-            shutil.copy2(secret_path, dest_path)
-            # Make it writable so workspace-mcp can update tokens
-            dest_path.chmod(0o644)
-            logging.info("✓ Copied Google OAuth credentials from Secret to writable workspace at %s", dest_path)
-        except Exception as e:
-            logging.error("Failed to copy Google OAuth credentials: %s", e)
-
-    async def _prepare_workspace(self):
-        """Clone input repo/branch into workspace and configure git remotes."""
-        workspace = Path(self.context.workspace_path)
-        workspace.mkdir(parents=True, exist_ok=True)
-
-        # Check if reusing workspace from previous session
-        parent_session_id = self.context.get_env('PARENT_SESSION_ID', '').strip()
-        reusing_workspace = bool(parent_session_id)
-
-        logging.info(f"Workspace preparation: parent_session_id={parent_session_id[:8] if parent_session_id else 'None'}, reusing={reusing_workspace}")
-        if reusing_workspace:
-            await self._send_log(f"♻️ Reusing workspace from session {parent_session_id[:8]}")
-            logging.info("Preserving existing workspace state for continuation")
-
-        repos_cfg = self._get_repos_config()
-        if repos_cfg:
-            # Multi-repo: clone each into workspace/<name>
-            try:
-                for r in repos_cfg:
-                    name = (r.get('name') or '').strip()
-                    inp = r.get('input') or {}
-                    url = (inp.get('url') or '').strip()
-                    branch = (inp.get('branch') or '').strip() or 'main'
-                    if not name or not url:
-                        continue
-                    repo_dir = workspace / name
-
-                    # Fetch appropriate token for this repo's URL
-                    token = await self._fetch_token_for_url(url)
-
-                    # Check if repo already exists
-                    repo_exists = repo_dir.exists() and (repo_dir / ".git").exists()
-
-                    if not repo_exists:
-                        # Clone fresh copy
-                        await self._send_log(f"📥 Cloning {name}...")
-                        logging.info(f"Cloning {name} from {url} (branch: {branch})")
-                        clone_url = self._url_with_token(url, token) if token else url
-                        await self._run_cmd(["git", "clone", "--branch", branch, "--single-branch", clone_url, str(repo_dir)], cwd=str(workspace))
-                        # Update remote URL to persist token (git strips it from clone URL)
-                        await self._run_cmd(["git", "remote", "set-url", "origin", clone_url], cwd=str(repo_dir), ignore_errors=True)
-                        logging.info(f"Successfully cloned {name}")
-                    elif reusing_workspace:
-                        # Reusing workspace - preserve local changes from previous session
-                        await self._send_log(f"✓ Preserving {name} (continuation)")
-                        logging.info(f"Repo {name} exists and reusing workspace - preserving all local changes")
-                        # Update remote URL in case credentials changed
-                        await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(url, token) if token else url], cwd=str(repo_dir), ignore_errors=True)
-                        # Don't fetch, don't reset - keep all changes!
-                    else:
-                        # Repo exists but NOT reusing - reset to clean state
-                        await self._send_log(f"🔄 Resetting {name} to clean state")
-                        logging.info(f"Repo {name} exists but not reusing - resetting to clean state")
-                        await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(url, token) if token else url], cwd=str(repo_dir), ignore_errors=True)
-                        await self._run_cmd(["git", "fetch", "origin", branch], cwd=str(repo_dir))
-                        await self._run_cmd(["git", "checkout", branch], cwd=str(repo_dir))
-                        await self._run_cmd(["git", "reset", "--hard", f"origin/{branch}"], cwd=str(repo_dir))
-                        logging.info(f"Reset {name} to origin/{branch}")
-
-                    # Git identity with fallbacks
-                    user_name = os.getenv("GIT_USER_NAME", "").strip() or "Ambient Code Bot"
-                    user_email = os.getenv("GIT_USER_EMAIL", "").strip() or "bot@ambient-code.local"
-                    await self._run_cmd(["git", "config", "user.name", user_name], cwd=str(repo_dir))
-                    await self._run_cmd(["git", "config", "user.email", user_email], cwd=str(repo_dir))
-                    logging.info(f"Git identity configured: {user_name} <{user_email}>")
-
-                    # Configure output remote if present
-                    out = r.get('output') or {}
-                    out_url_raw = (out.get('url') or '').strip()
-                    if out_url_raw:
-                        out_url = self._url_with_token(out_url_raw, token) if token else out_url_raw
-                        await self._run_cmd(["git", "remote", "remove", "output"], cwd=str(repo_dir), ignore_errors=True)
-                        await self._run_cmd(["git", "remote", "add", "output", out_url], cwd=str(repo_dir))
-            except Exception as e:
-                logging.error(f"Failed to prepare multi-repo workspace: {e}")
-                await self._send_log(f"Workspace preparation failed: {e}")
-            return
-
-        # Single-repo legacy flow
-        input_repo = os.getenv("INPUT_REPO_URL", "").strip()
-        if not input_repo:
-            logging.info("No INPUT_REPO_URL configured, skipping single-repo setup")
-            return
-        input_branch = os.getenv("INPUT_BRANCH", "").strip() or "main"
-        output_repo = os.getenv("OUTPUT_REPO_URL", "").strip()
-
-        # Fetch appropriate token for this repo's URL
-        token = await self._fetch_token_for_url(input_repo)
-
-        workspace_has_git = (workspace / ".git").exists()
-        logging.info(f"Single-repo setup: workspace_has_git={workspace_has_git}, reusing={reusing_workspace}")
-
-        try:
-            if not workspace_has_git:
-                # Clone fresh copy
-                await self._send_log("📥 Cloning input repository...")
-                logging.info(f"Cloning from {input_repo} (branch: {input_branch})")
-                clone_url = self._url_with_token(input_repo, token) if token else input_repo
-                await self._run_cmd(["git", "clone", "--branch", input_branch, "--single-branch", clone_url, str(workspace)], cwd=str(workspace.parent))
-                # Update remote URL to persist token (git strips it from clone URL)
-                await self._run_cmd(["git", "remote", "set-url", "origin", clone_url], cwd=str(workspace), ignore_errors=True)
-                logging.info("Successfully cloned repository")
-            elif reusing_workspace:
-                # Reusing workspace - preserve local changes from previous session
-                await self._send_log("✓ Preserving workspace (continuation)")
-                logging.info("Workspace exists and reusing - preserving all local changes")
-                await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(input_repo, token) if token else input_repo], cwd=str(workspace), ignore_errors=True)
-                # Don't fetch, don't reset - keep all changes!
-            else:
-                # Reset to clean state
-                await self._send_log("🔄 Resetting workspace to clean state")
-                logging.info("Workspace exists but not reusing - resetting to clean state")
-                await self._run_cmd(["git", "remote", "set-url", "origin", self._url_with_token(input_repo, token) if token else input_repo], cwd=str(workspace))
-                await self._run_cmd(["git", "fetch", "origin", input_branch], cwd=str(workspace))
-                await self._run_cmd(["git", "checkout", input_branch], cwd=str(workspace))
-                await self._run_cmd(["git", "reset", "--hard", f"origin/{input_branch}"], cwd=str(workspace))
-                logging.info(f"Reset workspace to origin/{input_branch}")
-
-            # Git identity with fallbacks
-            user_name = os.getenv("GIT_USER_NAME", "").strip() or "Ambient Code Bot"
-            user_email = os.getenv("GIT_USER_EMAIL", "").strip() or "bot@ambient-code.local"
-            await self._run_cmd(["git", "config", "user.name", user_name], cwd=str(workspace))
-            await self._run_cmd(["git", "config", "user.email", user_email], cwd=str(workspace))
-            logging.info(f"Git identity configured: {user_name} <{user_email}>")
-
-            if output_repo:
-                await self._send_log("Configuring output remote...")
-                out_url = self._url_with_token(output_repo, token) if token else output_repo
-                await self._run_cmd(["git", "remote", "remove", "output"], cwd=str(workspace), ignore_errors=True)
-                await self._run_cmd(["git", "remote", "add", "output", out_url], cwd=str(workspace))
-
-        except Exception as e:
-            logging.error(f"Failed to prepare workspace: {e}")
-            await self._send_log(f"Workspace preparation failed: {e}")
-
-        # Create artifacts directory (initial working directory)
-        try:
-            artifacts_dir = workspace / "artifacts"
-            artifacts_dir.mkdir(parents=True, exist_ok=True)
-            logging.info("Created artifacts directory")
-        except Exception as e:
-            logging.warning(f"Failed to create artifacts directory: {e}")
-
-    async def _validate_prerequisites(self):
-        """Validate prerequisite files exist for phase-based slash commands."""
-        prompt = self.context.get_env("INITIAL_PROMPT", "")
-        if not prompt:
-            return
-
-        # Extract slash command from prompt (e.g., "/speckit.plan", "/speckit.tasks", "/speckit.implement")
-        prompt_lower = prompt.strip().lower()
-
-        # Define prerequisite requirements
-        prerequisites = {
-            "/speckit.plan": ("spec.md", "Specification file (spec.md) not found. Please run /speckit.specify first to generate the specification."),
-            "/speckit.tasks": ("plan.md", "Planning file (plan.md) not found. Please run /speckit.plan first to generate the implementation plan."),
-            "/speckit.implement": ("tasks.md", "Tasks file (tasks.md) not found. Please run /speckit.tasks first to generate the task breakdown.")
-        }
-
-        # Check if prompt starts with a slash command that requires prerequisites
-        for cmd, (required_file, error_msg) in prerequisites.items():
-            if prompt_lower.startswith(cmd):
-                # Search for the required file in workspace
-                workspace = Path(self.context.workspace_path)
-                found = False
-
-                # Check in main workspace
-                if (workspace / required_file).exists():
-                    found = True
-                    break
-
-                # Check in multi-repo subdirectories (specs/XXX-feature-name/)
-                for subdir in workspace.rglob("specs/*/"):
-                    if (subdir / required_file).exists():
-                        found = True
-                        break
-
-                if not found:
-                    error_message = f"❌ {error_msg}"
-                    await self._send_log(error_message)
-                    raise PrerequisiteError(error_msg)
-
-                break  # Only check the first matching command
-
-    async def _initialize_workflow_if_set(self):
-        """Initialize workflow on startup if ACTIVE_WORKFLOW env vars are set."""
-        active_workflow_url = (os.getenv('ACTIVE_WORKFLOW_GIT_URL') or '').strip()
-        if not active_workflow_url:
-            return  # No workflow to initialize
-
-        active_workflow_branch = (os.getenv('ACTIVE_WORKFLOW_BRANCH') or 'main').strip()
-        active_workflow_path = (os.getenv('ACTIVE_WORKFLOW_PATH') or '').strip()
-
-        # Derive workflow name from URL
-        try:
-            owner, repo, _ = self._parse_owner_repo(active_workflow_url)
-            derived_name = repo or ''
-            if not derived_name:
-                p = urlparse(active_workflow_url)
-                parts = [p for p in (p.path or '').split('/') if p]
-                if parts:
-                    derived_name = parts[-1]
-            derived_name = (derived_name or '').removesuffix('.git').strip()
-
-            if not derived_name:
-                logging.warning("Could not derive workflow name from URL, skipping initialization")
-                return
-
-            workflow_dir = Path(self.context.workspace_path) / "workflows" / derived_name
-
-            # Only clone if workflow directory doesn't exist
-            if workflow_dir.exists():
-                logging.info(f"Workflow {derived_name} already exists, skipping initialization")
-                return
-
-            logging.info(f"Initializing workflow {derived_name} from CR spec on startup")
-            # Clone the workflow but don't request restart (we haven't started yet)
-            await self._clone_workflow_repository(active_workflow_url, active_workflow_branch, active_workflow_path, derived_name)
-
-        except Exception as e:
-            logging.error(f"Failed to initialize workflow on startup: {e}")
-            # Don't fail the session if workflow init fails - continue without it
-
-    async def _clone_workflow_repository(self, git_url: str, branch: str, path: str, workflow_name: str):
-        """Clone workflow repository without requesting restart (used during initialization)."""
-        workspace = Path(self.context.workspace_path)
-
-        workflow_dir = workspace / "workflows" / workflow_name
-        temp_clone_dir = workspace / "workflows" / f"{workflow_name}-clone-temp"
-
-        # Check if workflow already exists
-        if workflow_dir.exists():
-            await self._send_log(f"✓ Workflow {workflow_name} already loaded")
-            logging.info(f"Workflow {workflow_name} already exists at {workflow_dir}")
-            return
-
-        # Fetch appropriate token based on repo URL
-        token = await self._fetch_token_for_url(git_url)
-
-        # Clone to temporary directory first
-        await self._send_log(f"📥 Cloning workflow {workflow_name}...")
-        logging.info(f"Cloning workflow from {git_url} (branch: {branch})")
-        clone_url = self._url_with_token(git_url, token) if token else git_url
-        await self._run_cmd(["git", "clone", "--branch", branch, "--single-branch", clone_url, str(temp_clone_dir)], cwd=str(workspace))
-        logging.info(f"Successfully cloned workflow to temp directory")
-
-        # Extract subdirectory if path is specified
-        if path and path.strip():
-            subdir_path = temp_clone_dir / path.strip()
-            if subdir_path.exists() and subdir_path.is_dir():
-                # Copy only the subdirectory contents
-                shutil.copytree(subdir_path, workflow_dir)
-                shutil.rmtree(temp_clone_dir)
-                await self._send_log(f"✓ Extracted workflow from: {path}")
-                logging.info(f"Extracted subdirectory {path} to {workflow_dir}")
-            else:
-                # Path not found, use full repo
-                temp_clone_dir.rename(workflow_dir)
-                await self._send_log(f"⚠️ Path '{path}' not found, using full repository")
-                logging.warning(f"Subdirectory {path} not found, using full repo")
-        else:
-            # No path specified, use entire repo
-            temp_clone_dir.rename(workflow_dir)
-            logging.info(f"Using entire repository as workflow")
-
-        await self._send_log(f"✅ Workflow {workflow_name} ready")
-        logging.info(f"Workflow {workflow_name} setup complete at {workflow_dir}")
-
-    async def _handle_workflow_selection(self, git_url: str, branch: str = "main", path: str = ""):
-        """Clone and setup a workflow repository during an interactive session."""
-        try:
-            # Derive workflow name from URL
-            try:
-                owner, repo, _ = self._parse_owner_repo(git_url)
-                derived_name = repo or ''
-                if not derived_name:
-                    # Fallback: last path segment without .git
-                    p = urlparse(git_url)
-                    parts = [p for p in (p.path or '').split('/') if p]
-                    if parts:
-                        derived_name = parts[-1]
-                derived_name = (derived_name or '').removesuffix('.git').strip()
-            except Exception:
-                derived_name = 'workflow'
-
-            if not derived_name:
-                await self._send_log("❌ Could not derive workflow name from URL")
-                return
-
-            # Clone the workflow repository
-            await self._clone_workflow_repository(git_url, branch, path, derived_name)
-
-            # Set environment variables for the restart
-            os.environ['ACTIVE_WORKFLOW_GIT_URL'] = git_url
-            os.environ['ACTIVE_WORKFLOW_BRANCH'] = branch
-            if path and path.strip():
-                os.environ['ACTIVE_WORKFLOW_PATH'] = path
-
-            # Request restart to switch Claude's working directory
-            self._restart_requested = True
-
-        except Exception as e:
-            logging.error(f"Failed to setup workflow: {e}")
-            await self._send_log(f"❌ Workflow setup failed: {e}")
-
-    async def _handle_repo_added(self, payload):
-        """Clone newly added repository and request restart."""
-        repo_url = str(payload.get('url') or '').strip()
-        repo_branch = str(payload.get('branch') or '').strip() or 'main'
-        repo_name = str(payload.get('name') or '').strip()
-
-        if not repo_url or not repo_name:
-            logging.warning("Invalid repo_added payload")
-            return
-
-        workspace = Path(self.context.workspace_path)
-        repo_dir = workspace / repo_name
-
-        if repo_dir.exists():
-            await self._send_log(f"Repository {repo_name} already exists")
-            return
-
-        # Fetch appropriate token based on repo URL
-        token = await self._fetch_token_for_url(repo_url)
-        clone_url = self._url_with_token(repo_url, token) if token else repo_url
-
-        await self._send_log(f"📥 Cloning {repo_name}...")
-        await self._run_cmd(["git", "clone", "--branch", repo_branch, "--single-branch", clone_url, str(repo_dir)], cwd=str(workspace))
-        
-        # Configure git identity
-        user_name = os.getenv("GIT_USER_NAME", "").strip() or "Ambient Code Bot"
-        user_email = os.getenv("GIT_USER_EMAIL", "").strip() or "bot@ambient-code.local"
-        await self._run_cmd(["git", "config", "user.name", user_name], cwd=str(repo_dir))
-        await self._run_cmd(["git", "config", "user.email", user_email], cwd=str(repo_dir))
-        
-        await self._send_log(f"✅ Repository {repo_name} added")
-
-        # Update REPOS_JSON env var
-        repos_cfg = self._get_repos_config()
-        repos_cfg.append({'name': repo_name, 'input': {'url': repo_url, 'branch': repo_branch}})
-        os.environ['REPOS_JSON'] = _json.dumps(repos_cfg)
-
-        # Request restart to update additional directories
-        self._restart_requested = True
-
-    async def _handle_repo_removed(self, payload):
-        """Remove repository and request restart."""
-        repo_name = str(payload.get('name') or '').strip()
-
-        if not repo_name:
-            logging.warning("Invalid repo_removed payload")
-            return
-
-        workspace = Path(self.context.workspace_path)
-        repo_dir = workspace / repo_name
-
-        if not repo_dir.exists():
-            await self._send_log(f"Repository {repo_name} not found")
-            return
-
-        await self._send_log(f"🗑️ Removing {repo_name}...")
-        shutil.rmtree(repo_dir)
-
-        # Update REPOS_JSON env var
-        repos_cfg = self._get_repos_config()
-        repos_cfg = [r for r in repos_cfg if r.get('name') != repo_name]
-        os.environ['REPOS_JSON'] = _json.dumps(repos_cfg)
-
-        await self._send_log(f"✅ Repository {repo_name} removed")
-
-        # Request restart to update additional directories
-        self._restart_requested = True
-
-    async def _push_results_if_any(self):
-        """Commit and push changes to output repo/branch if configured."""
-        # Get GitHub token once for all repos
-        token = os.getenv("GITHUB_TOKEN") or await self._fetch_github_token()
-        if token:
-            logging.info("GitHub token obtained for push operations")
-        else:
-            logging.warning("No GitHub token available - push may fail for private repos")
-
-        repos_cfg = self._get_repos_config()
-        if repos_cfg:
-            # Multi-repo flow
-            try:
-                for r in repos_cfg:
-                    name = (r.get('name') or '').strip()
-                    if not name:
-                        continue
-                    repo_dir = Path(self.context.workspace_path) / name
-                    status = await self._run_cmd(["git", "status", "--porcelain"], cwd=str(repo_dir), capture_stdout=True)
-                    if not status.strip():
-                        logging.info(f"No changes detected for {name}, skipping push")
-                        continue
-
-                    out = r.get('output') or {}
-                    out_url_raw = (out.get('url') or '').strip()
-                    if not out_url_raw:
-                        logging.warning(f"No output URL configured for {name}, skipping push")
-                        continue
-
-                    # Add token to output URL
-                    out_url = self._url_with_token(out_url_raw, token) if token else out_url_raw
-
-                    in_ = r.get('input') or {}
-                    in_branch = (in_.get('branch') or '').strip()
-                    out_branch = (out.get('branch') or '').strip() or f"sessions/{self.context.session_id}"
-
-                    await self._send_log(f"Pushing changes for {name}...")
-                    logging.info(f"Configuring output remote with authentication for {name}")
-
-                    # Reconfigure output remote with token before push
-                    await self._run_cmd(["git", "remote", "remove", "output"], cwd=str(repo_dir), ignore_errors=True)
-                    await self._run_cmd(["git", "remote", "add", "output", out_url], cwd=str(repo_dir))
-
-                    logging.info(f"Checking out branch {out_branch} for {name}")
-                    await self._run_cmd(["git", "checkout", "-B", out_branch], cwd=str(repo_dir))
-
-                    logging.info(f"Staging all changes for {name}")
-                    await self._run_cmd(["git", "add", "-A"], cwd=str(repo_dir))
-
-                    logging.info(f"Committing changes for {name}")
-                    try:
-                        await self._run_cmd(["git", "commit", "-m", f"Session {self.context.session_id}: update"], cwd=str(repo_dir))
-                    except RuntimeError as e:
-                        if "nothing to commit" in str(e).lower():
-                            logging.info(f"No changes to commit for {name}")
-                            continue
-                        else:
-                            logging.error(f"Commit failed for {name}: {e}")
-                            raise
-
-                    # Verify we have a valid output remote
-                    logging.info(f"Verifying output remote for {name}")
-                    remotes_output = await self._run_cmd(["git", "remote", "-v"], cwd=str(repo_dir), capture_stdout=True)
-                    logging.info(f"Git remotes for {name}:\n{self._redact_secrets(remotes_output)}")
-
-                    if "output" not in remotes_output:
-                        raise RuntimeError(f"Output remote not configured for {name}")
-
-                    logging.info(f"Pushing to output remote: {out_branch} for {name}")
-                    await self._send_log(f"Pushing {name} to {out_branch}...")
-                    await self._run_cmd(["git", "push", "-u", "output", f"HEAD:{out_branch}"], cwd=str(repo_dir))
-
-                    logging.info(f"Push completed for {name}")
-                    await self._send_log(f"✓ Push completed for {name}")
-
-                    create_pr_flag = (os.getenv("CREATE_PR", "").strip().lower() == "true")
-                    if create_pr_flag and in_branch and out_branch and out_branch != in_branch and out_url:
-                        upstream_url = (in_.get('url') or '').strip() or out_url
-                        target_branch = os.getenv("PR_TARGET_BRANCH", "").strip() or in_branch
-                        try:
-                            pr_url = await self._create_pull_request(upstream_repo=upstream_url, fork_repo=out_url, head_branch=out_branch, base_branch=target_branch)
-                            if pr_url:
-                                await self._send_log({"level": "info", "message": f"Pull request created for {name}: {pr_url}"})
-                        except Exception as e:
-                            await self._send_log({"level": "error", "message": f"PR creation failed for {name}: {e}"})
-            except Exception as e:
-                logging.error(f"Failed to push results: {e}")
-                await self._send_log(f"Push failed: {e}")
-            return
-
-        # Single-repo legacy flow
-        output_repo_raw = os.getenv("OUTPUT_REPO_URL", "").strip()
-        if not output_repo_raw:
-            logging.info("No OUTPUT_REPO_URL configured, skipping legacy single-repo push")
-            return
-
-        # Add token to output URL
-        output_repo = self._url_with_token(output_repo_raw, token) if token else output_repo_raw
-
-        output_branch = os.getenv("OUTPUT_BRANCH", "").strip() or f"sessions/{self.context.session_id}"
-        input_repo = os.getenv("INPUT_REPO_URL", "").strip()
-        input_branch = os.getenv("INPUT_BRANCH", "").strip()
-        workspace = Path(self.context.workspace_path)
-        try:
-            status = await self._run_cmd(["git", "status", "--porcelain"], cwd=str(workspace), capture_stdout=True)
-            if not status.strip():
-                await self._send_log({"level": "system", "message": "No changes to push."})
-                return
-
-            await self._send_log("Committing and pushing changes...")
-            logging.info("Configuring output remote with authentication")
-
-            # Reconfigure output remote with token before push
-            await self._run_cmd(["git", "remote", "remove", "output"], cwd=str(workspace), ignore_errors=True)
-            await self._run_cmd(["git", "remote", "add", "output", output_repo], cwd=str(workspace))
-
-            logging.info(f"Checking out branch {output_branch}")
-            await self._run_cmd(["git", "checkout", "-B", output_branch], cwd=str(workspace))
-
-            logging.info("Staging all changes")
-            await self._run_cmd(["git", "add", "-A"], cwd=str(workspace))
-
-            logging.info("Committing changes")
-            try:
-                await self._run_cmd(["git", "commit", "-m", f"Session {self.context.session_id}: update"], cwd=str(workspace))
-            except RuntimeError as e:
-                if "nothing to commit" in str(e).lower():
-                    logging.info("No changes to commit")
-                    await self._send_log({"level": "system", "message": "No new changes to commit."})
-                    return
-                else:
-                    logging.error(f"Commit failed: {e}")
-                    raise
-
-            # Verify we have a valid output remote
-            logging.info("Verifying output remote")
-            remotes_output = await self._run_cmd(["git", "remote", "-v"], cwd=str(workspace), capture_stdout=True)
-            logging.info(f"Git remotes:\n{self._redact_secrets(remotes_output)}")
-
-            if "output" not in remotes_output:
-                raise RuntimeError("Output remote not configured")
-
-            logging.info(f"Pushing to output remote: {output_branch}")
-            await self._send_log(f"Pushing to {output_branch}...")
-            await self._run_cmd(["git", "push", "-u", "output", f"HEAD:{output_branch}"], cwd=str(workspace))
-
-            logging.info("Push completed")
-            await self._send_log("✓ Push completed")
-
-            create_pr_flag = (os.getenv("CREATE_PR", "").strip().lower() == "true")
-            if create_pr_flag and input_branch and output_branch and output_branch != input_branch:
-                target_branch = os.getenv("PR_TARGET_BRANCH", "").strip() or input_branch
-                try:
-                    pr_url = await self._create_pull_request(upstream_repo=input_repo or output_repo, fork_repo=output_repo, head_branch=output_branch, base_branch=target_branch)
-                    if pr_url:
-                        await self._send_log({"level": "info", "message": f"Pull request created: {pr_url}"})
-                except Exception as e:
-                    await self._send_log({"level": "error", "message": f"PR creation failed: {e}"})
-        except Exception as e:
-            logging.error(f"Failed to push results: {e}")
-            await self._send_log(f"Push failed: {e}")
-
-    async def _create_pull_request(self, upstream_repo: str, fork_repo: str, head_branch: str, base_branch: str) -> str | None:
-        """Create a GitHub Pull Request from fork_repo:head_branch into upstream_repo:base_branch.
-
-        Returns the PR HTML URL on success, or None.
-        """
-
-        token = (os.getenv("GITHUB_TOKEN") or await self._fetch_github_token() or "").strip()
-        if not token:
-            raise RuntimeError("Missing token for PR creation")
-
-        up_owner, up_name, up_host = self._parse_owner_repo(upstream_repo)
-        fk_owner, fk_name, fk_host = self._parse_owner_repo(fork_repo)
-        if not up_owner or not up_name or not fk_owner or not fk_name:
-            raise RuntimeError("Invalid repository URLs for PR creation")
-
-        # API base from upstream host
-        api = self._github_api_base(up_host)
-        # For cross-fork PRs, head must be in the form "owner:branch"
-        is_same_repo = (up_owner == fk_owner and up_name == fk_name)
-        head = head_branch if is_same_repo else f"{fk_owner}:{head_branch}"
-
-        url = f"{api}/repos/{up_owner}/{up_name}/pulls"
-        title = f"Changes from session {self.context.session_id[:8]}"
-        body = {
-            "title": title,
-            "body": f"Automated changes from runner session {self.context.session_id}",
-            "head": head,
-            "base": base_branch,
-        }
-
-        # Use blocking urllib in a thread to avoid adding deps
-        data = _json.dumps(body).encode("utf-8")
-        req = _urllib_request.Request(url, data=data, headers={
-            "Accept": "application/vnd.github+json",
-            "Authorization": f"token {token}",
-            "X-GitHub-Api-Version": "2022-11-28",
-            "Content-Type": "application/json",
-            "User-Agent": "vTeam-Runner",
-        }, method="POST")
-
-        loop = asyncio.get_event_loop()
-
-        def _do_req():
-            try:
-                with _urllib_request.urlopen(req, timeout=15) as resp:
-                    return resp.read().decode("utf-8", errors="replace")
-            except _urllib_error.HTTPError as he:
-                err_body = he.read().decode("utf-8", errors="replace")
-                raise RuntimeError(f"GitHub PR create failed: HTTP {he.code}: {err_body}")
-            except Exception as e:
-                raise RuntimeError(str(e))
-
-        resp_text = await loop.run_in_executor(None, _do_req)
-        try:
-            pr = _json.loads(resp_text)
-            return pr.get("html_url") or None
-        except Exception:
-            return None
-
-    def _parse_owner_repo(self, url: str) -> tuple[str, str, str]:
-        """Return (owner, name, host) from various URL formats."""
-        s = (url or "").strip()
-        s = s.removesuffix(".git")
-        host = "github.com"
-        try:
-            if s.startswith("http://") or s.startswith("https://"):
-                p = urlparse(s)
-                host = p.netloc
-                parts = [p for p in p.path.split("/") if p]
-                if len(parts) >= 2:
-                    return parts[0], parts[1], host
-            if s.startswith("git@") or ":" in s:
-                # Normalize SSH like git@host:owner/repo
-                s2 = s
-                if s2.startswith("git@"):
-                    s2 = s2.replace(":", "/", 1)
-                    s2 = s2.replace("git@", "ssh://git@", 1)
-                p = urlparse(s2)
-                host = p.hostname or host
-                parts = [p for p in (p.path or "").split("/") if p]
-                if len(parts) >= 2:
-                    return parts[-2], parts[-1], host
-            # owner/repo
-            parts = [p for p in s.split("/") if p]
-            if len(parts) == 2:
-                return parts[0], parts[1], host
-        except Exception:
-            return "", "", host
-        return "", "", host
-
-    def _github_api_base(self, host: str) -> str:
-        if not host or host == "github.com":
-            return "https://api.github.com"
-        return f"https://{host}/api/v3"
-
-    def _utc_iso(self) -> str:
-        try:
-            from datetime import datetime, timezone
-            return datetime.now(timezone.utc).isoformat()
-        except Exception:
-            return ""
-
-    def _compute_status_url(self) -> str | None:
-        """Compute CR status endpoint from WS URL or env.
-
-        Expected WS path: /api/projects/{project}/sessions/{session}/ws
-        We transform to:  /api/projects/{project}/agentic-sessions/{session}/status
-        """
-        try:
-            ws_url = getattr(self.shell.transport, 'url', None)
-            session_id = self.context.session_id
-            if ws_url:
-                parsed = urlparse(ws_url)
-                scheme = 'https' if parsed.scheme == 'wss' else 'http'
-                parts = [p for p in parsed.path.split('/') if p]
-                # ... api projects <project> sessions <session> ws
-                if 'projects' in parts and 'sessions' in parts:
-                    pi = parts.index('projects')
-                    si = parts.index('sessions')
-                    project = parts[pi+1] if len(parts) > pi+1 else os.getenv('PROJECT_NAME', '')
-                    sess = parts[si+1] if len(parts) > si+1 else session_id
-                    path = f"/api/projects/{project}/agentic-sessions/{sess}/status"
-                    return urlunparse((scheme, parsed.netloc, path, '', '', ''))
-            # Fallback to BACKEND_API_URL and PROJECT_NAME
-            base = os.getenv('BACKEND_API_URL', '').rstrip('/')
-            project = os.getenv('PROJECT_NAME', '').strip()
-            if base and project and session_id:
-                return f"{base}/projects/{project}/agentic-sessions/{session_id}/status"
-        except Exception:
-            return None
-        return None
-
-    async def _update_cr_annotation(self, key: str, value: str):
-        """Update a single annotation on the AgenticSession CR."""
-        status_url = self._compute_status_url()
-        if not status_url:
-            return
-
-        # Transform status URL to patch endpoint
-        try:
-            p = urlparse(status_url)
-            # Remove /status suffix to get base resource URL
-            new_path = p.path.rstrip("/")
-            if new_path.endswith("/status"):
-                new_path = new_path[:-7]
-            url = urlunparse((p.scheme, p.netloc, new_path, '', '', ''))
-
-            # JSON merge patch to update annotations
-            patch = _json.dumps({
-                "metadata": {
-                    "annotations": {
-                        key: value
-                    }
-                }
-            }).encode('utf-8')
-
-            req = _urllib_request.Request(url, data=patch, headers={
-                'Content-Type': 'application/merge-patch+json'
-            }, method='PATCH')
-
-            token = (os.getenv('BOT_TOKEN') or '').strip()
-            if token:
-                req.add_header('Authorization', f'Bearer {token}')
-
-            loop = asyncio.get_event_loop()
-
-            def _do():
-                try:
-                    with _urllib_request.urlopen(req, timeout=10) as resp:
-                        _ = resp.read()
-                    logging.info(f"Annotation {key} updated successfully")
-                    return True
-                except Exception as e:
-                    logging.error(f"Annotation update failed: {e}")
-                    return False
-
-            await loop.run_in_executor(None, _do)
-        except Exception as e:
-            logging.error(f"Failed to update annotation: {e}")
-
-    async def _run_cmd(self, cmd, cwd=None, capture_stdout=False, ignore_errors=False):
-        """Run a subprocess command asynchronously."""
-        # Redact secrets from command for logging
-        cmd_safe = [self._redact_secrets(str(arg)) for arg in cmd]
-        logging.info(f"Running command: {' '.join(cmd_safe)}")
-
-        proc = await asyncio.create_subprocess_exec(
-            *cmd,
-            stdout=asyncio.subprocess.PIPE,
-            stderr=asyncio.subprocess.PIPE,
-            cwd=cwd or self.context.workspace_path,
-        )
-        stdout_data, stderr_data = await proc.communicate()
-        stdout_text = stdout_data.decode("utf-8", errors="replace")
-        stderr_text = stderr_data.decode("utf-8", errors="replace")
-
-        # Log output for debugging (redacted)
-        if stdout_text.strip():
-            logging.info(f"Command stdout: {self._redact_secrets(stdout_text.strip())}")
-        if stderr_text.strip():
-            logging.info(f"Command stderr: {self._redact_secrets(stderr_text.strip())}")
-
-        if proc.returncode != 0 and not ignore_errors:
-            raise RuntimeError(stderr_text or f"Command failed: {' '.join(cmd_safe)}")
-
-        logging.info(f"Command completed with return code: {proc.returncode}")
-
-        if capture_stdout:
-            return stdout_text
-        return ""
-
-    async def _wait_for_ws_connection(self, timeout_seconds: int = 10):
-        """Wait for WebSocket connection to be established before proceeding.
-
-        Retries sending a test message until it succeeds or timeout is reached.
-        This prevents race condition where runner sends messages before WS is connected.
-        """
-        if not self.shell:
-            logging.warning("No shell available - skipping WebSocket wait")
-            return
-
-        start_time = asyncio.get_event_loop().time()
-        attempt = 0
-
-        while True:
-            elapsed = asyncio.get_event_loop().time() - start_time
-            if elapsed > timeout_seconds:
-                logging.error(f"WebSocket connection not established after {timeout_seconds}s - proceeding anyway")
-                return
-
-            try:
-                logging.info(f"WebSocket connection established (attempt {attempt + 1})")
-                return  # Success!
-            except Exception as e:
-                attempt += 1
-                if attempt == 1:
-                    logging.warning(f"WebSocket not ready yet, retrying... ({e})")
-                # Wait 200ms before retry
-                await asyncio.sleep(0.2)
-
-    async def _send_log(self, payload):
-        """Send a system-level message. Accepts either a string or a dict payload.
-
-        Args:
-            payload: String message or dict with 'message' key
-        """
-        if not self.shell:
-            return
-        text: str
-        if isinstance(payload, str):
-            text = payload
-        elif isinstance(payload, dict):
-            text = str(payload.get("message", ""))
-        else:
-            text = str(payload)
-
-        # Create payload dict
-        message_payload = {
-            "message": text
-        }
-
-        await self.shell._send_message(
-            MessageType.SYSTEM_MESSAGE,
-            message_payload,
-        )
-
-    def _url_with_token(self, url: str, token: str) -> str:
-        if not token or not url.lower().startswith("http"):
-            return url
-        try:
-            parsed = urlparse(url)
-            netloc = parsed.netloc
-            if "@" in netloc:
-                netloc = netloc.split("@", 1)[1]
-
-            # Use appropriate auth format based on provider
-            hostname = parsed.hostname or ""
-            if 'gitlab' in hostname.lower():
-                # GitLab uses oauth2 token format
-                auth = f"oauth2:{token}@"
-            else:
-                # GitHub and others use x-access-token format
-                auth = f"x-access-token:{token}@"
-
-            new_netloc = auth + netloc
-            return urlunparse((parsed.scheme, new_netloc, parsed.path,
-                               parsed.params, parsed.query, parsed.fragment))
-        except Exception:
-            return url
-
-    def _redact_secrets(self, text: str) -> str:
-        """Redact tokens and secrets from text for safe logging.
-
-        Protects:
-        - GitHub tokens (ghp_, ghs_, gho_, ghu_)
-        - Anthropic API keys (sk-ant-)
-        - Langfuse keys (pk-lf-, sk-lf-)
-        - URL-embedded credentials
-        - Environment variable assignments
-        """
-        if not text:
-            return text
-
-        # Redact GitHub tokens (ghs_, ghp_, gho_, ghu_ prefixes)
-        text = re.sub(r'gh[pousr]_[a-zA-Z0-9]{36,255}', 'gh*_***REDACTED***', text)
-
-        # Redact Anthropic API keys (sk-ant- prefix, typically ~100 chars)
-        text = re.sub(r'sk-ant-[a-zA-Z0-9\-_]{30,200}', 'sk-ant-***REDACTED***', text)
-
-        # Redact Langfuse public keys (pk-lf- prefix)
-        text = re.sub(r'pk-lf-[a-zA-Z0-9\-_]{10,100}', 'pk-lf-***REDACTED***', text)
-
-        # Redact Langfuse secret keys (sk-lf- prefix)
-        text = re.sub(r'sk-lf-[a-zA-Z0-9\-_]{10,100}', 'sk-lf-***REDACTED***', text)
-
-        # Redact x-access-token: patterns in URLs
-        text = re.sub(r'x-access-token:[^@\s]+@', 'x-access-token:***REDACTED***@', text)
-
-        # Redact oauth tokens in URLs
-        text = re.sub(r'oauth2:[^@\s]+@', 'oauth2:***REDACTED***@', text)
-
-        # Redact basic auth credentials
-        text = re.sub(r'://[^:@\s]+:[^@\s]+@', '://***REDACTED***@', text)
-
-        # Redact environment variable assignments (KEY=value format in logs)
-        # Covers: ANTHROPIC_API_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, etc.
-        text = re.sub(
-            r'(ANTHROPIC_API_KEY|LANGFUSE_SECRET_KEY|LANGFUSE_PUBLIC_KEY|BOT_TOKEN|GIT_TOKEN)\s*=\s*[^\s\'"]+',
-            r'\1=***REDACTED***',
-            text
-        )
-
-        return text
-
-    async def _get_sdk_session_id(self, session_name: str) -> str:
-        """Fetch the SDK session ID (UUID) from the parent session's CR status."""
-        status_url = self._compute_status_url()
-        if not status_url:
-            logging.warning("Cannot fetch SDK session ID: status URL not available")
-            return ""
-
-        try:
-            # Transform status URL to point to parent session
-            p = urlparse(status_url)
-            path_parts = [pt for pt in p.path.split('/') if pt]
-
-            if 'projects' in path_parts and 'agentic-sessions' in path_parts:
-                proj_idx = path_parts.index('projects')
-                project = path_parts[proj_idx + 1] if len(path_parts) > proj_idx + 1 else ''
-                # Point to parent session's status
-                new_path = f"/api/projects/{project}/agentic-sessions/{session_name}"
-                url = urlunparse((p.scheme, p.netloc, new_path, '', '', ''))
-                logging.info(f"Fetching SDK session ID from: {url}")
-            else:
-                logging.error("Could not parse project path from status URL")
-                return ""
-        except Exception as e:
-            logging.error(f"Failed to construct session URL: {e}")
-            return ""
-
-        req = _urllib_request.Request(url, headers={'Content-Type': 'application/json'}, method='GET')
-        bot = (os.getenv('BOT_TOKEN') or '').strip()
-        if bot:
-            req.add_header('Authorization', f'Bearer {bot}')
-
-        loop = asyncio.get_event_loop()
-
-        def _do_req():
-            try:
-                with _urllib_request.urlopen(req, timeout=15) as resp:
-                    return resp.read().decode('utf-8', errors='replace')
-            except _urllib_error.HTTPError as he:
-                logging.warning(f"SDK session ID fetch HTTP {he.code}")
-                return ''
-            except Exception as e:
-                logging.warning(f"SDK session ID fetch failed: {e}")
-                return ''
-
-        resp_text = await loop.run_in_executor(None, _do_req)
-        if not resp_text:
-            return ""
-
-        try:
-            data = _json.loads(resp_text)
-            # Look for SDK session ID in annotations (persists across restarts)
-            metadata = data.get('metadata', {})
-            annotations = metadata.get('annotations', {})
-            sdk_session_id = annotations.get('ambient-code.io/sdk-session-id', '')
-
-            if sdk_session_id:
-                # Validate it's a UUID
-                if '-' in sdk_session_id and len(sdk_session_id) == 36:
-                    logging.info(f"Found SDK session ID in annotations: {sdk_session_id}")
-                    return sdk_session_id
-                else:
-                    logging.warning(f"Invalid SDK session ID format: {sdk_session_id}")
-                    return ""
-            else:
-                logging.warning(f"Parent session {session_name} has no sdk-session-id annotation")
-                return ""
-        except Exception as e:
-            logging.error(f"Failed to parse SDK session ID: {e}")
-            return ""
-
-    async def _fetch_token_for_url(self, url: str) -> str:
-        """Fetch appropriate token based on repository URL.
-
-        Detects the provider (GitHub, GitLab) from the hostname and returns
-        the corresponding token from environment or API.
-        """
-        try:
-            parsed = urlparse(url)
-            hostname = parsed.hostname or ""
-
-            # Check if it's a GitLab instance (gitlab.com or self-hosted)
-            if 'gitlab' in hostname.lower():
-                token = os.getenv("GITLAB_TOKEN", "").strip()
-                if token:
-                    logging.info(f"Using GITLAB_TOKEN for {hostname}")
-                    return token
-                else:
-                    logging.warning(
-                        f"No GITLAB_TOKEN found for GitLab URL: {url}")
-                    return ""
-
-            # Default to GitHub for github.com or unknown hosts
-            token = os.getenv(
-                "GITHUB_TOKEN") or await self._fetch_github_token()
-            if token:
-                logging.info(f"Using GitHub token for {hostname}")
-            return token
-
-        except Exception as e:
-            logging.warning(
-                f"Failed to parse URL {url}: {e}, falling back to GitHub token"
-            )
-            return os.getenv(
-                "GITHUB_TOKEN") or await self._fetch_github_token()
-
-    async def _fetch_github_token(self) -> str:
-        # Try cached value from env first (GITHUB_TOKEN from ambient-non-vertex-integrations)
-        cached = os.getenv("GITHUB_TOKEN", "").strip()
-        if cached:
-            logging.info("Using GITHUB_TOKEN from environment")
-            return cached
-
-        # Build mint URL from status URL if available
-        status_url = self._compute_status_url()
-        if not status_url:
-            logging.warning("Cannot fetch GitHub token: status URL not available")
-            return ""
-
-        try:
-            p = urlparse(status_url)
-            new_path = p.path.rstrip("/")
-            if new_path.endswith("/status"):
-                new_path = new_path[:-7] + "/github/token"
-            else:
-                new_path = new_path + "/github/token"
-            url = urlunparse((p.scheme, p.netloc, new_path, '', '', ''))
-            logging.info(f"Fetching GitHub token from: {url}")
-        except Exception as e:
-            logging.error(f"Failed to construct token URL: {e}")
-            return ""
-
-        req = _urllib_request.Request(url, data=b"{}", headers={'Content-Type': 'application/json'}, method='POST')
-        bot = (os.getenv('BOT_TOKEN') or '').strip()
-        if bot:
-            req.add_header('Authorization', f'Bearer {bot}')
-            logging.debug("Using BOT_TOKEN for authentication")
-        else:
-            logging.warning("No BOT_TOKEN available for token fetch")
-
-        loop = asyncio.get_event_loop()
-
-        def _do_req():
-            try:
-                with _urllib_request.urlopen(req, timeout=10) as resp:
-                    return resp.read().decode('utf-8', errors='replace')
-            except Exception as e:
-                logging.warning(f"GitHub token fetch failed: {e}")
-                return ''
-
-        resp_text = await loop.run_in_executor(None, _do_req)
-        if not resp_text:
-            logging.warning("Empty response from token endpoint")
-            return ""
-
-        try:
-            data = _json.loads(resp_text)
-            token = str(data.get('token') or '')
-            if token:
-                logging.info("Successfully fetched GitHub token from backend")
-            else:
-                logging.warning("Token endpoint returned empty token")
-            return token
-        except Exception as e:
-            logging.error(f"Failed to parse token response: {e}")
-            return ""
-
-    async def _send_partial_output(self, output_chunk: str, *, stream_id: str, index: int):
-        """Send partial assistant output using MESSAGE_PARTIAL with PartialInfo."""
-        if self.shell and output_chunk.strip():
-            partial = PartialInfo(
-                id=stream_id,
-                index=index,
-                total=0,
-                data=output_chunk.strip(),
-            )
-            await self.shell._send_message(
-                MessageType.AGENT_MESSAGE,
-                "",
-                partial=partial,
-            )
-
-    async def _check_pr_intent(self, output: str):
-        """Check if output indicates PR creation intent."""
-        pr_indicators = [
-            "pull request",
-            "PR created",
-            "merge request",
-            "git push",
-            "branch created"
-        ]
-
-        if any(indicator.lower() in output.lower() for indicator in pr_indicators):
-            if self.shell:
-                await self.shell._send_message(
-                    MessageType.SYSTEM_MESSAGE,
-                    "pr.intent",
-                )
-
-    async def handle_message(self, message: dict):
-        """Handle incoming messages from backend."""
-        msg_type = message.get('type', '')
-
-        # Queue interactive messages for processing loop
-        if msg_type in ('user_message', 'interrupt', 'end_session', 'terminate', 'stop', 'workflow_change', 'repo_added', 'repo_removed'):
-            await self._incoming_queue.put(message)
-            logging.debug(f"Queued incoming message: {msg_type}")
-            return
-
-        logging.debug(f"Claude Code adapter received message: {msg_type}")
-
-    def _build_workspace_context_prompt(self, repos_cfg, workflow_name, artifacts_path, ambient_config):
-        """Generate comprehensive system prompt describing workspace layout."""
-
-        prompt = "You are Claude Code working in a structured development workspace.\n\n"
-
-        # Current working directory
-        if workflow_name:
-            prompt += "## Current Workflow\n"
-            prompt += f"Working directory: workflows/{workflow_name}/\n"
-            prompt += "This directory contains workflow logic and automation scripts.\n\n"
-
-        # File uploads directory - PRIORITIZE THIS for user context
-        prompt += "## User-Uploaded Files (IMPORTANT)\n"
-        prompt += "Location: file-uploads/\n"
-        prompt += "Purpose: User-uploaded context files (screenshots, documents, images, PDFs, specs, designs).\n"
-        prompt += "ALWAYS check this directory when starting a new task - it often contains critical context.\n"
-        prompt += "Files here were uploaded by the user via the UI and are available for you to read and reference.\n"
-
-        # List existing files if directory exists
-        file_uploads_path = Path(self.context.workspace_path) / "file-uploads"
-        if file_uploads_path.exists() and file_uploads_path.is_dir():
-            try:
-                files = sorted([f.name for f in file_uploads_path.iterdir() if f.is_file()])
-                if files:
-                    prompt += f"\nCurrently uploaded files ({len(files)}):\n"
-                    for filename in files:
-                        prompt += f"  - {filename}\n"
-                    prompt += "READ THESE FILES if they're relevant to the user's task!\n"
-                else:
-                    prompt += "\nNo files currently uploaded.\n"
-            except Exception as e:
-                logging.warning(f"Failed to list file-uploads directory: {e}")
-                prompt += "\n(Unable to list uploaded files)\n"
-        else:
-            prompt += "\nNo files currently uploaded.\n"
-
-        prompt += "\nCommon use cases:\n"
-        prompt += "  - Screenshots showing UI issues or design mockups\n"
-        prompt += "  - Specification documents and requirements\n"
-        prompt += "  - Reference images or diagrams\n"
-        prompt += "  - Error logs or debug output\n"
-        prompt += "This directory persists across sessions - check it proactively when unclear about task context.\n\n"
-
-        # Artifacts directory
-        prompt += "## Shared Artifacts Directory\n"
-        prompt += f"Location: {artifacts_path}\n"
-        prompt += "Purpose: Create all output artifacts (documents, specs, reports) here.\n"
-        prompt += "This directory persists across workflows and has its own git remote.\n\n"
-
-        # Available repos
-        if repos_cfg:
-            prompt += "## Available Code Repositories\n"
-            for i, repo in enumerate(repos_cfg):
-                name = repo.get('name', f'repo-{i}')
-                prompt += f"- {name}/\n"
-            prompt += "\nThese repositories contain source code you can read or modify.\n"
-            prompt += "Each has its own git configuration and remote.\n\n"
-
-        # Workflow-specific instructions
-        if ambient_config.get("systemPrompt"):
-            prompt += f"## Workflow Instructions\n{ambient_config['systemPrompt']}\n\n"
-
-        prompt += "## Navigation\n"
-        prompt += "All directories are accessible via relative or absolute paths.\n"
-
-        return prompt
-
-    def _get_repos_config(self) -> list[dict]:
-        """Read repos mapping from REPOS_JSON env if present."""
-        try:
-            raw = os.getenv('REPOS_JSON', '').strip()
-            if not raw:
-                return []
-            data = _json.loads(raw)
-            if isinstance(data, list):
-                # normalize names/keys
-                out = []
-                for it in data:
-                    if not isinstance(it, dict):
-                        continue
-                    name = str(it.get('name') or '').strip()
-                    input_obj = it.get('input') or {}
-                    output_obj = it.get('output') or None
-                    url = str((input_obj or {}).get('url') or '').strip()
-                    if not name and url:
-                        # Derive repo folder name from URL if not provided
-                        try:
-                            owner, repo, _ = self._parse_owner_repo(url)
-                            derived = repo or ''
-                            if not derived:
-                                # Fallback: last path segment without .git
-                                p = urlparse(url)
-                                parts = [p for p in (p.path or '').split('/') if p]
-                                if parts:
-                                    derived = parts[-1]
-                            name = (derived or '').removesuffix('.git').strip()
-                        except Exception:
-                            name = ''
-                    if name and isinstance(input_obj, dict) and url:
-                        out.append({'name': name, 'input': input_obj, 'output': output_obj})
-                return out
-        except Exception:
-            return []
-        return []
-
-    def _filter_mcp_servers(self, servers: dict) -> dict:
-        """Filter MCP servers to only allow http and sse types.
-
-        Args:
-            servers: Dictionary of MCP server configurations
-
-        Returns:
-            Filtered dictionary containing only allowed server types
-        """
-        allowed_servers = {}
-        allowed_types = {'http', 'sse'}
-
-        for name, server_config in servers.items():
-            if not isinstance(server_config, dict):
-                logging.warning(f"MCP server '{name}' has invalid configuration format, skipping")
-                continue
-
-            server_type = server_config.get('type', '').lower()
-
-            if server_type in allowed_types:
-                url = server_config.get('url', '')
-                if url:
-                    allowed_servers[name] = server_config
-                    logging.info(f"MCP server '{name}' allowed (type: {server_type}, url: {url})")
-                else:
-                    logging.warning(f"MCP server '{name}' rejected: missing 'url' field")
-            else:
-                logging.warning(f"MCP server '{name}' rejected: type '{server_type}' not allowed")
-
-        return allowed_servers
-
-    def _load_mcp_config(self, cwd_path: str) -> dict | None:
-        """Load MCP server configuration from the ambient runner's .mcp.json file.
-
-        Only loads MCP servers from the centrally-controlled configuration file
-        in the runner's own directory. Does NOT load from user workspace repos
-        for security reasons.
-
-        The .mcp.json file should be located at:
-        /app/claude-runner/.mcp.json (in the container)
-
-        Returns the parsed MCP servers configuration dict, or None if not found.
-        """
-        try:
-            # Only load from the runner's own directory
-            runner_mcp_file = Path("/app/claude-runner/.mcp.json")
-
-            if runner_mcp_file.exists() and runner_mcp_file.is_file():
-                logging.info(f"Loading MCP config from runner directory: {runner_mcp_file}")
-                with open(runner_mcp_file, 'r') as f:
-                    config = _json.load(f)
-                    all_servers = config.get('mcpServers', {})
-                    return all_servers
-            else:
-                logging.info("No .mcp.json file found in runner directory")
-                return None
-
-        except _json.JSONDecodeError as e:
-            logging.error(f"Failed to parse .mcp.json: {e}")
-            return None
-        except Exception as e:
-            logging.error(f"Error loading MCP config: {e}")
-            return None
-
-    def _load_ambient_config(self, cwd_path: str) -> dict:
-        """Load ambient.json configuration from workflow directory.
-        
-        Searches for ambient.json in the .ambient directory relative to the working directory.
-        Returns empty dict if not found (not an error - just use defaults).
-        """
-        try:
-            config_path = Path(cwd_path) / ".ambient" / "ambient.json"
-
-            if not config_path.exists():
-                logging.info(f"No ambient.json found at {config_path}, using defaults")
-                return {}
-
-            with open(config_path, 'r') as f:
-                config = _json.load(f)
-                logging.info(f"Loaded ambient.json: name={config.get('name')}, artifactsDir={config.get('artifactsDir')}")
-                return config
-
-        except _json.JSONDecodeError as e:
-            logging.error(f"Failed to parse ambient.json: {e}")
-            return {}
-        except Exception as e:
-            logging.error(f"Error loading ambient.json: {e}")
-            return {}
-
-
-async def main():
-    """Main entry point for the Claude Code runner wrapper."""
-    # Setup logging
-    logging.basicConfig(
-        level=logging.INFO,
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-    )
-
-    # Get configuration from environment
-    session_id = os.getenv('SESSION_ID', 'test-session')
-    workspace_path = os.getenv('WORKSPACE_PATH', '/workspace')
-    websocket_url = os.getenv('WEBSOCKET_URL', 'ws://backend:8080/session/ws')
-
-    # Ensure workspace exists
-    Path(workspace_path).mkdir(parents=True, exist_ok=True)
-
-    # Create adapter instance
-    adapter = ClaudeCodeAdapter()
-
-    # Create and run shell
-    shell = RunnerShell(
-        session_id=session_id,
-        workspace_path=workspace_path,
-        websocket_url=websocket_url,
-        adapter=adapter,
-    )
-
-    # Link shell to adapter
-    adapter.shell = shell
-
-    try:
-        await shell.start()
-        logging.info("Claude Code runner session completed")
-        return getattr(adapter, "last_exit_code", 0)
-    except KeyboardInterrupt:
-        logging.info("Claude Code runner session interrupted")
-        return 130
-    except Exception as e:
-        logging.error(f"Claude Code runner session failed: {e}")
-        exit_code = getattr(adapter, "last_exit_code", 1)
-        return exit_code or 1
-
-
-if __name__ == '__main__':
-    exit(asyncio.run(main()))
diff --git a/components/runners/runner-shell/README.md b/components/runners/runner-shell/README.md
deleted file mode 100644
index 8944accac..000000000
--- a/components/runners/runner-shell/README.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Runner Shell
-
-Standardized shell framework for AI agent runners in the vTeam platform.
-
-## Architecture
-
-The Runner Shell provides a common framework for different AI agents (Claude, OpenAI, etc.) with standardized:
-
-- **Protocol**: Common message format and types
-- **Transport**: WebSocket communication with backend
-- **Sink**: S3 persistence for message durability
-- **Context**: Session information and utilities
-
-## Components
-
-### Core
-- `shell.py` - Main orchestrator
-- `protocol.py` - Message definitions
-- `transport_ws.py` - WebSocket transport
-- `sink_s3.py` - S3 message persistence
-- `context.py` - Runner context
-
-### Adapters
-- `adapters/claude/` - Claude AI adapter
-
-
-## Usage
-
-```bash
-runner-shell \
-  --session-id sess-123 \
-  --workspace-path /workspace \
-  --websocket-url ws://backend:8080/session/sess-123/ws \
-  --s3-bucket ambient-code-sessions \
-  --adapter claude
-```
-
-## Development
-
-```bash
-# Install in development mode
-pip install -e ".[dev]"
-
-# Format code
-black runner_shell/
-```
-
-## Environment Variables
-
-- `ANTHROPIC_API_KEY` - Claude API key
-- `AWS_ACCESS_KEY_ID` - AWS credentials for S3
-- `AWS_SECRET_ACCESS_KEY` - AWS credentials for S3
\ No newline at end of file
diff --git a/components/runners/runner-shell/__init__.py b/components/runners/runner-shell/__init__.py
deleted file mode 100644
index e69de29bb..000000000
diff --git a/components/runners/runner-shell/pyproject.toml b/components/runners/runner-shell/pyproject.toml
deleted file mode 100644
index fa680270e..000000000
--- a/components/runners/runner-shell/pyproject.toml
+++ /dev/null
@@ -1,35 +0,0 @@
-[project]
-name = "runner-shell"
-version = "0.1.0"
-description = "Standardized runner shell for AI agent sessions"
-requires-python = ">=3.10"
-dependencies = [
-    "websockets>=11.0",
-    "aiobotocore>=2.5.0",
-    "pydantic>=2.0.0",
-    "aiofiles>=23.0.0",
-    "click>=8.1.0",
-    "anthropic>=0.26.0",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=7.0.0",
-    "pytest-asyncio>=0.21.0",
-    "black>=23.0.0",
-    "mypy>=1.0.0",
-]
-
-[project.scripts]
-runner-shell = "runner_shell.cli:main"
-
-[build-system]
-requires = ["setuptools>=61", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[tool.setuptools]
-include-package-data = false
-
-[tool.setuptools.packages.find]
-include = ["runner_shell*"]
-exclude = ["tests*", "adapters*", "core*", "cli*"]
\ No newline at end of file
diff --git a/components/runners/runner-shell/runner_shell/__init__.py b/components/runners/runner-shell/runner_shell/__init__.py
deleted file mode 100644
index 021fdba4d..000000000
--- a/components/runners/runner-shell/runner_shell/__init__.py
+++ /dev/null
@@ -1,5 +0,0 @@
-"""
-Runner Shell - Standardized framework for AI agent runners.
-"""
-
-__version__ = "0.1.0"
\ No newline at end of file
diff --git a/components/runners/runner-shell/runner_shell/core/__init__.py b/components/runners/runner-shell/runner_shell/core/__init__.py
deleted file mode 100644
index 0ee0f21ae..000000000
--- a/components/runners/runner-shell/runner_shell/core/__init__.py
+++ /dev/null
@@ -1,14 +0,0 @@
-"""Core runner shell components."""
-
-from .shell import RunnerShell
-from .protocol import Message, MessageType, SessionStatus, PRIntent
-from .context import RunnerContext
-
-__all__ = [
-    "RunnerShell",
-    "Message",
-    "MessageType",
-    "SessionStatus",
-    "PRIntent",
-    "RunnerContext"
-]
\ No newline at end of file
diff --git a/components/runners/runner-shell/runner_shell/core/protocol.py b/components/runners/runner-shell/runner_shell/core/protocol.py
deleted file mode 100644
index 75d8e9c91..000000000
--- a/components/runners/runner-shell/runner_shell/core/protocol.py
+++ /dev/null
@@ -1,57 +0,0 @@
-"""
-Protocol definitions for runner-backend communication.
-"""
-
-from enum import Enum
-from typing import Dict, Any, Optional, List
-from pydantic import BaseModel, Field
-
-
-class MessageType(str, Enum):
-    """Unified message types for runner communication."""
-
-    SYSTEM_MESSAGE = "system.message"
-    AGENT_MESSAGE = "agent.message"
-    USER_MESSAGE = "user.message"
-    MESSAGE_PARTIAL = "message.partial"
-    AGENT_RUNNING = "agent.running"
-    WAITING_FOR_INPUT = "agent.waiting"
-
-
-class SessionStatus(str, Enum):
-    """Session status values."""
-
-    QUEUED = "queued"
-    RUNNING = "running"
-    SUCCEEDED = "succeeded"
-    FAILED = "failed"
-
-
-class Message(BaseModel):
-    """Standard message format."""
-
-    seq: int = Field(description="Monotonic sequence number")
-    type: MessageType
-    timestamp: str
-    payload: Any
-    partial: Optional["PartialInfo"] = None
-
-
-class PartialInfo(BaseModel):
-    """Information for partial/fragmented messages."""
-
-    id: str = Field(description="Unique ID for this partial set")
-    index: int = Field(description="0-based index of this fragment")
-    total: int = Field(description="Total number of fragments")
-    data: str = Field(description="Fragment data")
-
-
-class PRIntent(BaseModel):
-    """PR creation intent."""
-
-    repo_url: str
-    source_branch: str
-    target_branch: str
-    title: str
-    description: str
-    changes_summary: List[str]
\ No newline at end of file
diff --git a/components/runners/runner-shell/runner_shell/core/shell.py b/components/runners/runner-shell/runner_shell/core/shell.py
deleted file mode 100644
index 58ecc72e3..000000000
--- a/components/runners/runner-shell/runner_shell/core/shell.py
+++ /dev/null
@@ -1,105 +0,0 @@
-"""
-Core shell for managing runner lifecycle and message flow.
-"""
-
-import asyncio
-import json
-from typing import Dict, Any
-from datetime import datetime
-
-from .protocol import Message, MessageType, PartialInfo
-from .transport_ws import WebSocketTransport
-from .context import RunnerContext
-
-
-class RunnerShell:
-    """Core shell that orchestrates runner execution."""
-
-    def __init__(
-        self,
-        session_id: str,
-        workspace_path: str,
-        websocket_url: str,
-        adapter: Any,
-    ):
-        self.session_id = session_id
-        self.workspace_path = workspace_path
-        self.adapter = adapter
-
-        # Initialize components
-        self.transport = WebSocketTransport(websocket_url)
-        self.sink = None
-        self.context = RunnerContext(
-            session_id=session_id,
-            workspace_path=workspace_path,
-        )
-
-        self.running = False
-        self.message_seq = 0
-
-    async def start(self):
-        """Start the runner shell."""
-        self.running = True
-
-        # Connect transport
-        await self.transport.connect()
-        # Forward incoming WS messages to adapter
-        self.transport.set_receive_handler(self.handle_incoming_message)
-
-        # Send session started as a system message
-        await self._send_message(
-            MessageType.SYSTEM_MESSAGE,
-            "session.started"
-        )
-
-        try:
-            # Initialize adapter with context
-            await self.adapter.initialize(self.context)
-
-            # Run adapter main loop
-            result = await self.adapter.run()
-
-            # Send completion as a system message
-            await self._send_message(
-                MessageType.SYSTEM_MESSAGE,
-                "session.completed"
-            )
-
-        except Exception as e:
-            # Send error as a system message
-            await self._send_message(
-                MessageType.SYSTEM_MESSAGE,
-                "session.failed"
-            )
-            raise
-        finally:
-            await self.stop()
-
-    async def stop(self):
-        """Stop the runner shell."""
-        self.running = False
-        await self.transport.disconnect()
-        # No-op; backend handles persistence
-
-    async def _send_message(self, msg_type: MessageType, payload: Dict[str, Any], partial: PartialInfo | None = None):
-        """Send a message through transport and persist to sink."""
-        self.message_seq += 1
-
-        message = Message(
-            seq=self.message_seq,
-            type=msg_type,
-            timestamp=datetime.utcnow().isoformat(),
-            payload=payload,
-            partial=partial,
-        )
-
-        # Send via transport
-        await self.transport.send(message.dict())
-
-        # No-op persistence; messages are persisted by backend
-
-    async def handle_incoming_message(self, message: Dict[str, Any]):
-        """Handle messages from backend."""
-        # Forward to adapter if it has a handler
-        if hasattr(self.adapter, 'handle_message'):
-            await self.adapter.handle_message(message)
\ No newline at end of file
diff --git a/components/runners/runner-shell/runner_shell/core/transport_ws.py b/components/runners/runner-shell/runner_shell/core/transport_ws.py
deleted file mode 100644
index 8c0053bf6..000000000
--- a/components/runners/runner-shell/runner_shell/core/transport_ws.py
+++ /dev/null
@@ -1,153 +0,0 @@
-"""
-WebSocket transport for bidirectional communication with backend.
-"""
-
-import asyncio
-import json
-import logging
-import os
-from typing import Optional, Dict, Any, Callable
-
-import websockets
-from websockets.client import WebSocketClientProtocol
-
-
-logger = logging.getLogger(__name__)
-
-
-class WebSocketTransport:
-    """WebSocket transport implementation."""
-
-    def __init__(self, url: str, reconnect_interval: int = 5):
-        self.url = url
-        self.reconnect_interval = reconnect_interval
-        self.websocket: Optional[WebSocketClientProtocol] = None
-        self.running = False
-        self.receive_handler: Optional[Callable] = None
-        self._recv_task: Optional[asyncio.Task] = None
-
-    async def connect(self):
-        """Connect to WebSocket endpoint."""
-        try:
-            # Forward Authorization header if BOT_TOKEN (runner SA token) is present
-            headers: Dict[str, str] = {}
-            token = (os.getenv("BOT_TOKEN") or "").strip()
-            if token:
-                headers["Authorization"] = f"Bearer {token}"
-
-            # Some websockets versions use `extra_headers`, others use `additional_headers`.
-            # Pass headers as list of tuples for broad compatibility.
-            header_items = [(k, v) for k, v in headers.items()]
-            # Disable client-side keepalive pings (ping_interval=None)
-            # Backend already sends pings every 30s, client pings cause timeouts during long Claude operations
-            try:
-                self.websocket = await websockets.connect(
-                    self.url,
-                    extra_headers=header_items,
-                    ping_interval=None  # Disable automatic keepalive, rely on backend pings
-                )
-            except TypeError:
-                # Fallback for newer versions
-                self.websocket = await websockets.connect(
-                    self.url,
-                    additional_headers=header_items,
-                    ping_interval=None  # Disable automatic keepalive, rely on backend pings
-                )
-            self.running = True
-            # Redact token from URL for logging
-            safe_url = self.url.split('?token=')[0] if '?token=' in self.url else self.url
-            logger.info(f"Connected to WebSocket: {safe_url}")
-
-            # Start receive loop only once
-            if self._recv_task is None or self._recv_task.done():
-                self._recv_task = asyncio.create_task(self._receive_loop())
-
-        except websockets.exceptions.InvalidStatusCode as e:
-            status = getattr(e, "status_code", None)
-            logger.error(
-                f"Failed to connect to WebSocket: HTTP {status if status is not None else 'unknown'}"
-            )
-            # Surface a clearer hint when auth is likely missing
-            if status == 401:
-                has_token = bool((os.getenv("BOT_TOKEN") or "").strip())
-                if not has_token:
-                    logger.error(
-                        "No BOT_TOKEN present; backend project routes require Authorization."
-                    )
-            raise
-        except Exception as e:
-            logger.error(f"Failed to connect to WebSocket: {e}")
-            raise
-
-    async def disconnect(self):
-        """Disconnect from WebSocket."""
-        self.running = False
-        if self.websocket:
-            await self.websocket.close()
-            self.websocket = None
-        # Cancel receive loop if running
-        if self._recv_task and not self._recv_task.done():
-            self._recv_task.cancel()
-            try:
-                await self._recv_task
-            except Exception:
-                pass
-            finally:
-                self._recv_task = None
-
-    async def send(self, message: Dict[str, Any]):
-        """Send message through WebSocket."""
-        if not self.websocket:
-            raise RuntimeError("WebSocket not connected")
-
-        try:
-            data = json.dumps(message)
-            await self.websocket.send(data)
-            logger.debug(f"Sent message: {message.get('type')}")
-
-        except Exception as e:
-            logger.error(f"Failed to send message: {e}")
-            raise
-
-    async def _receive_loop(self):
-        """Receive messages from WebSocket."""
-        while self.running:
-            try:
-                if not self.websocket:
-                    await asyncio.sleep(self.reconnect_interval)
-                    continue
-
-                message = await self.websocket.recv()
-                data = json.loads(message)
-                logger.debug(f"Received message: {data.get('type')}")
-
-                if self.receive_handler:
-                    await self.receive_handler(data)
-
-            except websockets.exceptions.ConnectionClosed:
-                logger.warning("WebSocket connection closed")
-                await self._reconnect()
-
-            except Exception as e:
-                logger.error(f"Error in receive loop: {e}")
-
-    async def _reconnect(self):
-        """Attempt to reconnect to WebSocket."""
-        if not self.running:
-            return
-
-        logger.info("Attempting to reconnect...")
-        self.websocket = None
-
-        while self.running:
-            try:
-                # Re-establish connection; guarded against spawning a second recv loop
-                await self.connect()
-                break
-            except Exception as e:
-                logger.error(f"Reconnection failed: {e}")
-                await asyncio.sleep(self.reconnect_interval)
-
-    def set_receive_handler(self, handler: Callable):
-        """Set handler for received messages."""
-        self.receive_handler = handler
diff --git a/docs/build-metadata.md b/docs/build-metadata.md
new file mode 100644
index 000000000..d7cabda0f
--- /dev/null
+++ b/docs/build-metadata.md
@@ -0,0 +1,297 @@
+# Build Metadata System
+
+This document explains the build metadata system that embeds git and build information into container images and logs it at runtime.
+
+## Overview
+
+Every container image built from this repository includes metadata about:
+- **Git Commit**: Full commit hash and version
+- **Git Branch**: Branch name the image was built from
+- **Git Repository**: Remote repository URL
+- **Git Status**: Whether there were uncommitted changes (`-dirty` suffix)
+- **Build Date**: ISO 8601 timestamp of when the image was built
+- **Build User**: Username and hostname of the builder
+
+This information is logged to the console when each component starts up, making it easy to:
+- Verify which version is running in production
+- Track down which commit introduced a bug
+- Identify if an image was built from a clean state or had local modifications
+- Audit who built production images and when
+
+## How It Works
+
+### 1. Build Time: Makefile Captures Git Metadata
+
+When you run `make build-all` or any build target, the Makefile captures git information:
+
+```makefile
+GIT_COMMIT := $(shell git rev-parse HEAD 2>/dev/null || echo "unknown")
+GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+GIT_REPO := $(shell git remote get-url origin 2>/dev/null || echo "local")
+GIT_DIRTY := $(shell git diff --quiet 2>/dev/null || echo "-dirty")
+GIT_VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+BUILD_DATE := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
+BUILD_USER := $(shell whoami)@$(shell hostname)
+```
+
+These values are passed to the container engine as build arguments:
+
+```bash
+podman build \
+  --build-arg GIT_COMMIT=abc123... \
+  --build-arg GIT_BRANCH=main \
+  --build-arg GIT_REPO=https://github.com/... \
+  --build-arg GIT_VERSION=v1.2.3-dirty \
+  --build-arg BUILD_DATE=2025-12-15T10:30:00Z \
+  --build-arg BUILD_USER=gkrumbac@MacBook \
+  -t vteam-backend:latest .
+```
+
+### 2. Build Time: Dockerfiles Embed Metadata as Environment Variables
+
+Each Dockerfile declares build arguments and sets them as environment variables:
+
+```dockerfile
+# Build arguments
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+ARG GIT_REPO=unknown
+ARG GIT_VERSION=unknown
+ARG BUILD_DATE=unknown
+ARG BUILD_USER=unknown
+
+# ... build stages ...
+
+# Final stage - set as environment variables
+ENV GIT_COMMIT=${GIT_COMMIT}
+ENV GIT_BRANCH=${GIT_BRANCH}
+ENV GIT_REPO=${GIT_REPO}
+ENV GIT_VERSION=${GIT_VERSION}
+ENV BUILD_DATE=${BUILD_DATE}
+ENV BUILD_USER=${BUILD_USER}
+```
+
+**Note**: For multi-stage builds, you must redeclare ARG in each stage where you need to use them.
+
+### 3. Runtime: Components Log Metadata on Startup
+
+Each component reads these environment variables and logs them when starting:
+
+**Backend (Go):**
+```go
+func logBuildInfo() {
+    log.Println("==============================================")
+    log.Println("Backend API - Build Information")
+    log.Println("==============================================")
+    log.Printf("Version:     %s", getEnvOrDefault("GIT_VERSION", "unknown"))
+    log.Printf("Commit:      %s", getEnvOrDefault("GIT_COMMIT", "unknown"))
+    log.Printf("Branch:      %s", getEnvOrDefault("GIT_BRANCH", "unknown"))
+    log.Printf("Repository:  %s", getEnvOrDefault("GIT_REPO", "unknown"))
+    log.Printf("Built:       %s", getEnvOrDefault("BUILD_DATE", "unknown"))
+    log.Printf("Built by:    %s", getEnvOrDefault("BUILD_USER", "unknown"))
+    log.Println("==============================================")
+}
+```
+
+**Frontend (TypeScript):**
+```typescript
+// src/instrumentation.ts - runs once on server startup
+export function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    console.log('==============================================');
+    console.log('Frontend - Build Information');
+    console.log('==============================================');
+    console.log(`Version:     ${process.env.NEXT_PUBLIC_GIT_VERSION || 'unknown'}`);
+    console.log(`Commit:      ${process.env.NEXT_PUBLIC_GIT_COMMIT || 'unknown'}`);
+    // ...
+  }
+}
+```
+
+**Runner (Python):**
+```python
+def log_build_info():
+    """Log build metadata information."""
+    logging.info("=" * 46)
+    logging.info("Claude Code Runner - Build Information")
+    logging.info("=" * 46)
+    logging.info(f"Version:     {os.getenv('GIT_VERSION', 'unknown')}")
+    logging.info(f"Commit:      {os.getenv('GIT_COMMIT', 'unknown')}")
+    # ...
+```
+
+## Example Output
+
+When you start any component, you'll see output like:
+
+```
+==============================================
+Backend API - Build Information
+==============================================
+Version:     v1.2.3-dirty
+Commit:      abc123def456789...
+Branch:      feature/build-metadata
+Repository:  https://github.com/ambient-code/vteam.git
+Built:       2025-12-15T10:30:45Z
+Built by:    gkrumbac@MacBook-Pro.local
+==============================================
+```
+
+The `-dirty` suffix in the version indicates there were uncommitted changes when the image was built.
+
+## Viewing Build Metadata
+
+### In Kubernetes/OpenShift Logs
+
+```bash
+# Backend logs
+oc logs deployment/backend-api -n ambient-code | head -20
+
+# Frontend logs
+oc logs deployment/frontend -n ambient-code | head -20
+
+# Operator logs
+oc logs deployment/agentic-operator -n ambient-code | head -20
+
+# Runner job logs
+oc logs job/session-abc123 -n project-namespace | head -20
+```
+
+### Inspecting Container Environment Variables
+
+```bash
+# Using podman/docker
+podman run --rm vteam-backend:latest env | grep GIT
+
+# In Kubernetes
+kubectl exec deployment/backend-api -n ambient-code -- env | grep GIT
+```
+
+### Checking Image Labels (optional enhancement)
+
+You can also add this metadata as image labels for inspection without running the container:
+
+```bash
+podman inspect vteam-backend:latest | jq '.[0].Config.Labels'
+```
+
+## Development Workflow
+
+### Clean Builds
+
+To ensure no cache is used and base images are pulled fresh:
+
+```bash
+make build-all BUILD_FLAGS='--no-cache --pull'
+```
+
+Or use the VS Code task: **Build All (Podman)** which now includes these flags by default.
+
+### Checking if Your Changes Are Reflected
+
+After building and deploying:
+
+1. Check the build output shows current git info:
+   ```
+   Building backend...
+   Git: feature/my-change@abc123-dirty
+   ```
+
+2. Restart the deployment to see new logs:
+   ```bash
+   oc rollout restart deployment/backend-api -n ambient-code
+   oc logs -f deployment/backend-api -n ambient-code
+   ```
+
+3. Verify the logged commit matches your current commit:
+   ```bash
+   git rev-parse --short HEAD
+   ```
+
+### Local vs Clean Builds
+
+- **Local builds** (`-dirty` suffix): Built with uncommitted changes
+- **CI builds** (clean): Built from committed code in GitHub Actions
+- **Production images**: Should always be clean (no `-dirty` suffix)
+
+## CI/CD Integration
+
+The GitHub Actions workflow (`.github/workflows/components-build-deploy.yml`) automatically:
+
+1. Captures git metadata from the commit being built
+2. Passes build arguments to image builds
+3. Pushes images to `quay.io/ambient_code` with full metadata
+4. Tags images with git commit SHA for traceability
+
+Production images are always built from clean commits, so they never have a `-dirty` suffix.
+
+## Troubleshooting
+
+### Build metadata shows "unknown"
+
+**Cause**: Git commands failed during build (not in a git repository, or git not installed)
+
+**Solution**:
+- Ensure you're building from within the git repository
+- Check that git is installed: `git --version`
+- Verify `.git` directory exists in the project root
+
+### Version shows "-dirty" but I committed all changes
+
+**Cause**: There are untracked files or ignored files that were modified
+
+**Check**:
+```bash
+git status
+git diff --quiet && echo "clean" || echo "dirty"
+```
+
+**Solution**: Commit or stash all changes before building production images
+
+### Frontend build metadata not showing
+
+**Cause**: Next.js instrumentation not enabled or not using `NEXT_PUBLIC_` prefix
+
+**Verify**:
+1. `next.config.js` has `instrumentationHook: true`
+2. Environment variables use `NEXT_PUBLIC_` prefix in Dockerfile
+3. Frontend was rebuilt after changes
+
+### Build metadata different between components
+
+**Cause**: Components were built at different times or from different commits
+
+**Solution**: Always build all components together:
+```bash
+make build-all
+```
+
+## Best Practices
+
+1. **Always commit before building production images** to avoid `-dirty` suffix
+2. **Use `make build-all`** to ensure all components have matching metadata
+3. **Check logs after deployment** to verify correct version is running
+4. **Include commit SHA in incident reports** for faster debugging
+5. **Tag production releases** so version shows `v1.2.3` instead of commit hash
+
+## Related Files
+
+- `Makefile` - Captures git metadata and passes to builds
+- `components/*/Dockerfile` - Declares ARGs and sets ENVs
+- `components/backend/main.go` - Backend logging
+- `components/operator/main.go` - Operator logging
+- `components/frontend/src/instrumentation.ts` - Frontend logging
+- `components/runners/claude-code-runner/wrapper.py` - Runner logging
+- `.vscode/tasks.json` - VS Code build tasks with `--no-cache --pull`
+
+## Future Enhancements
+
+Potential improvements to the build metadata system:
+
+- **Image labels**: Add metadata as OCI image labels for inspection without running
+- **API endpoint**: Expose `/version` endpoint returning JSON with all metadata
+- **UI display**: Show build version in frontend footer or settings page
+- **Sentry integration**: Include version in error reports for better tracking
+- **Metrics tags**: Tag Prometheus metrics with git version for correlation
+- **Deployment annotations**: Add metadata to Kubernetes deployment annotations
+