feat: wire full governance telemetry pipeline (#3)

## Summary

Wires the complete governance telemetry pipeline using native ConnectRPC. Authenticates with the user's OIDC token — no client secrets, no client_credentials.

## What this PR does

- **ConnectRPC client** (`internal/backend/`) — uses user's bearer token from `kontext login`. 90 lines, no token management.
- **Session lifecycle** — CreateSession on start, heartbeat every 30s, EndSession on exit
- **Sidecar** — Unix socket server, processes hook events, ingests to backend via ConnectRPC async
- **Hook registration** — generates Claude Code `settings.json` with PreToolUse, PostToolUse, UserPromptSubmit
- **Hook command** — reads stdin, connects to sidecar via `KONTEXT_SOCKET`, writes decision to stdout
- **Wire protocol** — length-prefixed JSON over Unix socket
- **Proto codegen** — generated from [`kontext-dev/proto`](https://github.com/kontext-dev/proto) via `buf generate`

## Auth model

The user's OIDC access token (from `kontext login`, stored in system keyring) is the only credential. No `KONTEXT_CLIENT_ID`, no `KONTEXT_CLIENT_SECRET`, no `client_credentials` grant. The backend verifies the JWT and derives org + user identity.

Credential exchange (`.env.kontext` → provider tokens) uses the existing `POST /oauth2/token` endpoint (RFC 8693), same as the SDK's `requireProvider`. Not part of the ConnectRPC service.

## Blocked by (server-side)

- [ ] **kontext-security/kontext#408** — `AgentService` ConnectRPC endpoint + session endpoints accepting user tokens

## Before merging

- [ ] #408 deployed
- [ ] End-to-end: `kontext start --agent claude` → session in dashboard → events in traces → clean disconnect

## Events

| Event | Source | Purpose |
|---|---|---|
| `session.begin` | CLI lifecycle | Session in dashboard |
| `session.end` | CLI lifecycle | Session disconnected |
| `hook.pre_tool_call` | PreToolUse | Tool call telemetry |
| `hook.post_tool_call` | PostToolUse | Tool result audit |
| `hook.user_prompt` | UserPromptSubmit | Prompt logging |

Closes #2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: tumberger

.gitignore

@@ -1,6 +1,5 @@
 bin/
 dist/
-gen/
 *.exe
 .env.kontext
 kontext

README.md

@@ -9,10 +9,11 @@ kontext start --agent claude
 ```
 
 1. **Authenticates** — loads your identity from the system keyring (set up via `kontext login`)
-2. **Resolves credentials** — reads `.env.kontext`, exchanges placeholders for short-lived tokens via Kontext
-3. **Launches the agent** — spawns Claude Code with credentials injected as env vars
-4. **Enforces policy** — every tool call is evaluated against your org's OpenFGA policy (via a local sidecar)
-5. **Logs everything** — full audit trail streamed to the Kontext backend via gRPC
+2. **Creates a session** — registers with the Kontext backend, visible in the dashboard
+3. **Resolves credentials** — reads `.env.kontext`, exchanges placeholders for short-lived tokens
+4. **Launches the agent** — spawns Claude Code with credentials injected as env vars + governance hooks
+5. **Captures every action** — PreToolUse, PostToolUse, and UserPromptSubmit events streamed to the backend
+6. **Tears down cleanly** — session disconnected, credentials expired, temp files removed
 
 Credentials are ephemeral — scoped to the session, gone when it ends.
 
@@ -33,28 +34,25 @@ go build -o bin/kontext ./cmd/kontext
 ### First-time setup
 
 ```bash
-kontext login
+kontext start --agent claude
 ```
 
-Opens a browser for OIDC authentication. Stores your refresh token in the system keyring (macOS Keychain / Linux secret service). No client IDs or secrets to manage.
+On first run, the CLI handles everything interactively:
+- No session? Opens browser for OIDC login, stores refresh token in system keyring
+- No `.env.kontext`? Prompts for which providers the project needs, writes the file
+- Provider not connected? Opens browser to the Kontext hosted connect flow
 
 ### Declare credentials
 
-Create a `.env.kontext` file in your project:
+The `.env.kontext` file declares what credentials the project needs:
 
 ```
 GITHUB_TOKEN={{kontext:github}}
 STRIPE_KEY={{kontext:stripe}}
 DATABASE_URL={{kontext:postgres/prod-readonly}}
 ```
 
-### Run
-
-```bash
-kontext start --agent claude
-```
-
-The CLI resolves each placeholder, injects the credentials as env vars, and launches Claude Code with governance hooks active.
+Commit this to your repo — the team shares it.
 
 ### Supported agents
 
@@ -69,38 +67,103 @@ The CLI resolves each placeholder, injects the credentials as env vars, and laun
 ```
 kontext start --agent claude
   │
-  ├── Auth: OIDC refresh token from keyring → ephemeral session token
-  ├── Credentials: .env.kontext → ExchangeCredential RPC → env vars
-  ├── Sidecar: Unix socket server for hook ↔ backend communication
-  ├── Agent: spawn claude with injected env + hook config
+  ├── Auth: OIDC refresh token from keyring
+  ├── ConnectRPC: CreateSession → session in dashboard
+  ├── Sidecar: Unix socket server (kontext.sock)
+  │     ├── Heartbeat loop (30s)
+  │     └── Async event ingestion via ConnectRPC
+  ├── Hooks: settings.json → Claude Code --settings
+  ├── Agent: spawn claude with injected env
   │     │
-  │     ├── [PreToolUse]  → hook binary → sidecar → policy eval → allow/deny
-  │     └── [PostToolUse] → hook binary → sidecar → audit log
+  │     ├── [PreToolUse]        → kontext hook → sidecar → ingest
+  │     ├── [PostToolUse]       → kontext hook → sidecar → ingest
+  │     └── [UserPromptSubmit]  → kontext hook → sidecar → ingest
   │
-  └── Backend: bidirectional gRPC stream (ProcessHookEvent, SyncPolicy)
+  └── On exit: EndSession → cleanup
 ```
 
-**Hook handlers** are the compiled `kontext hook` binary — <5ms startup, communicates with the sidecar over a Unix socket. No per-hook HTTP requests.
+### Hook flow (per tool call)
 
-**Policy evaluation** uses OpenFGA tuples cached locally by the sidecar. The backend streams policy updates in real-time via `SyncPolicy`.
+```
+Claude Code fires PreToolUse
+  → spawns: kontext hook --agent claude
+  → hook reads stdin JSON (tool_name, tool_input)
+  → hook connects to sidecar via KONTEXT_SOCKET (Unix socket)
+  → sidecar returns allow/deny immediately
+  → sidecar ingests event to backend asynchronously
+  → hook writes decision JSON to stdout, exits
+  → ~5ms total (Go binary, no runtime startup)
+```
+
+## Telemetry Strategy
+
+The CLI separates **governance telemetry** from **developer observability**. These are distinct concerns with different backends and data models.
+
+### Governance telemetry (built-in)
+
+Session lifecycle and tool call events flow to the Kontext backend. This powers the dashboard — sessions, traces, audit trail.
+
+| Event | Source | When |
+|---|---|---|
+| `session.begin` | CLI lifecycle | Agent launched |
+| `session.end` | CLI lifecycle | Agent exited |
+| `hook.pre_tool_call` | PreToolUse hook | Before every tool execution |
+| `hook.post_tool_call` | PostToolUse hook | After every tool execution |
+| `hook.user_prompt` | UserPromptSubmit hook | User submits a prompt |
+
+Events are streamed to the backend via the ConnectRPC `ProcessHookEvent` bidirectional stream and stored in the `mcp_events` table.
+
+**What governance telemetry captures:**
+- What the agent tried to do (tool name + input)
+- What happened (tool response)
+- Whether it was allowed (policy decision)
+- Who did it (session → user → org attribution)
+- When (timestamps, duration)
+
+**What governance telemetry does NOT capture:**
+- LLM reasoning or thinking
+- Token usage or cost
+- Model parameters
+- Conversation history
+- Response quality
+
+### Developer observability (external, future)
+
+LLM-level observability — generation details, token costs, reasoning traces, conversation history — is a separate concern. It is not part of the governance pipeline.
+
+For this, the CLI will optionally export OpenTelemetry spans to an external backend:
+- **Langfuse** — open-source, has a native Claude Code integration, self-hostable
+- **Dash0** — OTEL-native SaaS, cheap ($0.60/M spans), AI/agent-aware
+
+This is additive — the governance pipeline works independently. OTEL export is planned but not yet implemented.
 
 ## Protocol
 
 Service definitions: [`proto/kontext/agent/v1/agent.proto`](proto/kontext/agent/v1/agent.proto)
 
-Uses [ConnectRPC](https://connectrpc.com/) (gRPC-compatible) for backend communication.
+The CLI communicates with the Kontext backend exclusively via ConnectRPC using the generated stubs. Requires the server-side `AgentService` endpoint ([kontext-dev/kontext#408](https://github.com/kontext-dev/kontext/issues/408)).
+
+### Sidecar wire protocol
+
+Hook handlers communicate with the sidecar over a Unix socket using length-prefixed JSON (4-byte big-endian uint32 + JSON payload):
+
+- `EvaluateRequest` — hook → sidecar: agent, hook_event, tool_name, tool_input, tool_response
+- `EvaluateResult` — sidecar → hook: allowed (bool), reason (string)
 
 ## Development
 
 ```bash
 # Build
 go build -o bin/kontext ./cmd/kontext
 
-# Generate protobuf (requires buf)
+# Generate protobuf (requires buf + plugins)
 buf generate
 
 # Test
 go test ./...
+
+# Link for local use
+ln -sf $(pwd)/bin/kontext ~/.local/bin/kontext
 ```
 
 ## License

cmd/kontext/main.go

@@ -2,13 +2,19 @@ package main
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"net"
 	"os"
+	"time"
 
 	"github.com/spf13/cobra"
 
+	"github.com/kontext-dev/kontext-cli/internal/agent"
 	"github.com/kontext-dev/kontext-cli/internal/auth"
+	"github.com/kontext-dev/kontext-cli/internal/hook"
 	"github.com/kontext-dev/kontext-cli/internal/run"
+	"github.com/kontext-dev/kontext-cli/internal/sidecar"
 
 	// Register agent adapters
 	_ "github.com/kontext-dev/kontext-cli/internal/agent/claude"
@@ -97,17 +103,76 @@ func hookCmd() *cobra.Command {
 		Short:  "Process a hook event (called by the agent, not by users)",
 		Hidden: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			fmt.Fprintln(os.Stderr, "kontext hook (not yet implemented)")
-			// TODO:
-			// 1. Read stdin (hook event JSON)
-			// 2. Connect to sidecar via KONTEXT_SOCKET
-			// 3. Send event, receive decision
-			// 4. Write decision to stdout, exit with appropriate code
-			return nil
+			a, ok := agent.Get(agentName)
+			if !ok {
+				fmt.Fprintf(os.Stderr, "unknown agent: %s\n", agentName)
+				os.Exit(2)
+			}
+
+			socketPath := os.Getenv("KONTEXT_SOCKET")
+			if socketPath == "" {
+				// No sidecar — fail-open
+				hook.Run(a, func(e *agent.HookEvent) (bool, string, error) {
+					return true, "no sidecar", nil
+				})
+				return nil // unreachable
+			}
+
+			hook.Run(a, func(e *agent.HookEvent) (bool, string, error) {
+				return evaluateViaSidecar(socketPath, agentName, e)
+			})
+			return nil // unreachable (hook.Run calls os.Exit)
 		},
 	}
 
 	cmd.Flags().StringVar(&agentName, "agent", "claude", "Agent type")
 
 	return cmd
 }
+
+func evaluateViaSidecar(socketPath, agentName string, e *agent.HookEvent) (bool, string, error) {
+	conn, err := net.DialTimeout("unix", socketPath, 5*time.Second)
+	if err != nil {
+		// Sidecar unreachable — fail-open
+		return true, "sidecar unreachable", nil
+	}
+	defer conn.Close()
+	conn.SetDeadline(time.Now().Add(10 * time.Second))
+
+	req := sidecar.EvaluateRequest{
+		Type:      "evaluate",
+		Agent:     agentName,
+		HookEvent: e.HookEventName,
+		ToolName:  e.ToolName,
+		ToolUseID: e.ToolUseID,
+		CWD:       e.CWD,
+	}
+
+	// Marshal tool input/response to JSON
+	if e.ToolInput != nil {
+		data, _ := marshalJSON(e.ToolInput)
+		req.ToolInput = data
+	}
+	if e.ToolResponse != nil {
+		data, _ := marshalJSON(e.ToolResponse)
+		req.ToolResponse = data
+	}
+
+	if err := sidecar.WriteMessage(conn, req); err != nil {
+		return true, "sidecar write error", nil
+	}
+
+	var result sidecar.EvaluateResult
+	if err := sidecar.ReadMessage(conn, &result); err != nil {
+		return true, "sidecar read error", nil
+	}
+
+	return result.Allowed, result.Reason, nil
+}
+
+func marshalJSON(v any) ([]byte, error) {
+	if v == nil {
+		return nil, nil
+	}
+	return json.Marshal(v)
+}