feat: trustworthy tool summaries, semantic audit, and repetition collapsing

.gitignore

@@ -6,3 +6,4 @@ bin/
 coverage.out
 dist/
 /cc-session
+.claude/

cmd/cc-session/audit.go

@@ -39,13 +39,34 @@ func runAudit(args []string, out io.Writer, errOut io.Writer, store parser.Store
 
 	result := analyzer.ComputeAudit(events)
 
-	for _, catName := range []string{"tool_result_cut", "system_noise", "thinking"} {
-		items := result.Categories[catName]
+	fmt.Fprintln(out, "=== CUT-content histogram (risk-descending) ===")
+	for _, bucket := range analyzer.BucketOrder {
+		items := result.Samples[bucket]
+		if len(items) == 0 {
+			continue
+		}
+		fmt.Fprintf(out, "  %-24s %6s items  %12s chars\n",
+			bucket, analyzer.FormatNumber(len(items)), analyzer.FormatNumber(result.BucketChars[bucket]))
+	}
+
+	fmt.Fprintln(out, "\n=== Failed tool result length (chars) ===")
+	if result.Failures.Count == 0 {
+		fmt.Fprintln(out, "  no failed tool results in this session")
+	} else {
+		f := result.Failures
+		fmt.Fprintf(out, "  count: %s   median: %s   p90: %s   max: %s\n",
+			analyzer.FormatNumber(f.Count), analyzer.FormatNumber(f.Median),
+			analyzer.FormatNumber(f.P90), analyzer.FormatNumber(f.Max))
+	}
+
+	fmt.Fprintln(out, "\n=== Samples ===")
+	for _, bucket := range analyzer.BucketOrder {
+		items := result.Samples[bucket]
 		if len(items) == 0 {
 			continue
 		}
 		shown := sampleCount(*samples, len(items))
-		fmt.Fprintf(out, "=== %s (%d items, showing %d) ===\n", catName, len(items), shown)
+		fmt.Fprintf(out, "=== %s (%d items, showing %d) ===\n", bucket, len(items), shown)
 		for _, item := range items[:shown] {
 			fmt.Fprintf(out, "  %s\n\n", item)
 		}

cmd/cc-session/commands.go

@@ -32,6 +32,12 @@ type command struct {
 	// deprecated "inject" alias. The cheat sheet enforces this by panicking
 	// if a row ever references a hidden command's name.
 	hidden bool
+	// tracksUsage marks commands whose invocations should be recorded to
+	// usage.jsonl. main's dispatch starts tracking (see beginUsageTracking
+	// in usage_cmd.go) before run executes, so a failure anywhere inside
+	// run — including before it resolves a session ID — still produces a
+	// usage entry. Meta commands ("help", "usage" itself) leave this false.
+	tracksUsage bool
 	// run executes the command. reader is the concrete claudecodec.Codec,
 	// which satisfies both session.TranscriptReader and session.HeaderScanner
 	// so one signature covers every cmdXxx regardless of which interface it
@@ -52,46 +58,53 @@ var commands []command
 func init() {
 	commands = []command{
 		{
-			name:    "list",
-			summary: "列出最近的 session",
-			argHint: "list",
-			run:     func(args []string, reader claudecodec.Codec) { cmdList(args, reader) },
+			name:        "list",
+			summary:     "列出最近的 session",
+			argHint:     "list",
+			tracksUsage: true,
+			run:         func(args []string, reader claudecodec.Codec) { cmdList(args, reader) },
 		},
 		{
-			name:    "inherit",
-			summary: "分頁繼承 session 到 context",
-			argHint: "inherit <id>",
-			run:     func(args []string, reader claudecodec.Codec) { cmdInherit(args, reader) },
+			name:        "inherit",
+			summary:     "分頁繼承 session 到 context",
+			argHint:     "inherit <id>",
+			tracksUsage: true,
+			run:         func(args []string, reader claudecodec.Codec) { cmdInherit(args, reader) },
 		},
 		{
-			name:    "read",
-			summary: "完整對話 + tool call 一行摘要",
-			argHint: "read <id>",
-			run:     func(args []string, reader claudecodec.Codec) { cmdRead(args, reader) },
+			name:        "read",
+			summary:     "完整對話 + tool call 一行摘要",
+			argHint:     "read <id>",
+			tracksUsage: true,
+			run:         func(args []string, reader claudecodec.Codec) { cmdRead(args, reader) },
 		},
 		{
-			name:    "context",
-			summary: "精簡注入格式（帶 metadata header）",
-			argHint: "context <id>",
-			run:     func(args []string, reader claudecodec.Codec) { cmdContext(args, reader) },
+			name:        "context",
+			summary:     "精簡注入格式（帶 metadata header）",
+			argHint:     "context <id>",
+			tracksUsage: true,
+			run:         func(args []string, reader claudecodec.Codec) { cmdContext(args, reader) },
 		},
 		{
-			name:    "expand",
-			summary: "展開特定 tool call 完整內容",
-			argHint: "expand <id> <tool-id>",
-			run:     func(args []string, reader claudecodec.Codec) { cmdExpand(args, reader) },
+			name:        "expand",
+			summary:     "展開特定 tool call 完整內容",
+			argHint:     "expand <id> <tool-id>",
+			tracksUsage: true,
+			run:         func(args []string, reader claudecodec.Codec) { cmdExpand(args, reader) },
 		},
 		{
-			name:    "stats",
-			summary: "字元與 token 分佈統計",
-			argHint: "stats <id>",
-			run:     func(args []string, reader claudecodec.Codec) { cmdStats(args, reader) },
+			name:        "stats",
+			summary:     "字元與 token 分佈統計",
+			argHint:     "stats <id>",
+			tracksUsage: true,
+			run:         func(args []string, reader claudecodec.Codec) { cmdStats(args, reader) },
 		},
 		{
-			name:    "audit",
-			summary: "檢視被過濾的內容取樣",
-			argHint: "audit <id>",
-			run:     func(args []string, reader claudecodec.Codec) { cmdAudit(args, reader) },
+			name:        "audit",
+			summary:     "檢視被過濾的內容取樣",
+			argHint:     "audit <id>",
+			tracksUsage: true,
+			run:         func(args []string, reader claudecodec.Codec) { cmdAudit(args, reader) },
 		},
 		{
 			name:    "usage",
@@ -107,15 +120,17 @@ func init() {
 			run: func(args []string, _ claudecodec.Codec) { cmdHelp(args) },
 		},
 		{
-			name:    "benchmark",
-			summary: "掃描近期 session，計算壓縮率與成本比較",
+			name:        "benchmark",
+			summary:     "掃描近期 session，計算壓縮率與成本比較",
+			tracksUsage: true,
 			// No argHint: benchmark is a maintainer/analysis command, not part of
 			// the skill's quick-launch surface.
 			run: func(args []string, reader claudecodec.Codec) { cmdBenchmark(args, reader) },
 		},
 		{
-			name:   "inject",
-			hidden: true,
+			name:        "inject",
+			hidden:      true,
+			tracksUsage: true,
 			run: func(args []string, reader claudecodec.Codec) {
 				fmt.Fprintln(os.Stderr, "cc-session inject 已改名為 cc-session inherit，inject 別名將於未來版本移除，請改用 inherit。")
 				cmdInherit(args, reader)

cmd/cc-session/e2e_test.go

@@ -77,7 +77,7 @@ func TestCLI_WhenSessionExists_ThenListReadContextAndAuditWorkEndToEnd(t *testin
 			name: "audit samples cut tool results",
 			args: []string{"audit", sid, "-n", "5"},
 			want: []string{
-				"=== tool_result_cut (1 items, showing 1) ===",
+				"=== success_output_bash (1 items, showing 1) ===",
 			},
 		},
 		{

cmd/cc-session/expand.go

@@ -29,7 +29,7 @@ func runExpand(args []string, out io.Writer, errOut io.Writer, store parser.Stor
 	if resolved.Path == "" {
 		return fmt.Errorf("transcript not found: %s", resolved.ID)
 	}
-	logUsageAsync("expand", session.ShortID(resolved.ID, 8))
+	logUsageAsync("expand", session.ShortID(resolved.ID, 8), requestedIDs...)
 
 	events, err := reader.ReadAll(resolved.Path)
 	if err != nil {

cmd/cc-session/helpers.go

@@ -11,6 +11,7 @@ import (
 )
 
 func exitOnError(err error) {
+	finalizeUsageLog(err)
 	if err == nil {
 		return
 	}

cmd/cc-session/main.go

@@ -6,6 +6,7 @@ package main
 import (
 	"fmt"
 	"os"
+	"runtime/debug"
 
 	"github.com/Mapleeeeeeeeeee/cc-session-reader/internal/claudecodec"
 	"github.com/Mapleeeeeeeeeee/cc-session-reader/internal/tokens"
@@ -14,6 +15,40 @@ import (
 var version = "dev"
 var commit = "none"
 
+// readBuildInfo is the debug.ReadBuildInfo backend used by resolveVersion. It
+// is a package-level seam so tests can substitute deterministic build info
+// instead of whatever the go test binary itself was built with.
+var readBuildInfo = debug.ReadBuildInfo
+
+// resolveVersion returns version unchanged unless it's still the "dev"
+// placeholder, meaning goreleaser's ldflags -X override (see .goreleaser.yaml)
+// never ran — a plain `go build`/`go install` of this module. In that case it
+// falls back to runtime/debug build info: `go install pkg@version` embeds the
+// module version in info.Main.Version, while a source build embeds the VCS
+// revision in info.Settings. Returns "dev" unchanged if neither is available.
+func resolveVersion(version string) string {
+	if version != "dev" {
+		return version
+	}
+	info, ok := readBuildInfo()
+	if !ok {
+		return version
+	}
+	if info.Main.Version != "" && info.Main.Version != "(devel)" {
+		return info.Main.Version
+	}
+	for _, s := range info.Settings {
+		if s.Key == "vcs.revision" && s.Value != "" {
+			rev := s.Value
+			if len(rev) > 12 {
+				rev = rev[:12]
+			}
+			return "dev+" + rev
+		}
+	}
+	return version
+}
+
 type countTokensFunc func(string) (int, error)
 
 // countTokensFn is the token-counting backend used by runStats. It is a
@@ -37,6 +72,8 @@ func main() {
 		os.Exit(1)
 	}
 
+	version = resolveVersion(version)
+
 	defer waitUsageLog()
 
 	reader := claudecodec.Codec{}
@@ -56,6 +93,9 @@ func main() {
 			printUsage()
 			os.Exit(1)
 		}
+		if cmd.tracksUsage {
+			beginUsageTracking(cmd.name)
+		}
 		cmd.run(os.Args[2:], reader)
 	}
 }