feat(usage): report complete delegated session costs

Session usage undercounted delegation because Claude Code stores each subagent in a separate transcript. Include descendant subagents by default across local, server, PostgreSQL, and DuckDB views while keeping aggregate reports unchanged. The --own-only flag preserves the previous per-transcript view.

Also account for billed Claude web searches and restore the deprecated cost_usd compatibility field so supported backends report consistent costs.

Author: mjacobs

cmd/agentsview/archive_query_backend.go

@@ -12,6 +12,7 @@ import (
 	"go.kenn.io/agentsview/internal/parser"
 	"go.kenn.io/agentsview/internal/pricing"
 	"go.kenn.io/agentsview/internal/pricingrefresh"
+	"go.kenn.io/agentsview/internal/service"
 	"go.kenn.io/agentsview/internal/sync"
 )
 
@@ -34,7 +35,15 @@ type archiveQueryPolicy struct {
 type archiveQueryBackend interface {
 	ActivityReport(context.Context, ActivityReportConfig) (activity.Report, error)
 	DailyUsage(context.Context, dailyUsageQuery) (db.DailyUsageResult, error)
-	SessionUsage(context.Context, string) (*sessionUsageOutput, int, error)
+	SessionUsage(context.Context, sessionUsageQuery) (*sessionUsageOutput, int, error)
+}
+
+// sessionUsageQuery selects the session and the attribution scope for
+// `session usage`. OwnOnly restores the pre-rollup behavior of reporting
+// just the named transcript's own rows.
+type sessionUsageQuery struct {
+	SessionID string
+	OwnOnly   bool
 }
 
 type dailyUsageQuery struct {
@@ -186,9 +195,9 @@ func (b daemonArchiveQueryBackend) DailyUsage(
 
 func (b daemonArchiveQueryBackend) SessionUsage(
 	ctx context.Context,
-	sessionID string,
+	query sessionUsageQuery,
 ) (*sessionUsageOutput, int, error) {
-	return httpSessionUsageData(ctx, b.tr.URL, b.authToken, sessionID)
+	return httpSessionUsageData(ctx, b.tr.URL, b.authToken, query)
 }
 
 type localArchiveQueryBackend struct {
@@ -238,13 +247,13 @@ func localDailyUsageFilter(query dailyUsageQuery) db.UsageFilter {
 
 func (b localArchiveQueryBackend) SessionUsage(
 	ctx context.Context,
-	sessionID string,
+	query sessionUsageQuery,
 ) (*sessionUsageOutput, int, error) {
 	applyCustomPricing(b.database, b.cfg)
 	ensureUsagePricing(b.database, b.offline, b.cfg.CustomModelPricing)
 
 	resolvedID, known := resolveRawSessionID(
-		ctx, b.database, b.cfg.AgentDirs, sessionID,
+		ctx, b.database, b.cfg.AgentDirs, query.SessionID,
 	)
 
 	if known && !b.skipFreshData {
@@ -260,18 +269,29 @@ func (b localArchiveQueryBackend) SessionUsage(
 			fmt.Fprintf(os.Stderr,
 				"warning: sync failed: %v\n", syncErr)
 		}
+		if !query.OwnOnly {
+			syncSubagentTranscripts(ctx, engine, b.database, resolvedID)
+		}
 		// Flush pending debounced signal recomputes before the
 		// usage query reads the session.
 		engine.Close()
 	}
 
-	u, err := b.database.GetSessionUsage(ctx, resolvedID, true)
+	load := func() (*db.SessionUsage, error) {
+		if query.OwnOnly {
+			return b.database.GetSessionUsage(ctx, resolvedID, true)
+		}
+		return service.SessionUsageWithSubagents(
+			ctx, b.database, resolvedID, true)
+	}
+
+	u, err := load()
 	if err != nil {
 		return nil, tokenUseExitErr,
 			fmt.Errorf("querying session usage: %w", err)
 	}
 	if u == nil {
-		fmt.Fprintf(os.Stderr, "session not found: %s\n", sessionID)
+		fmt.Fprintf(os.Stderr, "session not found: %s\n", query.SessionID)
 		return nil, tokenUseExitNotFound, nil
 	}
 	if len(u.UnpricedModels) > 0 && !b.offline {
@@ -283,9 +303,7 @@ func (b localArchiveQueryBackend) SessionUsage(
 			fmt.Fprintf(os.Stderr,
 				"warning: pricing refresh failed: %v\n", refErr)
 		} else if refreshed {
-			if u2, e := b.database.GetSessionUsage(
-				ctx, resolvedID, true,
-			); e == nil && u2 != nil {
+			if u2, e := load(); e == nil && u2 != nil {
 				u = u2
 			}
 		}
@@ -301,6 +319,33 @@ func (b localArchiveQueryBackend) SessionUsage(
 	}, usageExitCode(u), nil
 }
 
+// syncSubagentTranscripts refreshes the subagent transcripts that live
+// beside a session's own file, so a session that just finished reports its
+// subagents' spend instead of whatever was last ingested. SyncSingleSession
+// only knows about the named session's file; the children are separate
+// transcripts under <session>/subagents/ that may not be in the archive
+// yet, so they are synced by path. Sync failures are non-fatal: the query
+// still runs against whatever is already stored.
+func syncSubagentTranscripts(
+	ctx context.Context,
+	engine *sync.Engine,
+	database *db.DB,
+	sessionID string,
+) {
+	sourcePath := database.GetSessionFilePath(sessionID)
+	if sourcePath == "" {
+		sourcePath = engine.FindSourceFile(sessionID)
+	}
+	paths := parser.ClaudeSubagentTranscriptPaths(sourcePath)
+	if len(paths) == 0 {
+		return
+	}
+	if syncErr := engine.SyncPathsContext(ctx, paths); syncErr != nil {
+		fmt.Fprintf(os.Stderr,
+			"warning: subagent sync failed: %v\n", syncErr)
+	}
+}
+
 func closeArchiveQueryBackend(cleanup func()) {
 	if cleanup != nil {
 		cleanup()

cmd/agentsview/archive_query_backend_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"net/http"
+	"os"
 	"path/filepath"
 	"testing"
 	"time"
@@ -12,6 +13,8 @@ import (
 	"go.kenn.io/agentsview/internal/config"
 	"go.kenn.io/agentsview/internal/db"
 	"go.kenn.io/agentsview/internal/dbtest"
+	"go.kenn.io/agentsview/internal/parser"
+	"go.kenn.io/agentsview/internal/testjsonl"
 )
 
 func TestResolveArchiveQueryBackendNoSyncStartsNoSyncDaemon(t *testing.T) {
@@ -109,7 +112,8 @@ func TestLocalArchiveQuerySessionUsageNoSyncSkipsSingleSessionSync(
 	}
 	stderr := captureStderr(t, func() {
 		out, exitCode, err := backend.SessionUsage(
-			context.Background(), "codex:no-sync-usage",
+			context.Background(),
+			sessionUsageQuery{SessionID: "codex:no-sync-usage"},
 		)
 		require.NoError(t, err)
 		require.NotNil(t, out)
@@ -119,3 +123,83 @@ func TestLocalArchiveQuerySessionUsageNoSyncSkipsSingleSessionSync(
 	assert.NotContains(t, stderr, "warning: sync failed")
 	assert.NotContains(t, stderr, "warning: pricing seed failed")
 }
+
+// TestLocalSessionUsageRefreshesSubagentTranscripts covers the freshness
+// half of the subagent rollup: SyncSingleSession only knows about the named
+// session's file, so the backend must also ingest the agent-*.jsonl files
+// beside it. Without that, a session that just finished would report a
+// combined cost missing its most recent subagents.
+func TestLocalSessionUsageRefreshesSubagentTranscripts(t *testing.T) {
+	dataDir := testDataDir(t)
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	for _, def := range parser.Registry {
+		if def.EnvVar != "" {
+			t.Setenv(def.EnvVar,
+				filepath.Join(home, "agent-dirs", string(def.Type)))
+		}
+	}
+	claudeDir := t.TempDir()
+	t.Setenv("CLAUDE_PROJECTS_DIR", claudeDir)
+
+	projDir := filepath.Join(claudeDir, "-home-proj")
+	require.NoError(t, os.MkdirAll(
+		filepath.Join(projDir, "parent-uuid", "subagents"), 0o755))
+	parentPath := filepath.Join(projDir, "parent-uuid.jsonl")
+	require.NoError(t, os.WriteFile(parentPath, []byte(
+		testjsonl.NewSessionBuilder().
+			AddClaudeUser("2026-05-20T10:00:00Z", "delegate this").
+			AddClaudeAssistant("2026-05-20T10:00:05Z", "on it").
+			String(),
+	), 0o644))
+
+	dbPath := sessionsDBPath(dataDir)
+	database := dbtest.OpenTestDBAt(t, dbPath)
+	backend := localArchiveQueryBackend{
+		cfg: config.Config{
+			DBPath: dbPath,
+			AgentDirs: map[parser.AgentType][]string{
+				parser.AgentClaude: {claudeDir},
+			},
+		},
+		database: database,
+		offline:  true,
+	}
+	ctx := context.Background()
+
+	// Ingest the parent, then write a subagent transcript the way Claude
+	// Code does after the parent's own file was last synced.
+	_, _, err := backend.SessionUsage(
+		ctx, sessionUsageQuery{SessionID: "parent-uuid"})
+	require.NoError(t, err)
+
+	require.NoError(t, os.WriteFile(
+		filepath.Join(projDir, "parent-uuid", "subagents",
+			"agent-worker1.jsonl"),
+		[]byte(testjsonl.NewSessionBuilder().
+			AddClaudeUserWithSessionID(
+				"2026-05-20T10:01:00Z", "do the subtask", "parent-uuid").
+			AddClaudeAssistant("2026-05-20T10:01:30Z", "subtask done").
+			String()),
+		0o644))
+
+	out, _, err := backend.SessionUsage(
+		ctx, sessionUsageQuery{SessionID: "parent-uuid"})
+	require.NoError(t, err)
+	require.NotNil(t, out)
+	assert.Equal(t, 1, out.SubagentCount,
+		"the new subagent transcript must be ingested before the query")
+
+	child, err := database.GetSession(ctx, "agent-worker1")
+	require.NoError(t, err)
+	require.NotNil(t, child, "subagent session was not synced")
+	require.NotNil(t, child.ParentSessionID)
+	assert.Equal(t, "parent-uuid", *child.ParentSessionID)
+
+	// --own-only skips the subagent refresh and the combined view.
+	own, _, err := backend.SessionUsage(
+		ctx, sessionUsageQuery{SessionID: "parent-uuid", OwnOnly: true})
+	require.NoError(t, err)
+	require.NotNil(t, own)
+	assert.Zero(t, own.SubagentCount)
+}

cmd/agentsview/session_test.go

@@ -1248,15 +1248,121 @@ func TestSessionUsage_ServerFlagUsesHTTP(t *testing.T) {
 	require.NoError(t, err)
 	require.NotNil(t, out)
 	assert.Equal(t, "/api/v1/sessions/remote-session/usage", reqs.UsagePath)
-	assert.Equal(t, "breakdown=true", reqs.UsageQuery,
-		"remote CLI must request full breakdown rows")
+	assert.Equal(t, "breakdown=true&subagents=true", reqs.UsageQuery,
+		"remote CLI must request full breakdown rows and subagent usage")
 	assert.Equal(t, tokenUseExitOK, code)
 	assert.Equal(t, "remote-session", out.SessionID)
 	assert.Equal(t, "remote-project", out.Project)
 	assert.Equal(t, 42, out.TotalOutputTokens)
 	assert.True(t, out.ServerRunning)
 }
 
+func TestSessionUsage_ServerFlagOwnOnlySkipsSubagents(t *testing.T) {
+	newAgentDataDir(t)
+
+	ts, reqs := newRemoteUsageServer(t, remoteUsageSpec{
+		canonicalID:   "remote-session",
+		serverRunning: true,
+	})
+
+	cmd := sessionUsageCommand(t,
+		"session", "usage", "remote-session", "--server", ts.URL, "--own-only")
+
+	out, code, err := sessionUsageDataForCommand(cmd, "remote-session")
+	require.NoError(t, err)
+	require.NotNil(t, out)
+	assert.Equal(t, "breakdown=true", reqs.UsageQuery,
+		"--own-only must not ask the daemon for subagent usage")
+	assert.Equal(t, tokenUseExitOK, code)
+}
+
+// seedSubagentOnlyUsage seeds a parent session with no usage of its own and
+// one subagent transcript that holds all the token data, which is the shape
+// that used to make `session usage <parent>` exit 3 with an empty report.
+func seedSubagentOnlyUsage(
+	t *testing.T, d *db.DB, parentID, childID string, outputTokens int,
+) {
+	t.Helper()
+	require.NoError(t, d.UpsertSession(db.Session{
+		ID:               parentID,
+		Project:          "local-project",
+		Machine:          "usage-host",
+		Agent:            "claude",
+		MessageCount:     2,
+		UserMessageCount: 2,
+	}))
+	require.NoError(t, d.UpsertSession(db.Session{
+		ID:                   childID,
+		Project:              "local-project",
+		Machine:              "usage-host",
+		Agent:                "claude",
+		MessageCount:         2,
+		ParentSessionID:      &parentID,
+		RelationshipType:     "subagent",
+		TotalOutputTokens:    outputTokens,
+		HasTotalOutputTokens: true,
+	}))
+}
+
+func TestSessionUsage_LocalIncludesSubagentUsageByDefault(t *testing.T) {
+	dataDir := newAgentDataDir(t)
+	t.Setenv("AGENTSVIEW_NO_DAEMON", "1")
+
+	localDB := dbtest.OpenTestDBAt(t, sessionsDBPath(dataDir))
+	seedSubagentOnlyUsage(t, localDB, "claude:parent-only", "agent-child", 24)
+
+	cmd := sessionUsageCommand(t, "session", "usage", "claude:parent-only")
+
+	out, code, err := sessionUsageDataForCommand(cmd, "claude:parent-only")
+	require.NoError(t, err)
+	require.NotNil(t, out)
+	assert.Equal(t, tokenUseExitOK, code,
+		"a parent whose token data lives in subagents must not exit 3")
+	assert.Equal(t, "claude:parent-only", out.SessionID)
+	assert.Equal(t, 1, out.SubagentCount)
+	assert.Equal(t, 24, out.TotalOutputTokens)
+	assert.True(t, out.HasTokenData)
+}
+
+func TestSessionUsage_LocalOwnOnlyExcludesSubagentUsage(t *testing.T) {
+	dataDir := newAgentDataDir(t)
+	t.Setenv("AGENTSVIEW_NO_DAEMON", "1")
+
+	localDB := dbtest.OpenTestDBAt(t, sessionsDBPath(dataDir))
+	seedSubagentOnlyUsage(t, localDB, "claude:parent-only", "agent-child", 24)
+
+	cmd := sessionUsageCommand(t,
+		"session", "usage", "claude:parent-only", "--own-only")
+
+	out, code, err := sessionUsageDataForCommand(cmd, "claude:parent-only")
+	require.NoError(t, err)
+	require.NotNil(t, out)
+	assert.Equal(t, tokenUseExitNoTokenData, code,
+		"--own-only restores the pre-rollup empty report and exit code")
+	assert.Zero(t, out.SubagentCount)
+	assert.Zero(t, out.TotalOutputTokens)
+	assert.False(t, out.HasTokenData)
+}
+
+func TestSessionUsage_PGFlagIncludesSubagentUsage(t *testing.T) {
+	dataDir := newAgentDataDir(t)
+	t.Setenv("AGENTSVIEW_PG_URL", "postgres://example.test/agentsview")
+
+	pgDB := dbtest.OpenTestDBAt(t, filepath.Join(dataDir, "pg.db"))
+	seedSubagentOnlyUsage(t, pgDB, "claude:pg-parent", "agent-pg-child", 42)
+
+	stubPGReadStore(t, pgDB)
+
+	cmd := sessionUsageCommand(t, "session", "usage", "claude:pg-parent", "--pg")
+
+	out, code, err := sessionUsageDataForCommand(cmd, "claude:pg-parent")
+	require.NoError(t, err)
+	require.NotNil(t, out)
+	assert.Equal(t, tokenUseExitOK, code)
+	assert.Equal(t, 1, out.SubagentCount)
+	assert.Equal(t, 42, out.TotalOutputTokens)
+}
+
 func TestSessionUsage_UsesDiscoveredDaemon(t *testing.T) {
 	dataDir := newAgentDataDir(t)