diff --git a/src/mcp_prompts.rs b/src/mcp_prompts.rs index 5e1ac9be..340449d9 100644 --- a/src/mcp_prompts.rs +++ b/src/mcp_prompts.rs @@ -214,6 +214,13 @@ fn get_handoff_command(request: &GetPromptRequestParams, agent: Option<&str>) -> item_id= (so the reply becomes the next asset version instead of a new \ item) and reply_to=, reusing its \ thread_id.\n\ + If the work already lives on some other existing item (not just your \ + own inbox reply), pass that item's id as item_id too — omitting it \ + always creates a new item, even when one covering this work already \ + exists. And if this is just a plain-text status update with no \ + versioned artifact to attach, skip `handoff` entirely: call `comment` \ + (action=create, item_id=) plus `item` (action=update, id=, \ + assignee_agent=) instead — lighter, no new item, no asset.\n\ - `inbox [me]` → call the `item` tool (action=list, state_group=\"backlog,unstarted,started\" \ by default to hide completed/cancelled items — omit state_group only if the command \ explicitly says `all`) — already scoped to this repo's linked project — and filter to \ diff --git a/src/mcp_server.rs b/src/mcp_server.rs index fc916c74..1cf7c631 100644 --- a/src/mcp_server.rs +++ b/src/mcp_server.rs @@ -409,7 +409,7 @@ impl AgentflareMcp { self.artifact_impl(req) } #[tool( - description = "Hand a work product to another agent: assigns/creates an item for the recipient (in the repo's linked project) and attaches the content to it as an asset. Re-attaching under the same item_id creates the next asset version, not a duplicate. Sender is this runtime's own identity." + description = "Hand a work product to another agent: assigns/creates an item for the recipient (in the repo's linked project) and attaches the content to it as an asset. Pass `item_id` to target an existing item instead of creating a new one — omitting it always mints a new item, so if the work already has a home item, pass its id. Re-attaching under the same item_id creates the next asset version, not a duplicate. For a plain-text status update with no versioned artifact to attach, prefer `comment` (action=create) + `item` (action=update, id=, assignee_agent=...) instead of this tool — lighter, no new item, no asset. Sender is this runtime's own identity." )] fn handoff(&self, Parameters(req): Parameters) -> Result { self.handoff_impl(req) diff --git a/src/mcp_server/types.rs b/src/mcp_server/types.rs index 38ca0a19..9f6f9bc7 100644 --- a/src/mcp_server/types.rs +++ b/src/mcp_server/types.rs @@ -155,7 +155,7 @@ pub(crate) struct HandoffRequest { #[serde(default)] pub(crate) r#type: Option, #[schemars( - description = "Existing item ID to assign and attach to, instead of creating a new item" + description = "Existing item ID to assign and attach to, instead of creating a new one. If the work already has a home item, always pass its id here — omitting it unconditionally creates a new item, even when one covering this work already exists." )] #[serde(default)] pub(crate) item_id: Option,