catcollect-results

name	cat:collect-results
description	Gather results from completed subagent including commits, metrics, and state updates

Collect Results

Purpose

Extract work products from a completed subagent's worktree, including commit history, code changes, token metrics, and status information. Prepares the subagent's work for integration back into the parent task branch.

When to Use

• Subagent has signaled completion
• Subagent has hit context limits and partial results are needed
• Monitoring indicates subagent is stalled or needs intervention
• Before merging subagent branch to task branch

Workflow

Progress Output (MANDATORY):

Display collection progress using visible feedback symbols:

On collection start:

◆ Collecting results: {subagent-id}...

On successful collection:

✓ Subagent complete: {N}K tokens · {N} commits
  → Files changed: {N}
  → Status: {success|partial|failed}

On collection with issues:

⚠ Subagent complete with concerns: {N}K tokens · {N} commits
  → Compaction events: {N}
  → Discovered issues: {N}

These symbols match the phase-based progress format used in /cat:work.

Steps: Verify completion, Extract commits, Parse metrics, Extract issues, Report to user, Update STATE.md

1. Verify Subagent Completion

Check for completion marker file (fast path, no session parsing):

WORKTREE=".worktrees/${TASK}-sub-${UUID}"
COMPLETION_FILE="${WORKTREE}/.completion.json"

# Check for completion marker (preferred - lightweight)
if [ -f "$COMPLETION_FILE" ]; then
  echo "Subagent completed"
  cat "$COMPLETION_FILE"  # Contains status, tokensUsed, compactionEvents, summary
else
  echo "Subagent not yet complete or marker not written"
fi

Why completion marker? Reading .completion.json (~200 bytes) is far cheaper than parsing the session JSONL file (potentially megabytes of conversation history).

2. Extract Commit History

cd "${WORKTREE}"

# Get commits made by subagent (since branch creation)
git log --oneline origin/HEAD..HEAD

# Get detailed commit info
git log --format="%H %s" origin/HEAD..HEAD > /tmp/subagent-commits.txt

3. Parse Token Metrics

CRITICAL: Token totals must span ALL compaction events.

Session files contain entries BEFORE and AFTER any compaction. The jq command below parses ALL assistant entries regardless of when compaction occurred, providing cumulative totals.

Preferred: Read from completion marker (already computed by subagent):

COMPLETION_FILE="${WORKTREE}/.completion.json"
if [ -f "$COMPLETION_FILE" ]; then
  TOTAL_TOKENS=$(jq -r '.tokensUsed // 0' "$COMPLETION_FILE")
  INPUT_TOKENS=$(jq -r '.inputTokens // 0' "$COMPLETION_FILE")
  OUTPUT_TOKENS=$(jq -r '.outputTokens // 0' "$COMPLETION_FILE")
  COMPACTIONS=$(jq -r '.compactionEvents // 0' "$COMPLETION_FILE")
  STATUS=$(jq -r '.status // "unknown"' "$COMPLETION_FILE")
fi

Fallback: Use token-report skill for accurate context-based metrics:

If .completion.json is missing or has no token data, invoke /cat:token-report which extracts totalTokens from Task tool completions in the session file. This metric represents actual context processed (matching CLI "Done" display) rather than cumulative API response tokens.

SESSION_ID=$(cat "${WORKTREE}/.session_id" 2>/dev/null)
if [ -n "$SESSION_ID" ] && [ ! -f "$COMPLETION_FILE" ]; then
  echo "NOTE: .completion.json missing. Token metrics available via /cat:token-report"
  # The token-report skill extracts totalTokens from toolUseResult in session JSONL
fi

Why totalTokens from toolUseResult? The session file stores Task tool completion results with totalTokens which represents the full context the subagent processed. This matches the CLI "Done (X tool uses · XK tokens · Xm Xs)" display and is the correct metric for monitoring.

4. Extract Discovered Issues

If curiosity was medium or high, the subagent may have noted issues in .completion.json:

COMPLETION_FILE="${WORKTREE}/.completion.json"
ISSUES=$(jq -r '.discoveredIssues // []' "$COMPLETION_FILE")
ISSUE_COUNT=$(echo "$ISSUES" | jq 'length')

if [ "$ISSUE_COUNT" -gt 0 ]; then
  echo "Discovered issues: $ISSUE_COUNT"
  echo "$ISSUES" | jq -r '.[] | "- [\(.severity)] \(.file):\(.line) - \(.description)"'
fi

Issue format in .completion.json:

{
  "discoveredIssues": [
    {
      "file": "src/parser/Lexer.java",
      "line": 142,
      "type": "code-quality",
      "severity": "medium",
      "description": "Duplicate token validation logic could be extracted",
      "benefitCost": 2.5
    }
  ]
}

Important: The main agent handles these issues based on the patience setting (see work.md handle_discovered_issues step). This skill only extracts them.

5. Read Subagent Work Products

cd "${WORKTREE}"

# List modified files
git diff --name-only origin/HEAD..HEAD

# Get full diff for review
git diff origin/HEAD..HEAD > /tmp/subagent-changes.diff

6. Extract Subagent Status

If subagent maintained a STATE.md or status file:

# Read subagent's final state
cat "${WORKTREE}/.claude/cat/tasks/${TASK}/STATE.md"

# Or check for completion report
cat "${WORKTREE}/COMPLETION_REPORT.md" 2>/dev/null

7. MANDATORY: Report Token Metrics to User

CRITICAL (M096): Verify token values before reporting - never estimate or guess.

Before presenting metrics, verify you have ACTUAL measured values:

# Verify .completion.json exists and contains numeric values
if [ -f "$COMPLETION_FILE" ]; then
  TOTAL=$(jq -r '.tokensUsed // 0' "$COMPLETION_FILE")
  if [ "$TOTAL" -gt 0 ]; then
    echo "Token metrics verified from .completion.json"
  else
    echo "WARNING: No token data in .completion.json - parsing session file"
    # Fall back to session file parsing (see step 3)
  fi
fi

# Sanity check: implementation subagents typically use 30K-150K tokens
# If value seems unreasonably low (< 10K for implementation), verify source

Anti-pattern (M096): Presenting token metrics without actually reading them from .completion.json or session file. Claiming "subagent used X tokens" without verification is a measurement bug.

Before updating state, present token metrics to user.

CRITICAL: Output directly WITHOUT code blocks (M125). Markdown **bold** renders correctly when output as plain text, but shows as literal asterisks inside triple-backtick code blocks.

Output format (do NOT wrap in ```):

Subagent Execution Report

Subagent: a1b2c3d4 Task: 1.2-implement-parser Status: success

Token Usage:

• Total tokens: 65,000 (32.5% of 200K context)
• Input tokens: 45,000
• Output tokens: 20,000
• Compaction events: 0
• Execution quality: Good ✓

Work Summary:

• Commits: 5
• Files changed: 12
• Lines: +450 / -120

Discovered Issues: 2 (will be handled by main agent based on patience setting)

Why mandatory: Users cannot observe subagent execution. This report is the only visibility into what happened during subagent execution and whether quality may have degraded.

If compaction events > 0, add warning:

⚠️ CONTEXT COMPACTION DETECTED

The subagent experienced context pressure and may have produced lower quality output.
Consider invoking /cat:decompose-task for similar tasks in the future.

8. Update Parent STATE.md

Record collection results in parent's tracking:

subagents:
  - id: a1b2c3d4
    task: 1.2-implement-parser
    status: collected  # Changed from 'running'
    collected_at: 2026-01-10T15:00:00Z
    results:
      commits: 5
      files_changed: 12
      lines_added: 450
      lines_removed: 120
    metrics:
      total_tokens: 65000
      input_tokens: 45000
      output_tokens: 20000
      compaction_events: 0
    ready_for_merge: true
    reported_to_user: true  # MANDATORY - metrics must be shown to user

9. Prepare for Merge

# Ensure subagent branch is up to date
cd "${WORKTREE}"
git status

# Note any uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "WARNING: Uncommitted changes in subagent worktree"
  git status --short
fi

Examples

Successful Collection

collection_report:
  subagent_id: a1b2c3d4
  task: 1.2-implement-parser
  collection_status: success

  commits:
    - hash: abc123
      message: "feature: implement basic parser structure"
    - hash: def456
      message: "feature: add expression parsing"
    - hash: ghi789
      message: "test: add parser unit tests"

  metrics:
    total_tokens: 65000
    efficiency: 0.89  # commits per 10K tokens
    compactions: 0

  files_summary:
    - src/parser/Parser.java (new)
    - src/parser/ExpressionParser.java (new)
    - test/parser/ParserTest.java (new)

  next_action: ready_for_merge

Partial Collection (Context Limit Hit)

collection_report:
  subagent_id: b2c3d4e5
  task: 1.3-implement-formatter
  collection_status: partial

  reason: context_limit_reached
  compaction_events: 2

  commits:
    - hash: jkl012
      message: "feature: implement basic formatter"
    # Only 1 of 3 planned commits completed

  remaining_work:
    - "Implement indent handling"
    - "Add line wrapping"

  metrics:
    total_tokens: 195000
    efficiency: 0.05  # Low due to compaction overhead

  next_action: decompose_remaining
  recommendation: "Spawn new subagent for remaining work"

Anti-Patterns

Wait for completion before collecting

# ❌ Interrupting active work
collect-results "${SUBAGENT}"  # Still processing!

# ✅ Wait for completion or explicit intervention reason
if is_complete "${SUBAGENT}" || needs_intervention "${SUBAGENT}"; then
  collect-results "${SUBAGENT}"
fi

Handle uncommitted changes before proceeding

# ❌ Proceeding with dirty worktree
collect-results "${SUBAGENT}"
merge-subagent "${SUBAGENT}"

# ✅ Handle uncommitted work
if has_uncommitted_changes "${SUBAGENT}"; then
  echo "WARNING: Uncommitted changes detected"
  # Either commit them or document as lost
fi

Always collect full metrics

# ❌ Only grabbing commits
git log --oneline > results.txt
# Done!

# ✅ Full metrics for learning
collect_commits "${SUBAGENT}"
collect_token_metrics "${SUBAGENT}"
collect_compaction_events "${SUBAGENT}"
update_parent_state "${SUBAGENT}"

Collect cumulative tokens spanning compactions

# ❌ Only counting post-compaction tokens
TOKENS=$(jq -s 'last | .message.usage | .input_tokens + .output_tokens' "${SESSION_FILE}")
# This misses all pre-compaction token usage!

# ✅ Cumulative totals spanning ALL compactions
TOKENS=$(jq -s '[.[] | select(.type == "assistant") | .message.usage |
  (.input_tokens + .output_tokens)] | add' "${SESSION_FILE}")
# Sums ALL entries regardless of compaction events

Why this matters: Token estimates are for the ENTIRE task. If a subagent uses 50K tokens, hits compaction, then uses another 30K tokens, the actual usage is 80K - not 30K. Accurate reporting enables proper estimate validation.

Preserve partial progress from incomplete work

# ❌ Discarding incomplete work
if [ "${STATUS}" != "complete" ]; then
  echo "Incomplete, discarding"
  cleanup_worktree "${SUBAGENT}"
fi

# ✅ Preserve partial progress
if [ "${STATUS}" != "complete" ]; then
  echo "Collecting partial results"
  document_remaining_work "${SUBAGENT}"
  # Results can still be merged
fi

Related Skills

• cat:monitor-subagents - Check if subagent is ready for collection
• cat:merge-subagent - Merge collected results to task branch
• cat:token-report - Detailed analysis of token usage
• cat:decompose-task - Split remaining work after partial collection