docs: document optional todos param for new_task (#6329)

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/architect-mode-prompt.snap

@@ -354,6 +354,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -361,12 +365,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/ask-mode-prompt.snap

@@ -251,6 +251,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -258,12 +262,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/mcp-server-creation-disabled.snap

@@ -354,6 +354,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -361,12 +365,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/mcp-server-creation-enabled.snap

@@ -403,6 +403,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -410,12 +414,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/add-custom-instructions/partial-reads-enabled.snap

@@ -359,6 +359,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -366,12 +370,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/consistent-system-prompt.snap

@@ -354,6 +354,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -361,12 +365,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/with-computer-use-support.snap

@@ -407,6 +407,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -414,12 +418,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/with-diff-enabled-false.snap

@@ -354,6 +354,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -361,12 +365,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/with-diff-enabled-true.snap

@@ -442,6 +442,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -449,12 +453,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/with-diff-enabled-undefined.snap

@@ -354,6 +354,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -361,12 +365,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/with-different-viewport-size.snap

@@ -407,6 +407,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -414,12 +418,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/with-mcp-hub-provided.snap

@@ -403,6 +403,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -410,12 +414,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/__tests__/__snapshots__/system-prompt/with-undefined-mcp-hub.snap

@@ -354,6 +354,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -361,12 +365,25 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
 
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
+
 
 ## update_todo_list
 

src/core/prompts/tools/new-task.ts

@@ -7,6 +7,10 @@ Description: This will let you create a new task instance in the chosen mode usi
 Parameters:
 - mode: (required) The slug of the mode to start the new task in (e.g., "code", "debug", "architect").
 - message: (required) The initial user message or instructions for this new task.
+- todos: (optional) A markdown checklist string to initialize the new task's todo list. Use the same single-level checklist format as update_todo_list. If provided, Task parses this during initialization to create the todoList. If omitted, the task starts without a todoList.
+
+Notes:
+- settings.todoListEnabled only gates prompting behavior (i.e., whether update_todo_list is made available in prompts). Passing todos here does not force prompting if todoListEnabled is disabled.
 
 Usage:
 <new_task>
@@ -14,10 +18,23 @@ Usage:
 <message>Your initial instructions here</message>
 </new_task>
 
-Example:
+Example (without todos):
 <new_task>
 <mode>code</mode>
 <message>Implement a new feature for the application.</message>
 </new_task>
+
+Example (with todos):
+<new_task>
+<mode>code</mode>
+<message>Implement user authentication</message>
+<todos>
+[ ] Set up authentication middleware
+[ ] Create login endpoint
+[ ] Create logout endpoint
+[-] Add session management
+[x] Write tests for authentication
+</todos>
+</new_task>
 `
 }

src/shared/tools.ts

@@ -155,7 +155,7 @@ export interface SwitchModeToolUse extends ToolUse {
 
 export interface NewTaskToolUse extends ToolUse {
 	name: "new_task"
-	params: Partial<Pick<Record<ToolParamName, string>, "mode" | "message">>
+	params: Partial<Pick<Record<ToolParamName, string>, "mode" | "message" | "todos">>
 }
 
 export interface SearchAndReplaceToolUse extends ToolUse {