feat(hook): custom trace tags and session grouping via commands

[zerafachris]

feat(hook): custom trace tags via CC_LANGFUSE_TAG_COMMAND

What

Adds two opt-in, related config options for attributing traces to external work items.
Both empty by default — no behavior change for existing users.

• CC_LANGFUSE_TAG_COMMAND — runs a command once per hook run; each non-empty stdout
  line is merged into the trace tags.
• CC_LANGFUSE_SESSION_LABEL_COMMAND + CC_LANGFUSE_SESSION_LABEL_MODE — takes the
  first non-empty stdout line as a label and groups the session's traces under it
  (prefix / collapse / off).

One script can drive both — tags use every line, the label uses the first:

CC_LANGFUSE_TAG_COMMAND='~/bin/langfuse-tags.sh'
CC_LANGFUSE_SESSION_LABEL_COMMAND='~/bin/langfuse-tags.sh'

# ~/bin/langfuse-tags.sh — first line is the story id, the rest are extra tags
b=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) || exit 0
[[ $b =~ [sS][cC]-([0-9]+) ]] && { echo "sc-${BASH_REMATCH[1]}"; echo "layer:build"; }

That tags every trace with sc-<id> + layer:build and groups the session as
sc-<id>/<uuid>.

Why

Today get_trace_tags() returns a fixed set (claude-code + optional skill tags), so any
team wanting to attribute traces to a branch, ticket, CI run, or cost center must fork and
patch the hook. Because the hook is large and evolves fast, such patches silently stop
applying on update — and since the hook fails open, the custom tags just vanish with no
error. This gives those teams a supported, update-safe seam instead.

How

• Tags: collect_custom_tags() runs the command (shell=True), memoized per process;
  one line in get_trace_tags() appends the result and de-dups order-preserving (a
  command may re-emit claude-code).
• Session label: apply_session_label() (called in main()) relabels the session id used
  for the trace. Crucially, the incremental-read state key stays on the raw session id —
  emit_new_turns_from_transcript gains a trace_session_id param, so relabeling groups
  traces without ever re-emitting past turns or requiring a state migration.
• Both share one runner (_run_tag_command) and are fail-open in every direction — no
  command, non-zero exit, timeout, or exception contributes nothing and never interrupts
  tracing.
• Bounded: CC_LANGFUSE_TAG_TIMEOUT (default 2s), max 20 tags, 64 chars per tag/label,
  session id capped at Langfuse's 199-char limit.

Surface

• hooks/langfuse_hook.py: +import subprocess, config constants, _run_tag_command(),
  collect_custom_tags(), resolve_session_label(), apply_session_label(), one line in
  get_trace_tags(), a trace_session_id param threaded through emit_new_turns_from_transcript,
  and the apply_session_label() call in main().
• .claude-plugin/plugin.json: userConfig entries for the four options.
• README: "Custom tags" and "Grouping sessions by a label" sections.
• Tests: 15 cases (below).

Testing

15 tests pass under pytest against the built hook. Tags:

case	result
command emits two tags	['sc-1234','layer:build']
blank lines / whitespace stripped	['sc-9','foo']
no command	[]
non-zero exit → fail-open	[]
timeout → fail-open	[]
100 lines → capped	20 tags
200-char tag → capped	64 chars
command re-emits claude-code → merge+de-dup	['claude-code','sc-77']

Session label:

case	result
prefix (default)	sc-53855/<uuid>
collapse	sc-53855
off	unchanged
no command / empty / non-zero exit	unchanged
250-char label	label capped 64, session ≤ 199
one script feeds both	tags = all lines, label = first line

Note for reviewers

CC_LANGFUSE_TAG_COMMAND executes a user-configured shell string (same trust level as
configuring a hook; empty by default). If you'd rather avoid shell=True, an argv-style
no-shell form is a one-line change — happy to switch. A static CC_LANGFUSE_EXTRA_TAGS
list could also ship alongside for the no-subprocess case; left out here to keep the PR
focused on the dynamic use case that actually needs it.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[zerafachris]

Opt-in and backward-compatible — all four config options default to empty/existing behavior, so nothing changes for current users. Follows the same CC_LANGFUSE_* userConfig pattern as #23.

Ran the full test suite locally against this repo's tests/ harness (the stubbed conftest): 79 passing, including 15 new cases covering the tag command, the session-label modes, fail-open paths, and bounds. Session labeling changes only the trace grouping id — the incremental-read state key stays on the raw session id, so relabeling never re-emits past turns.

@hassiebp @jannikmaierhoefer — would appreciate a look when you have a moment. Happy to adjust the shape (e.g. no-shell argv form, or a static tag list alongside) if you'd prefer.

[atoomic]

@zerafachris you noted in the description that a static CC_LANGFUSE_EXTRA_TAGS could ship
alongside this. I've opened #61 doing exactly that (as CC_LANGFUSE_TAGS, building on #37), plus #62 for the underlying need.

They compose rather than compete: the static form covers the case where the launching process
already knows the labels and can export them, with no subprocess involved; yours covers the
case where they have to be computed at run time. A run could reasonably set both.

One practical heads-up: this PR adds tests/unit/test_custom_tags.py, and so does mine — so whichever lands second will need to merge that file rather than add it. Flagging it now so it's not a surprise at rebase time.