[FEATURE] Expose metadata field in TaskGet results

Summary

The Task system supports storing arbitrary metadata in tasks, but the TaskGet tool does not expose this metadata in its results. This makes metadata-driven development workflows require reading JSON files directly, which is less ergonomic than using the Task tools.

Current Behavior

What Gets Stored

When creating a task with metadata:

TaskCreate({
  subject: "Implement user authentication",
  description: "Add JWT-based auth",
  metadata: {
    acceptance_criteria: [...],
    api_spec: {...},
    security_requirements: [...]
  }
})

The metadata is correctly stored in ~/.claude/tasks/<session-id>/1.json.

What Gets Retrieved

TaskGet result:

Task #1: Implement user authentication
Status: pending
Description: Add JWT-based auth

The metadata field is not included in the result.

Problem

To access task metadata, Claude must:

1. Use TaskGet to see basic task info
2. Realize metadata is needed
3. Use the Read tool to directly read the JSON file at ~/.claude/tasks/<session-id>/1.json
4. Parse the metadata field from the file

This breaks the abstraction of the Task API and makes specification-driven development more cumbersome.

Proposed Enhancement

Update TaskGet to include metadata in its results:

Current return format:

Task #1: Implement user authentication
Status: pending
Description: Add JWT-based auth

Proposed return format:

Task #1: Implement user authentication
Status: pending
Description: Add JWT-based auth
Metadata: {
  "priority": "high",
  "acceptance_criteria": [...],
  "api_spec": {...}
}

If a task has no metadata field, it could be omitted or shown as Metadata: (none).

Use Cases

1. Specification-Driven Development

Store complete task specifications in metadata:

{
  "metadata": {
    "acceptance_criteria": [
      {"given": "User on login page", "when": "...", "then": "..."}
    ],
    "api_spec": {
      "endpoint": "/api/v1/users",
      "method": "POST",
      "request_body": {...}
    },
    "security_requirements": [...],
    "test_scenarios": [...]
  }
}

Claude can then read the full specification via TaskGet without needing to read files directly.

2. Project Management

{
  "metadata": {
    "priority": "high",
    "estimate_hours": 4,
    "jira_ticket": "PROJ-123",
    "assigned_to": "backend-team"
  }
}

3. External System Integration

{
  "metadata": {
    "github_issue": "#456",
    "linear_id": "LIN-789",
    "slack_thread": "https://..."
  }
}

Benefits

1. Better API abstraction - Claude doesn't need to bypass the Task API to read files
2. Improved DX - Simpler workflow for metadata-driven development
3. Consistency - All task data accessible through the same API
4. Enables richer tooling - External tools can query metadata via Task API

Workaround (Current)

Currently, Claude must read the task file directly with the Read tool:

1. TaskGet({ taskId: "1" }) 
   → Returns basic info (no metadata)

2. Read("~/.claude/tasks/session-id/1.json")
   → Returns full JSON file content

3. Parse metadata from the file manually

This requires knowing the session ID and file path structure, bypassing the Task API abstraction.

Implementation Notes

• Metadata is already stored correctly in task JSON files
• The tool definitions already accept metadata in TaskCreate and TaskUpdate
• This is purely about exposing existing data in tool results
• TaskGet already returns: subject, description, status, blocks, blockedBy
• Adding metadata would complete the picture

Related

This would complement specification-driven development patterns and make the metadata feature more accessible for cross-session workflows where Claude needs to understand task specifications.