feat: add short UUID prefix resolution to query_items get operation (#60)

Allow query_items(operation="get") to accept hex prefixes (4-35 chars)
in addition to full 36-char UUIDs. When agents lose short-to-full UUID
mappings after context compaction, they can now resolve items by prefix
directly without searching by title.

- Add findByIdPrefix to WorkItemRepository interface and SQLite impl
- Prefix detection: length==36 → exact UUID match, otherwise hex prefix
- Ambiguous prefixes (2+ matches) return error with full match list
- Prefixes < 4 chars rejected to avoid excessive ambiguity

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jpicklyk

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/application/tools/items/QueryItemsTool.kt

@@ -19,15 +19,24 @@ import kotlinx.serialization.json.*
  */
 class QueryItemsTool : BaseToolDefinition() {
 
+    companion object {
+        /** Minimum hex characters required for prefix resolution (avoids excessive ambiguity). */
+        private const val MIN_PREFIX_LENGTH = 4
+
+        private val HEX_PATTERN = Regex("^[0-9a-fA-F]+$")
+    }
+
     override val name = "query_items"
 
     override val description = """
 Unified read operations for work items.
 
 Operations: get, search, overview
 
-**get** - Retrieve a single item by ID
-- Required: id (UUID)
+**get** - Retrieve a single item by ID or short prefix
+- Required: id (UUID or hex prefix, minimum 4 characters)
+- Full 36-char UUID: exact match (existing behavior)
+- Short hex prefix (4-35 chars): resolves to unique item; errors if ambiguous or not found
 - Returns full item JSON
 - includeAncestors (boolean, default false): When true, each item includes an `ancestors` array showing the full path from root to direct parent
 
@@ -65,7 +74,7 @@ Operations: get, search, overview
             })
             put("id", buildJsonObject {
                 put("type", JsonPrimitive("string"))
-                put("description", JsonPrimitive("Item UUID (required for get)"))
+                put("description", JsonPrimitive("Item UUID or hex prefix (minimum 4 characters)"))
             })
             put("itemId", buildJsonObject {
                 put("type", JsonPrimitive("string"))
@@ -150,7 +159,7 @@ Operations: get, search, overview
     override fun validateParams(params: JsonElement) {
         val operation = requireString(params, "operation")
         when (operation) {
-            "get" -> extractUUID(params, "id", required = true)
+            "get" -> requireString(params, "id") // Accept any string; UUID vs prefix validation happens in executeGet
             "search", "overview" -> { /* all parameters are optional */ }
             else -> throw ToolValidationException("Invalid operation: $operation. Must be one of: get, search, overview")
         }
@@ -227,18 +236,73 @@ Operations: get, search, overview
     // ──────────────────────────────────────────────
 
     private suspend fun executeGet(params: JsonElement, context: ToolExecutionContext): JsonElement {
-        val id = extractUUID(params, "id", required = true)!!
+        val idStr = requireString(params, "id")
         val includeAncestors = params.jsonObject["includeAncestors"]?.jsonPrimitive?.booleanOrNull ?: false
 
-        val item = when (val result = context.workItemRepository().getById(id)) {
-            is Result.Success -> result.data
-            is Result.Error -> return errorResponse(
-                "WorkItem not found",
-                ErrorCodes.RESOURCE_NOT_FOUND,
-                additionalData = buildJsonObject {
-                    put("requestedId", JsonPrimitive(id.toString()))
+        // Try parsing as a full UUID first (fast path — avoids prefix resolution overhead)
+        val item = if (idStr.length == 36) {
+            val id = try {
+                java.util.UUID.fromString(idStr)
+            } catch (_: IllegalArgumentException) {
+                return errorResponse("Invalid UUID format: $idStr", ErrorCodes.VALIDATION_ERROR)
+            }
+            when (val result = context.workItemRepository().getById(id)) {
+                is Result.Success -> result.data
+                is Result.Error -> return errorResponse(
+                    "WorkItem not found",
+                    ErrorCodes.RESOURCE_NOT_FOUND,
+                    additionalData = buildJsonObject {
+                        put("requestedId", JsonPrimitive(idStr))
+                    }
+                )
+            }
+        } else {
+            // Prefix resolution path
+            if (!idStr.matches(HEX_PATTERN)) {
+                return errorResponse(
+                    "Invalid ID format: must be a UUID or hex prefix ($MIN_PREFIX_LENGTH-35 chars), got: $idStr",
+                    ErrorCodes.VALIDATION_ERROR
+                )
+            }
+            if (idStr.length < MIN_PREFIX_LENGTH) {
+                return errorResponse(
+                    "ID prefix too short: minimum $MIN_PREFIX_LENGTH hex characters required, got ${idStr.length}",
+                    ErrorCodes.VALIDATION_ERROR
+                )
+            }
+
+            when (val result = context.workItemRepository().findByIdPrefix(idStr)) {
+                is Result.Success -> {
+                    val matches = result.data
+                    when {
+                        matches.isEmpty() -> return errorResponse(
+                            "No WorkItem found matching prefix: $idStr",
+                            ErrorCodes.RESOURCE_NOT_FOUND,
+                            additionalData = buildJsonObject {
+                                put("prefix", JsonPrimitive(idStr))
+                            }
+                        )
+                        matches.size > 1 -> return errorResponse(
+                            "Ambiguous prefix: $idStr matches ${matches.size} items",
+                            ErrorCodes.VALIDATION_ERROR,
+                            additionalData = buildJsonObject {
+                                put("prefix", JsonPrimitive(idStr))
+                                put("matches", JsonArray(matches.map { match ->
+                                    buildJsonObject {
+                                        put("id", JsonPrimitive(match.id.toString()))
+                                        put("title", JsonPrimitive(match.title))
+                                    }
+                                }))
+                            }
+                        )
+                        else -> matches.first()
+                    }
                 }
-            )
+                is Result.Error -> return errorResponse(
+                    "Failed to resolve prefix: ${result.error.message}",
+                    ErrorCodes.DATABASE_ERROR
+                )
+            }
         }
 
         val itemJson = workItemToJson(item)

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/domain/repository/WorkItemRepository.kt

@@ -89,6 +89,12 @@ interface WorkItemRepository {
      */
     suspend fun deleteAll(ids: Set<UUID>): Result<Int>
 
+    /**
+     * Find work items whose ID starts with the given hex prefix.
+     * Used for short UUID prefix resolution.
+     */
+    suspend fun findByIdPrefix(prefix: String, limit: Int = 10): Result<List<WorkItem>>
+
     /**
      * For each itemId, resolve its full ancestor chain (root -> direct parent).
      * Returns Map<itemId, List<WorkItem>> ordered root-first, ancestors only (item itself excluded).

current/src/main/kotlin/io/github/jpicklyk/mcptask/current/infrastructure/repository/SQLiteWorkItemRepository.kt

@@ -17,7 +17,9 @@ import org.jetbrains.exposed.v1.core.SqlExpressionBuilder.greaterEq
 import org.jetbrains.exposed.v1.core.SqlExpressionBuilder.inList
 import org.jetbrains.exposed.v1.core.SqlExpressionBuilder.lessEq
 import org.jetbrains.exposed.v1.core.SqlExpressionBuilder.like
+import org.jetbrains.exposed.v1.core.VarCharColumnType
 import org.jetbrains.exposed.v1.core.and
+import org.jetbrains.exposed.v1.core.castTo
 import org.jetbrains.exposed.v1.core.dao.id.EntityID
 import org.jetbrains.exposed.v1.core.or
 import org.jetbrains.exposed.v1.jdbc.deleteWhere
@@ -403,6 +405,42 @@ class SQLiteWorkItemRepository(private val databaseManager: DatabaseManager) : W
         }
     }
 
+    override suspend fun findByIdPrefix(prefix: String, limit: Int): Result<List<WorkItem>> = try {
+        // Convert a hex-only prefix into a UUID-formatted prefix for LIKE matching.
+        // UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12)
+        // Dash positions in the hex string: after 8, 12, 16, 20
+        val formattedPrefix = formatHexAsUuidPrefix(prefix.lowercase())
+        newSuspendedTransaction(db = databaseManager.getDatabase()) {
+            val items = WorkItemsTable.selectAll()
+                .where {
+                    WorkItemsTable.id.castTo<String>(VarCharColumnType(36)).like("$formattedPrefix%")
+                }
+                .limit(limit)
+                .mapNotNull { mapRowToWorkItemSafe(it) }
+            Result.Success(items)
+        }
+    } catch (e: Exception) {
+        Result.Error(RepositoryError.DatabaseError("Failed to find WorkItems by ID prefix: ${e.message}", e))
+    }
+
+    /**
+     * Converts a hex-only prefix string into UUID-formatted prefix with dashes
+     * inserted at the correct positions (after hex positions 8, 12, 16, 20).
+     */
+    private fun formatHexAsUuidPrefix(hexPrefix: String): String {
+        val dashPositions = listOf(8, 12, 16, 20)
+        val sb = StringBuilder()
+        var hexIndex = 0
+        for (ch in hexPrefix) {
+            if (hexIndex in dashPositions) {
+                sb.append('-')
+            }
+            sb.append(ch)
+            hexIndex++
+        }
+        return sb.toString()
+    }
+
     override suspend fun findAncestorChains(itemIds: Set<UUID>): Result<Map<UUID, List<WorkItem>>> {
         if (itemIds.isEmpty()) return Result.Success(emptyMap())
         return try {