fix: remove DeepPlan injection, rename Task tool to Agent tool (#365)

* fix: remove automatic DeepPlan injection from startup hook

The startup_context hook was injecting an instruction forcing agents
into the DeepPlan workflow whenever they entered plan mode. Remove
the injection, deprecate the corresponding requirement (JOBS-REQ-014.5.1),
and drop the test that enforced it.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add agents/ directory to AGENTS.md project structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: rename Task tool references to Agent tool across codebase

Claude Code renamed the Task tool to Agent tool. Update all references
in source code, tests, specs, docs, skills, schemas, and hooks to use
the new name. Also drop the `name` field from review formatter output
since the Agent tool uses `description` as the primary identifier,
and deprecate REVIEW-REQ-006.3.3a accordingly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use REQUIREMENT REMOVED format and update changelog

- JOBS-REQ-014.5.1: use "REQUIREMENT REMOVED" instead of strikethrough
  per requirement-id-stability convention
- Update deepschema validation to exempt "REQUIREMENT REMOVED" lines
- Add changelog entries for this PR

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address pre-existing review findings across codebase

- wrapper.py: update stale docstring to list all 8 NormalizedEvent values
- quality_gate.py: remove dead QualityGateError class, fix stale comment
- tools.py: DRY — refactor _write_manifest to accept optional jobs param,
  add comment documenting deliberate lack of path-traversal check
- LA-REQ-006.5: fix MAY/MUST contradiction (now both say MUST)
- learning_agents_architecture.md: fix inaccurate sequential processing
  description to match actual parallel behavior in learn/SKILL.md
- deepwork_jobs job.yml: fix "should" typo, add errata_summary output,
  fix MCP prefix to plugin form, fix RFC 2119 double-negative phrasing
- formatter.py: fix ruff double blank line

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): rename MCP server to deepwork-dev in e2e test

The reviewer agent's tool patterns (mcp__deepwork-dev__* and
mcp__plugin_deepwork_deepwork__*) didn't match the CI server named
"deepwork" (mcp__deepwork__*), so the reviewer couldn't call
mark_review_as_passed. Aligns with CLAUDE.md guidance to always use
the deepwork-dev prefix in this repo.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nhorton

.deepwork/learning-agents/consistency-reviewer/topics/mcp-workflow-patterns.md

@@ -68,7 +68,7 @@ steps:
 When the server encounters a concurrent entry, it:
 1. Uses the first step ID as the "current" step
 2. Appends a `**CONCURRENT STEPS**` message to the instructions
-3. Expects the agent to use the Task tool to execute them in parallel
+3. Expects the agent to use the Agent tool to execute them in parallel
 
 **Consistency check**: The `current_entry_index` tracks position in the `step_entries` list (which may contain concurrent groups), not the flat step list.
 

.github/workflows/claude-code-test.yml

@@ -219,9 +219,11 @@ jobs:
           # The plugin (--plugin-dir) provides skills, hooks, and MCP server config.
           # Override the plugin's MCP config to use the bare `deepwork` command
           # (the plugin uses `uvx` which may not resolve the local venv install).
+          # Server is named "deepwork-dev" to match the reviewer agent's tool
+          # patterns (mcp__deepwork-dev__*) — see CLAUDE.md MCP tool naming.
           python3 -c "
           import json
-          mcp = {'mcpServers': {'deepwork': {
+          mcp = {'mcpServers': {'deepwork-dev': {
               'command': 'deepwork',
               'args': ['serve', '--path', '.', '--platform', 'claude']
           }}}
@@ -236,10 +238,10 @@ jobs:
               'permissions': {
                   'allow': [
                       'Bash(*)', 'Read(./**)', 'Edit(./**)', 'Write(./**)', 'Skill(*)',
-                      'mcp__deepwork__get_workflows', 'mcp__deepwork__start_workflow',
-                      'mcp__deepwork__finished_step', 'mcp__deepwork__abort_workflow',
-                      'mcp__deepwork__go_to_step',
-                      'mcp__deepwork__mark_review_as_passed'
+                      'mcp__deepwork-dev__get_workflows', 'mcp__deepwork-dev__start_workflow',
+                      'mcp__deepwork-dev__finished_step', 'mcp__deepwork-dev__abort_workflow',
+                      'mcp__deepwork-dev__go_to_step',
+                      'mcp__deepwork-dev__mark_review_as_passed'
                   ]
               }
           }

AGENTS.md

@@ -216,6 +216,7 @@ deepwork/
 │   ├── claude/           # Claude Code plugin
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── README_REVIEWS.md
+│   │   ├── agents/         # Subagent definitions (e.g., reviewer.md)
 │   │   ├── example_reviews/
 │   │   ├── skills/
 │   │   │   ├── configure_reviews/SKILL.md

CHANGELOG.md

@@ -12,12 +12,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Post-commit review reminder hook now short-circuits when all applicable (non-catch-all) review rules for the committed files are already marked as passed, emitting "No re-review needed" instead of nagging
+- Renamed all "Task tool" references to "Agent tool" across codebase to match Claude Code's current tool naming
+- Review formatter now emits `description`, `subagent_type`, and `prompt` fields (dropped `name` field) to match Agent tool signature
+- Hook wrapper tool mappings updated: `Task`/`task` → `Agent`/`agent`
 
 ### Fixed
 
 - Review instruction files now include a `## Project Root` directive stating the absolute project root so reviewer subagents read files from the correct working tree — fixes spurious findings in git-worktree setups where the subagent's cwd differed from the worktree the commits actually lived in (REVIEW-REQ-005.1.9)
 
 ### Removed
+
+- Removed automatic DeepPlan workflow injection from startup_context.sh hook (no longer forces plan mode into DeepPlan)
+- Deprecated JOBS-REQ-014.5.1 (startup hook DeepPlan trigger) and REVIEW-REQ-006.3.3a (name field in review output)
 ## [0.13.3] - 2026-04-10
 
 ### Added

doc/architecture.md

@@ -872,7 +872,7 @@ Lists all available workflows from `.deepwork/jobs/`.
 
 **Parameters**: None
 
-**Returns**: List of jobs with their workflows, steps, and summaries. Each `WorkflowInfo` includes a `how_to_invoke` field with invocation instructions: when the workflow's `agent` field is set in job.yml, it directs callers to delegate via the Task tool; otherwise, it directs callers to use the `start_workflow` MCP tool directly.
+**Returns**: List of jobs with their workflows, steps, and summaries. Each `WorkflowInfo` includes a `how_to_invoke` field with invocation instructions: when the workflow's `agent` field is set in job.yml, it directs callers to delegate via the Agent tool; otherwise, it directs callers to use the `start_workflow` MCP tool directly.
 
 #### 2. `start_workflow`
 Begins a new workflow session.

doc/job_yml_guidance.md

@@ -82,11 +82,11 @@ Changes how the workflow appears in `get_workflows`. Without `agent`, the respon
 
 > Call `start_workflow` with job_name="X" and workflow_name="Y", then follow the step instructions it returns.
 
-With `agent` set (e.g., `"general-purpose"`), the response tells the caller to spawn a **Task sub-agent** of that type:
+With `agent` set (e.g., `"general-purpose"`), the response tells the caller to spawn a sub-agent of that type:
 
-> Invoke as a Task using subagent_type="general-purpose" with a prompt giving full context and instructions to call `start_workflow`...
+> Invoke as an Agent using subagent_type="general-purpose" with a prompt giving full context and instructions to call `start_workflow`...
 
-If the agent does not have the Task tool available, the instructions fall back to direct invocation.
+If the agent does not have the Agent tool available, the instructions fall back to direct invocation.
 
 Use `agent` for workflows that should execute autonomously without blocking the main conversation.
 

doc/learning_agents_architecture.md

@@ -13,8 +13,8 @@ A sub-agent with a persistent knowledge base that improves over time. Defined in
 
 ### Learning Cycle
 The feedback loop that makes agents improve:
-1. **Use** — Agent is invoked via Task tool during normal work
-2. **Track** — Post-Task hook records the session for later review
+1. **Use** — Agent is invoked via Agent tool during normal work
+2. **Track** — Post-Agent hook records the session for later review
 3. **Identify** — Transcript is reviewed for issues/mistakes
 4. **Investigate** — Root causes are determined from transcript evidence
 5. **Incorporate** — Learnings are folded back into the agent's knowledge base
@@ -250,12 +250,12 @@ After the script runs, the skill prompts the user to describe what the agent is
 Fills in key files in the LearningAgent directory — initial topics and/or learnings if the user provides seed knowledge about the domain.
 
 #### learn
-Runs the full learning cycle on all sessions needing it. The skill takes no arguments — any text after `learn` is ignored. Sessions are processed sequentially (not in parallel) to avoid conflicts when the same agent appears in multiple sessions. Workflow:
-1. Uses `!`find ...`` to inject a list of all paths containing a `needs_learning_as_of_timestamp` file into the prompt
-2. For each such folder, spawns a Task with the `LearningAgentExpert` agent using **Sonnet model** to run the `identify` skill
-3. After identification completes, spawns a Task with the `LearningAgentExpert` to run `investigate-issues` then `incorporate-learnings` in sequence
+Runs the full learning cycle on all sessions needing it. The skill takes no arguments. Workflow:
+1. Uses a script to inject a list of all paths containing a `needs_learning_as_of_timestamp` file into the prompt
+2. Spawns an Agent per session with the `LearningAgentExpert` agent using **Sonnet model** to run the `identify` skill — **all run in parallel**
+3. After identification completes, skips sessions where zero issues were found; for remaining sessions, spawns an Agent per session to run `investigate-issues` then `incorporate-learnings` in sequence — **sessions for different agents run in parallel; sessions for the same agent run serially**
 
-If no pending sessions are found (or the `.deepwork/tmp/agent_sessions/` directory is missing), the skill informs the user and stops. If a sub-skill Task fails for a session, the skill logs the failure, skips that session, continues processing remaining sessions, and does NOT mark `needs_learning_as_of_timestamp` as resolved. On completion, the skill outputs a summary containing total sessions processed, total issues identified, list of agents updated, key learnings per agent, and any skipped sessions with reasons. The `learn` skill itself MUST NOT modify agent files directly — all knowledge base updates are delegated to the sub-skills.
+If no pending sessions are found (or the `.deepwork/tmp/agent_sessions/` directory is missing), the skill informs the user and stops. If a sub-skill Agent fails for a session, the skill logs the failure, skips that session, continues processing remaining sessions, and does NOT mark `needs_learning_as_of_timestamp` as resolved. On completion, the skill outputs a summary containing total sessions processed, total issues identified, list of agents updated, key learnings per agent, and any skipped sessions with reasons. The `learn` skill itself MUST NOT modify agent files directly — all knowledge base updates are delegated to the sub-skills.
 
 #### setup
 Configures project permissions for the LearningAgents plugin. Adds required Bash and file access rules to `.claude/settings.json` so hooks and scripts can run without manual approval.
@@ -324,4 +324,4 @@ Issues are tied to specific transcripts for evidence. Storing them alongside ses
 The `learn` skill spawns identification tasks using the Sonnet model. Transcript review is high-volume, pattern-matching work that doesn't require the most capable model. This keeps learning cycles fast and cost-effective.
 
 ### Why Hidden Skills
-Skills like `identify`, `report-issue`, `investigate-issues`, and `incorporate-learnings` are implementation details of the learning cycle. They're invoked by the `learn` skill via Task delegation, not directly by users. Hiding them keeps the user-facing skill surface clean.
+Skills like `identify`, `report-issue`, `investigate-issues`, and `incorporate-learnings` are implementation details of the learning cycle. They're invoked by the `learn` skill via Agent delegation, not directly by users. Hiding them keeps the user-facing skill surface clean.

doc/mcp_interface.md

@@ -183,7 +183,7 @@ Navigate back to a prior step in the current workflow. Clears all progress from
 
 ### 6. `get_review_instructions`
 
-Run a review of changed files based on `.deepreview` configuration files and DeepSchema-generated synthetic review rules. Returns a list of review tasks to invoke in parallel. Each task has `name`, `description`, `subagent_type`, and `prompt` fields for the Task tool.
+Run a review of changed files based on `.deepreview` configuration files and DeepSchema-generated synthetic review rules. Returns a list of review tasks to invoke in parallel. Each task has `description`, `subagent_type`, and `prompt` fields for the Agent tool.
 
 This tool operates outside the workflow lifecycle — it can be called independently at any time.
 
@@ -402,7 +402,7 @@ The quality gate builds dynamic `ReviewRule` objects from step output review blo
 - **Job context**: The workflow's `common_job_info` (if any)
 - **Step inputs**: Input values from prior steps, with file_path inputs shown as `@path` references
 
-These rules are then processed through the standard DeepWork Reviews pipeline (matched against output files, instruction files written, formatted for the agent platform). The review output directs the agent to launch parallel Task agents for each review.
+These rules are then processed through the standard DeepWork Reviews pipeline (matched against output files, instruction files written, formatted for the agent platform). The review output directs the agent to launch parallel review agents for each review.
 
 ### Review Types
 
@@ -496,7 +496,7 @@ Add to your `.mcp.json`:
 | 2.1.0 | Added `important_note` field to `StartWorkflowResponse` — instructs agents to clarify ambiguous user requests via `AskUserQuestion` when available. |
 | 2.0.0 | **Breaking**: `session_id` is now a required `string` parameter on all mutation tools (`start_workflow`, `finished_step`, `abort_workflow`, `go_to_step`). Added `agent_id` optional parameter for sub-agent scoping — sub-agents get their own isolated workflow stacks. State persistence path changed to `.deepwork/tmp/sessions/<platform>/session-<id>/state.json` (with sub-agent state in `agent_<agent_id>.json`). |
 | 1.9.0 | Added `go_to_step` tool for navigating back to prior steps. Clears all step progress from the target step onward, forcing re-execution of subsequent steps. Supports `session_id` for concurrent workflow safety. |
-| 1.8.0 | Added `how_to_invoke` field to `WorkflowInfo` in `get_workflows` response. Always populated with invocation instructions: when a workflow's `agent` field is set, directs callers to delegate via the Task tool; otherwise, directs callers to use the `start_workflow` MCP tool directly. Also added optional `agent` field to workflow definitions in job.yml. |
+| 1.8.0 | Added `how_to_invoke` field to `WorkflowInfo` in `get_workflows` response. Always populated with invocation instructions: when a workflow's `agent` field is set, directs callers to delegate via the Agent tool; otherwise, directs callers to use the `start_workflow` MCP tool directly. Also added optional `agent` field to workflow definitions in job.yml. |
 | 1.7.0 | Added `mark_review_as_passed` tool for review pass caching. Instruction files now include an "After Review" section with the review ID. Reviews with a `.passed` marker are automatically skipped by `get_review_instructions`. |
 | 1.6.0 | Added `get_configured_reviews` tool for listing configured review rules without running the full pipeline. Supports optional file-based filtering. |
 | 1.5.0 | Added `get_review_instructions` tool (originally named `review`) for running `.deepreview`-based code reviews via MCP. Added `--platform` CLI option to `serve` command. |

learning_agents/agents/learning-agent-expert.md

@@ -21,7 +21,7 @@ You are the meta-expert that operates on LearningAgent files. You understand the
 
 !`cat ${CLAUDE_PLUGIN_ROOT}/doc/learning_log_folder_structure.md`
 
-### Post-Task Reminder
+### Post-Agent Reminder
 
 !`cat ${CLAUDE_PLUGIN_ROOT}/doc/learning_agent_post_task_reminder.md`
 

learning_agents/doc/learning_log_folder_structure.md

@@ -19,13 +19,13 @@ Session-level agent interaction logs are stored in `.deepwork/tmp/agent_sessions
 
 ### conversation_transcript.jsonl
 
-A symlink to the agent's Claude Code transcript, created automatically by the post-Task hook. Points to the subagent transcript at `~/.claude/projects/<project-hash>/<session_id>/subagents/agent-<agent_id>.jsonl`. This allows learning cycle skills to read the transcript directly from the session log folder without needing to search for it via Glob patterns.
+A symlink to the agent's Claude Code transcript, created automatically by the post-Agent hook. Points to the subagent transcript at `~/.claude/projects/<project-hash>/<session_id>/subagents/agent-<agent_id>.jsonl`. This allows learning cycle skills to read the transcript directly from the session log folder without needing to search for it via Glob patterns.
 
-The symlink is only created if the transcript file exists at hook execution time (which it should, since the PostToolUse hook fires after the Task completes).
+The symlink is only created if the transcript file exists at hook execution time (which it should, since the PostToolUse hook fires after the Agent completes).
 
 ### needs_learning_as_of_timestamp
 
-Created automatically by the post-Task hook whenever a LearningAgent is used. The file body contains a single ISO 8601 timestamp indicating when the agent was last invoked. This file serves as a flag: its presence means the session transcript has not yet been processed for learnings.
+Created automatically by the post-Agent hook whenever a LearningAgent is used. The file body contains a single ISO 8601 timestamp indicating when the agent was last invoked. This file serves as a flag: its presence means the session transcript has not yet been processed for learnings.
 
 Deleted by `incorporate_learnings` after all issues in the folder have been processed.
 
@@ -35,19 +35,19 @@ Updated by `incorporate_learnings` after processing issues in this conversation.
 
 ### agent_used
 
-Created automatically by the post-Task hook. Contains the name of the LearningAgent that was used in this session (matching the folder name under `.deepwork/learning-agents/`). This links the session's agent_id back to the LearningAgent definition so learning skills can look up the agent's instructions and knowledge.
+Created automatically by the post-Agent hook. Contains the name of the LearningAgent that was used in this session (matching the folder name under `.deepwork/learning-agents/`). This links the session's agent_id back to the LearningAgent definition so learning skills can look up the agent's instructions and knowledge.
 
 ### *.issue.yml
 
 Issue files created during the `identify` and `report_issue` skills. See `issue_yml_format.md` for the full schema. These files progress through statuses: `identified` → `investigated` → `learned`.
 
 ### conversation_transcript.jsonl
 
-Symlink to the agent's Claude Code transcript, created automatically by the post-Task hook. **THIS IS THE FILE TO READ TO SEE THE CONVERSATION ALL THE OTHER FILES REFER TO.**
+Symlink to the agent's Claude Code transcript, created automatically by the post-Agent hook. **THIS IS THE FILE TO READ TO SEE THE CONVERSATION ALL THE OTHER FILES REFER TO.**
 
 ## Lifecycle
 
-1. **Agent used**: Post-Task hook creates `needs_learning_as_of_timestamp`, `agent_used`, and `conversation_transcript.jsonl` symlink
+1. **Agent used**: Post-Agent hook creates `needs_learning_as_of_timestamp`, `agent_used`, and `conversation_transcript.jsonl` symlink
 2. **Session ends**: Stop hook detects `needs_learning_as_of_timestamp` files and suggests running a learning cycle
 3. **Learning cycle** (`/learning-agents learn`):
    a. `identify` reads transcripts and creates `*.issue.yml` files with status `identified`