Feature Request: Add Hook for High-Level Task Completion (`TaskCompletion`)

Title: Feature Request: Add Hook for High-Level Task Completion (TaskCompletion)

Labels: feature-request, enhancement, hooks

Issue

Is your feature request related to a problem? Please describe.

Currently, it's difficult to build reliable automations that trigger after Claude Code completes a high-level, multi-turn task. The existing hooks are too granular and fire based on low-level agentic events rather than the logical completion of a user's overall objective.

For example, if a user prompts, "Implement feature X," there is no deterministic way to know when Claude has finished the entire implementation. This makes it impossible to reliably trigger subsequent actions like updating a Jira ticket, notifying a team, or kicking off a CI pipeline. There's no clear signal for the "commit" or completion stage of the "Explore, plan, code, commit" workflow described in the best practices.

Describe the solution you'd like

I propose the introduction of a new hook, TaskCompletion.

This hook would be triggered when Claude determines that a user-initiated task has been fully completed. This feature aligns perfectly with existing concepts within Claude Code, such as its internal Todo list (changelog v1.0.93) and "plan mode" (changelog v1.0.51). Since Claude already has mechanisms to stay on track and execute multi-step plans, a hook that fires upon the completion of the primary task would be a natural and powerful extension.

The data payload for this hook could include valuable context about the completed task:

{
  "session_id": "abc123...",
  "transcript_path": "/path/to/transcript.jsonl",
  "hook_event_name": "TaskCompletion",
  "task_id": "task-xyz-789", // A unique identifier for the task
  "task_prompt": "Fix the off-by-one error in the pagination logic.", // The initial user prompt
  "status": "success" | "failure" | "partial_completion" | "cancelled",
  "summary": "Fixed the pagination error in 'pagination.js' and added a new test case.", // An optional summary
  "task_plan": [ // Optional: The final plan Claude was executing
    "1. Locate relevant files for pagination.",
    "2. Identify off-by-one error in loop condition.",
    "3. Implement fix.",
    "4. Add a new unit test to cover this edge case."
  ],
  "related_commits": [ // Optional: Any git commits made during the task
    "a1b2c3d4e5f6"
  ],
  "tool_usage_summary": { // Optional: A summary of tools used
      "Bash": 5,
      "Edit": 3,
      "mcp__github__pr_review": 1
  }
}

Describe alternatives you've considered

I have considered using existing hooks, but they are insufficient for this use case:

• SubagentStop: This hook is not a viable solution because it fires for every sub-agent invocation, not just at the end of the entire task. A single user command can easily trigger multiple sub-agents, leading to multiple hook invocations for a single logical task.
• Stop: This hook is also unsuitable. According to the Hooks Reference documentation, it triggers when the main agent has "finished responding," which corresponds to the end of a single agentic turn. While the Stop hook can return {"decision": "block"} to prevent Claude from stopping, using this to check for task completion would require building a complex, stateful script that parses the entire conversation transcript (transcript_path) after every single turn. This is brittle, inefficient, and externalizes the core problem of state tracking, which should be managed internally by Claude Code. The TaskCompletion hook is needed to avoid this exact complexity.

Both of these alternatives operate at the level of individual turns or sub-tasks, not at the level of the user's overall objective.

Use Cases & Additional Context

A TaskCompletion hook would unlock powerful, reliable automation workflows across several key areas:

1. Project Management & Workflow Automation

• Automatic Ticket Lifecycle Management: Automatically transition a Jira, Asana, or Linear ticket from "In Progress" to "In Review" when Claude completes a task, posting its summary as a final comment.
• Developer Time Tracking: Automatically stop a timer in a tool like Harvest or Clockify when a feature is marked as complete, logging the time against the correct project.

2. CI/CD & Deployment Automation

• Triggering Staging Deployments: Upon successful feature implementation, trigger a CI/CD pipeline that builds the new branch and deploys it to a QA environment for immediate testing.
• Automated Hotfix Pipeline: For tasks initiated with "hotfix," a successful completion could trigger an expedited release pipeline, pushing the fix to production after passing tests.

3. Code Quality & Maintenance

• Final Code Quality Gate: After any code change task, trigger a final, comprehensive quality check using tools like SonarQube, linters, and formatters to ensure the final code is clean.
• Code Coverage Validation: After a task to "write tests," automatically run a coverage report and flag the task for review if the coverage threshold is not met.

4. Documentation & Knowledge Management

• Synchronized API Documentation: When a task involving API changes is completed, trigger a script to regenerate the OpenAPI/Swagger specification and publish it to a developer portal.
• Drafting Release Notes: Extract Claude's summary upon feature completion and append it to a DRAFT_RELEASE_NOTES.md file, incrementally building a log of changes.

5. Team Communication & Collaboration

• Team Status Notifications: Post a concise summary of the completed task to a Slack or Teams channel, providing a link to the relevant commit. This is especially useful for long-running, unsupervised tasks.
• Automated Handoffs: After completing a backend API task, automatically ping the designated front-end developer on Slack to let them know the API is ready for integration.

6. Security & Compliance

• Post-Change Security Scans: After code modifications, automatically trigger targeted security scans (e.g., Snyk, CodeQL) on only the changed files or newly introduced dependencies.
• Automated Workflow Verification: When running in unsupervised "Safe YOLO mode" (--dangerously-skip-permissions), this hook could trigger a final verification script (e.g., npm run lint) to confirm no errors remain before committing.

This feature would be a transformative enhancement to Claude Code's hooking system, enabling a new class of robust, end-to-end automations.

Thank you for considering this proposal.