From 29bcdfd5fce7d939cc44d4a77fd55688e1f3d43e Mon Sep 17 00:00:00 2001
From: John Trujillo <johnandrestrujillo@gmail.com>
Date: Tue, 6 Oct 2026 09:49:58 -0500
Subject: [PATCH 1/2] feat(ai-core): let the agent run any Gradle task
 (ADFA-6337)

New run_gradle_task runs tasks with arguments such as --tests or --rerun, returns build output, cancels on Stop and reruns on repeat requests. GradleCommandLine parses leading options, spaced list entries, colour codes and wrapped host errors; build wait limits move to BuildWait.kt. The chat-history write scope now closes on dispose once queued writes finish.

Refs: ADFA-6337
---
 plugins/AI-Core/ai-core.html                  |  11 +-
 plugins/AI-Core/build.gradle.kts              |   4 +-
 .../AI-Core/src/main/assets/docs/index.html   |   5 +
 .../main/assets/prompts/tool_descriptions.yml |  16 ++
 .../plugins/aicore/tool/handlers/BuildWait.kt |  12 +
 .../tool/handlers/BuiltInToolHandlers.kt      |   5 +
 .../aicore/tool/handlers/GradleCommandLine.kt |  73 ++++++
 .../aicore/tool/handlers/RunAppHandler.kt     |   9 -
 .../tool/handlers/RunGradleTaskHandler.kt     | 211 ++++++++++++++++++
 .../plugins/aicore/viewmodel/ChatViewModel.kt |   6 +-
 .../handlers/BuiltInHandlerApprovalTest.kt    |   1 +
 .../tool/handlers/GradleCommandLineTest.kt    |  72 ++++++
 .../tool/handlers/RunGradleTaskHandlerTest.kt | 205 +++++++++++++++++
 13 files changed, 613 insertions(+), 17 deletions(-)
 create mode 100644 plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuildWait.kt
 create mode 100644 plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLine.kt
 create mode 100644 plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandler.kt
 create mode 100644 plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLineTest.kt
 create mode 100644 plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandlerTest.kt

diff --git a/plugins/AI-Core/ai-core.html b/plugins/AI-Core/ai-core.html
index 0a99341b..8ed34862 100644
--- a/plugins/AI-Core/ai-core.html
+++ b/plugins/AI-Core/ai-core.html
@@ -61,8 +61,9 @@ <h2>Executive overview</h2>
   <h2>Core functionality</h2>
   <ul>
     <li><b>Agent chat</b> — a conversational editor tab that can read and edit
-      project files, add dependencies, run a Gradle sync and launch the app, with
-      every file-changing action gated behind an approval dialog.</li>
+      project files, add dependencies, run a Gradle sync or any Gradle task
+      (tests, lint, clean) and launch the app, with every file-changing action
+      gated behind an approval dialog.</li>
     <li><b>Agent settings</b> — one screen to pick the backend and configure it;
       each backend contributes its own portion of that screen.</li>
     <li><b>Web search</b> — the agent always has <code>web_search</code> (the
@@ -138,8 +139,8 @@ <h2>Technical architecture</h2>
   </table>
   <p>AI Core declares <b>filesystem.read</b>, <b>filesystem.write</b>,
   <b>system.commands</b> and <b>project.structure</b> — the agent reads and edits
-  files in the open project, triggers Gradle sync and run through the IDE's own
-  build service, and inspects the project's module structure. It declares
+  files in the open project, triggers Gradle sync, Gradle tasks and run through
+  the IDE's own build service, and inspects the project's module structure. It declares
   <b>no network access and loads no native code</b>: those belong to the backend
   plugin that serves a given request, so a device using only the local backend
   never grants a network-capable AI plugin. The same holds for tools another
@@ -157,7 +158,7 @@ <h2>Usage</h2>
       enter a Gemini API key. The same screen is reachable from the Agent tab.</li>
     <li>Open a project and switch to the <b>Agent</b> tab to start chatting. Any
       action that changes a file asks for your approval first, as does starting a
-      Gradle sync or generating from a template. Only reads run unprompted.</li>
+      Gradle sync or task, or generating from a template. Only reads run unprompted.</li>
     <li><i>Optional:</i> install a tool provider such as <b>AI Agent MCP</b> to
       give the agent tools beyond its own. Its tools appear in the agent's tool
       list once configured, and each asks for approval naming the plugin it came
diff --git a/plugins/AI-Core/build.gradle.kts b/plugins/AI-Core/build.gradle.kts
index fa98f596..78c39b0a 100644
--- a/plugins/AI-Core/build.gradle.kts
+++ b/plugins/AI-Core/build.gradle.kts
@@ -15,8 +15,8 @@ android {
         applicationId = "com.itsaky.androidide.plugins.aicore"
         minSdk = 33
         targetSdk = 36
-        versionCode = 6
-        versionName = "3.2.0"
+        versionCode = 7
+        versionName = "3.3.0"
     }
 
     buildFeatures {
diff --git a/plugins/AI-Core/src/main/assets/docs/index.html b/plugins/AI-Core/src/main/assets/docs/index.html
index 99d0d59e..10733c78 100644
--- a/plugins/AI-Core/src/main/assets/docs/index.html
+++ b/plugins/AI-Core/src/main/assets/docs/index.html
@@ -103,6 +103,11 @@ <h2>What the agent can do</h2>
       so <b>Ctrl+Z undoes it</b> and your unsaved work is preserved.</li>
     <li>Trigger a Gradle sync (asks for approval — a sync starts a real build)
       and read build output.</li>
+    <li>Run any Gradle task, such as <code>test</code>, <code>lint</code> or
+      <code>clean</code>, with Gradle arguments such as
+      <code>--tests com.example.FooTest</code>. It asks first, runs on the IDE's
+      own Gradle daemon, and reports whether the task passed along with the test
+      failures or compiler errors. Pressing Stop cancels the task.</li>
     <li>Read <b>App Logs</b> and <b>IDE Logs</b>, so it can find the exception
       behind a crash without you copying log lines into the chat. It never
       asks first: reading a log changes nothing.</li>
diff --git a/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml b/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml
index 3e7cfd9d..e393189b 100644
--- a/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml
+++ b/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml
@@ -66,6 +66,22 @@ built_in_tools:
       prompt, so success means the install started, not that the app is on screen
   gradle_sync:
     description: Sync the Gradle project (reload dependencies and rebuild cache)
+  run_gradle_task:
+    # Without "any task" small models still answer that they cannot run tests, and without the
+    # second sentence Gemini answers a repeated "run the tests" from the earlier result.
+    description: >-
+      Run any Gradle task in the project — tests, lint, clean, assemble — and get back whether it
+      passed and the build output, test failures and compiler errors included. A result from an
+      earlier message is out of date: whenever the user asks to run a task, call this tool again
+      instead of repeating that result
+    arguments:
+      tasks: >-
+        The Gradle tasks to run, separated by spaces, e.g. "test" or ":app:testDebugUnitTest".
+      arguments: >-
+        Gradle command-line arguments, separated by spaces, e.g. "--tests com.example.FooTest"
+        or "--info". A task option such as --tests applies to the last task. Gradle skips a task
+        whose inputs have not changed; add "--rerun" to run the last task anyway. Omit when there
+        are none.
   generate_from_template:
     description: Generate files from Pebble templates with variable substitution
     arguments:
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuildWait.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuildWait.kt
new file mode 100644
index 00000000..f9313271
--- /dev/null
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuildWait.kt
@@ -0,0 +1,12 @@
+package com.itsaky.androidide.plugins.aicore.tool.handlers
+
+// Shared by every handler that waits on a build, so run_app and run_gradle_task give up together.
+
+/** How long to wait for a build to finish before reporting it still running. */
+internal const val BUILD_TIMEOUT_MS = 10 * 60 * 1000L
+
+/**
+ * How often to log that the wait is still alive. A build can hold the agent for ten minutes, and
+ * without a heartbeat that stretch of logcat is indistinguishable from a hung agent.
+ */
+internal const val BUILD_PROGRESS_LOG_INTERVAL_MS = 30 * 1000L
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt
index 46edf5a1..999fca77 100644
--- a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt
@@ -37,6 +37,7 @@ object BuiltInToolHandlers {
         // Build tools
         RunAppHandler(context, hasLogTools = hostHasLogApi()),
         GradleSyncHandler(context),
+    ) + (if (hostHasGradleTaskApi()) listOf(RunGradleTaskHandler(context)) else emptyList()) + listOf(
         // Template tool
         GenerateFromTemplateHandler(context),
         // Web tools
@@ -47,6 +48,10 @@ object BuiltInToolHandlers {
     // A string, not a class literal: hosts before ADFA-6267 lack the class, and the literal would throw.
     private fun hostHasLogApi(): Boolean =
         runCatching { Class.forName("com.itsaky.androidide.plugins.services.IdeLogService") }.isSuccess
+
+    // Same reason: a 26.41 host from before ADFA-6373 lacks executeTasks(tasks, arguments).
+    private fun hostHasGradleTaskApi(): Boolean =
+        runCatching { Class.forName("com.itsaky.androidide.plugins.services.GradleTaskResult") }.isSuccess
 }
 
 /** The log tools, kept apart so [LogSource] is only touched on a host that has it. */
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLine.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLine.kt
new file mode 100644
index 00000000..3e55347c
--- /dev/null
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLine.kt
@@ -0,0 +1,73 @@
+package com.itsaky.androidide.plugins.aicore.tool.handlers
+
+/** Tasks and Gradle arguments as the host takes them. */
+internal data class GradleInvocation(val tasks: List<String>, val arguments: List<String>)
+
+/**
+ * Reads the model's `tasks` and `arguments` into a [GradleInvocation]. Knows Gradle's command line,
+ * not the tool's argument names, so [RunGradleTaskHandler] keeps the call shape to itself.
+ */
+internal object GradleCommandLine {
+
+    // Gradle options whose value is the next token rather than `=value`.
+    private val VALUE_OPTIONS = setOf(
+        "-x", "--exclude-task", "--tests", "-p", "--project-dir", "-I", "--init-script",
+        "-g", "--gradle-user-home", "--console", "--warning-mode", "--max-workers", "--include-build",
+    )
+
+    /**
+     * Leading options, and everything from the first option after a task, move from [tasks] to the
+     * arguments: models write `tasks="test --tests Foo"` as often as not.
+     * @param tasks the tasks value as the model gave it: a string, a list, or null.
+     * @param arguments the arguments value, read the same way.
+     * @return the invocation; its task list is empty when the call names none.
+     */
+    fun parse(tasks: Any?, arguments: Any?): GradleInvocation {
+        val taskTokens = tokensOf(tasks)
+        var start = 0
+        while (start < taskTokens.size && taskTokens[start].startsWith("-")) {
+            // `-x lint test` must not run lint, so a leading option's own value stays with it.
+            start += if (taskTokens[start] in VALUE_OPTIONS) 2 else 1
+        }
+        start = start.coerceAtMost(taskTokens.size)
+        val firstOption = (start until taskTokens.size)
+            .firstOrNull { taskTokens[it].startsWith("-") } ?: taskTokens.size
+        return GradleInvocation(
+            tasks = taskTokens.subList(start, firstOption),
+            arguments = taskTokens.subList(0, start) +
+                taskTokens.subList(firstOption, taskTokens.size) + tokensOf(arguments),
+        )
+    }
+
+    /**
+     * Splits a tool argument into command-line tokens: a string on whitespace with single or
+     * double quotes grouping, so `--tests "com.example.Foo*"` stays one value; a list per entry.
+     */
+    fun tokensOf(value: Any?): List<String> = when (value) {
+        null -> emptyList()
+        is List<*> -> value.filterNotNull().flatMap { splitCommandLine(it.toString()) }
+        else -> splitCommandLine(value.toString())
+    }.filter(String::isNotEmpty)
+
+    private fun splitCommandLine(text: String): List<String> {
+        val tokens = mutableListOf<String>()
+        val current = StringBuilder()
+        var quote: Char? = null
+        var inToken = false
+        for (c in text) {
+            when {
+                quote != null && c == quote -> quote = null
+                quote != null -> current.append(c)
+                c == '"' || c == '\'' -> { quote = c; inToken = true }
+                c.isWhitespace() -> if (inToken) {
+                    tokens += current.toString()
+                    current.clear()
+                    inToken = false
+                }
+                else -> { current.append(c); inToken = true }
+            }
+        }
+        if (inToken) tokens += current.toString()
+        return tokens
+    }
+}
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunAppHandler.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunAppHandler.kt
index 829f960c..7060caab 100644
--- a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunAppHandler.kt
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunAppHandler.kt
@@ -15,15 +15,6 @@ import kotlinx.coroutines.withTimeoutOrNull
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.coroutines.resume
 
-/** How long to wait for the build callback before reporting the build still running. */
-internal const val BUILD_TIMEOUT_MS = 10 * 60 * 1000L
-
-/**
- * How often to log that the wait is still alive. A build can hold the agent for ten minutes, and
- * without a heartbeat that stretch of logcat is indistinguishable from a hung agent.
- */
-internal const val BUILD_PROGRESS_LOG_INTERVAL_MS = 30 * 1000L
-
 /**
  * Handler for running/building the app.
  */
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandler.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandler.kt
new file mode 100644
index 00000000..42e8ae8c
--- /dev/null
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandler.kt
@@ -0,0 +1,211 @@
+package com.itsaky.androidide.plugins.aicore.tool.handlers
+
+import com.itsaky.androidide.plugins.PluginContext
+import com.itsaky.androidide.plugins.aicore.logging.AgentTrace
+import com.itsaky.androidide.plugins.aicore.models.ToolResult
+import com.itsaky.androidide.plugins.aicore.tool.ToolHandler
+import com.itsaky.androidide.plugins.aicore.tool.ToolSchema
+import com.itsaky.androidide.plugins.aicore.tool.Validation
+import com.itsaky.androidide.plugins.services.GradleTaskResult
+import com.itsaky.androidide.plugins.services.IdeBuildService
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withTimeoutOrNull
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.CompletionException
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+/**
+ * Handler for running any Gradle task (`test`, `lint`, `clean`, `:app:testDebugUnitTest`) with
+ * Gradle arguments, on the IDE's own tooling server. Its output reaches the Build Output pane, and
+ * the slice worth reading comes back with the result, so a test run reports its failures at once.
+ */
+class RunGradleTaskHandler(
+    private val pluginContext: PluginContext,
+) : ToolHandler {
+    override val toolName = "run_gradle_task"
+
+    // Starts a real build, like run_app and gradle_sync, and the arguments are the model's choice.
+    override val requiresApproval = true
+
+    override val parametersSchema = ToolSchema.objectOf(
+        "tasks" to ToolSchema.string(),
+        "arguments" to ToolSchema.string(),
+        required = listOf("tasks"),
+    )
+
+    override val argAliases = mapOf(
+        "task" to "tasks",
+        "task_name" to "tasks",
+        "args" to "arguments",
+    )
+
+    override suspend fun validate(args: Map<String, Any?>): Validation {
+        val invocation = invocationOf(args)
+        return if (invocation.tasks.isEmpty()) {
+            Validation.Rejected(NO_TASKS)
+        } else {
+            Validation.Accepted(args)
+        }
+    }
+
+    override suspend fun execute(args: Map<String, Any?>): ToolResult {
+        val invocation = invocationOf(args)
+        if (invocation.tasks.isEmpty()) return NO_TASKS
+        val label = invocation.tasks.joinToString(" ")
+
+        return try {
+            val buildService = pluginContext.services.get(IdeBuildService::class.java)
+            if (buildService == null) {
+                AgentTrace.refusal("BUILD", "$toolName rejected", "IdeBuildService not available")
+                return ToolResult.failure(
+                    "Build service not available",
+                    "The IDE build service is not available."
+                )
+            }
+
+            AgentTrace.stage("BUILD", "$toolName tasks=$label args=${invocation.arguments}")
+            val startMs = System.currentTimeMillis()
+            val future = buildService.executeTasks(invocation.tasks, invocation.arguments)
+            val outcome = try {
+                withTimeoutOrNull(BUILD_TIMEOUT_MS) {
+                    coroutineScope {
+                        val heartbeat = launch { logProgressUntilCancelled(startMs) }
+                        try {
+                            awaitResult(future)
+                        } finally {
+                            heartbeat.cancel()
+                        }
+                    }
+                }
+            } catch (ce: CancellationException) {
+                // Stop pressed while the build runs: the agent started it, so the agent ends it.
+                if (!future.isDone) {
+                    AgentTrace.stage("BUILD", "$toolName stopped; cancelling the build")
+                    buildService.cancelBuild()
+                }
+                throw ce
+            }
+            val waitedMs = System.currentTimeMillis() - startMs
+
+            if (outcome == null) {
+                AgentTrace.refusal(
+                    "BUILD",
+                    "$toolName timed out waitedMs=$waitedMs",
+                    "no result within ${BUILD_TIMEOUT_MS / 1000}s; the build may still be running"
+                )
+                return ToolResult.failure(
+                    "Gradle task still running",
+                    "$label did not finish within 10 minutes and may still be running. " +
+                        "Call read_build_output to see how far it got."
+                )
+            }
+
+            AgentTrace.stage("BUILD", "$toolName outcome=$outcome waitedMs=$waitedMs")
+            resultFor(label, outcome, buildService.getBuildOutput())
+        } catch (ce: CancellationException) {
+            // An Exception on the JVM, so the catch below would report Stop as a task failure.
+            throw ce
+        } catch (e: Exception) {
+            AgentTrace.refusal("BUILD", "$toolName failed", e.toString())
+            pluginContext.logger.error("$toolName failed", e)
+            ToolResult.failure(
+                "Error: ${e.javaClass.simpleName}",
+                "${e.message ?: "Unknown error"}\n\n${e.stackTraceToString()}"
+            )
+        }
+    }
+
+    /** Logs one line every [BUILD_PROGRESS_LOG_INTERVAL_MS] while the wait lasts. */
+    private suspend fun logProgressUntilCancelled(startMs: Long) {
+        while (true) {
+            delay(BUILD_PROGRESS_LOG_INTERVAL_MS)
+            val seconds = (System.currentTimeMillis() - startMs) / 1000
+            AgentTrace.detail("BUILD", "$toolName still waiting elapsed=${seconds}s")
+        }
+    }
+
+    /**
+     * Suspends until [future] completes. Unlike `CompletableFuture.await`, a cancelled wait leaves
+     * the future alone, so the caller can still tell whether the build was running when it stopped.
+     */
+    private suspend fun awaitResult(future: CompletableFuture<GradleTaskResult>): GradleTaskResult =
+        suspendCancellableCoroutine { continuation ->
+            future.whenComplete { result, error ->
+                if (!continuation.isActive) return@whenComplete
+                // A dependent stage wraps the host's exception; the model should read the original.
+                val cause = (error as? CompletionException)?.cause ?: error
+                if (cause != null) continuation.resumeWithException(cause) else continuation.resume(result)
+            }
+        }
+
+    companion object {
+        private val NO_TASKS = ToolResult.failure(
+            "tasks is required",
+            "Name the Gradle task to run, e.g. tasks=\"test\" or tasks=\":app:testDebugUnitTest\"."
+        )
+
+        /** The call's `tasks` and `arguments` as the host takes them; see [GradleCommandLine]. */
+        internal fun invocationOf(args: Map<String, Any?>): GradleInvocation =
+            GradleCommandLine.parse(args["tasks"], args["arguments"])
+
+        /**
+         * The tool result for [outcome], carrying the build output window so a failed test or
+         * compile error reaches the model without a second call.
+         */
+        // The else is for a result a newer host adds; without it that result throws at runtime.
+        @Suppress("REDUNDANT_ELSE_IN_WHEN")
+        internal fun resultFor(label: String, outcome: GradleTaskResult, output: String?): ToolResult {
+            val log = output?.takeIf { it.isNotBlank() }?.let { ReadBuildOutputHandler.windowFor(it).text }
+            return when (outcome) {
+                GradleTaskResult.Success -> if (nothingRan(output)) {
+                    ToolResult.success(
+                        message = "$label succeeded; every task was up to date",
+                        data = "$UP_TO_DATE_NOTE\n\n${log.orEmpty()}"
+                    )
+                } else {
+                    ToolResult.success(message = "$label succeeded", data = log ?: "(No build output)")
+                }
+                is GradleTaskResult.Failed -> ToolResult.failure(
+                    "$label failed: ${outcome.reason}",
+                    log ?: "(No build output)"
+                )
+                is GradleTaskResult.Refused -> ToolResult.failure(
+                    "$label did not start: ${outcome.reason}",
+                    "No build ran. If another build is in progress, wait for it to finish and try again."
+                )
+                GradleTaskResult.Cancelled -> ToolResult.failure(
+                    "$label was cancelled",
+                    log ?: "(No build output)"
+                )
+                else -> ToolResult.failure("$label ended with an unknown result: $outcome")
+            }
+        }
+
+        private const val UP_TO_DATE_NOTE =
+            "Gradle skipped every task because nothing changed since it last ran, so no test or " +
+                "check ran now. To run it anyway, call run_gradle_task again with arguments=\"--rerun\"."
+
+        // "> Task :app:test UP-TO-DATE"; a task that ran has no outcome after its path.
+        private val TASK_LINE = Regex("""> Task (\S+)(?: ([A-Z-]+))?\s*$""")
+
+        // A colour console wraps the task line in escapes, which would hide it from TASK_LINE.
+        private val ANSI_ESCAPE = Regex("""\u001B\[[0-9;]*[A-Za-z]""")
+
+        /**
+         * Whether [output] lists tasks and Gradle skipped every one of them (UP-TO-DATE, FROM-CACHE,
+         * NO-SOURCE, SKIPPED). Without task lines nothing is claimed, so the plain result stands.
+         */
+        internal fun nothingRan(output: String?): Boolean {
+            val outcomes = output.orEmpty().lineSequence()
+                .mapNotNull { TASK_LINE.find(it.replace(ANSI_ESCAPE, "")) }
+                .map { it.groupValues[2] }
+                .toList()
+            return outcomes.isNotEmpty() && outcomes.none { it.isEmpty() }
+        }
+    }
+}
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/viewmodel/ChatViewModel.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/viewmodel/ChatViewModel.kt
index 6c6136a9..2f0664ef 100644
--- a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/viewmodel/ChatViewModel.kt
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/viewmodel/ChatViewModel.kt
@@ -426,8 +426,10 @@ class ChatViewModel(
      * the time [onCleared] asks for the last write, and this scope must outlive it. A failure
      * reaching here is logged rather than thrown, so a full disk cannot take the IDE down.
      */
+    private val persistSupervisor = SupervisorJob()
+
     private val persistScope = CoroutineScope(
-        SupervisorJob() + Dispatchers.IO + CoroutineExceptionHandler { _, e ->
+        persistSupervisor + Dispatchers.IO + CoroutineExceptionHandler { _, e ->
             logError("Chat history write failed", e)
         }
     )
@@ -2292,6 +2294,8 @@ class ChatViewModel(
         // schedules cannot run, since viewModelScope is already cancelled by the time we get here.
         stopProcessing(reason = "viewModel cleared")
         persistState()
+        // Ends persistScope once the queued writes finish; complete() lets them run, cancel() would drop them.
+        persistSupervisor.complete()
         stopStateTimer()
     }
 }
diff --git a/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt
index e6025ac6..52c1d27d 100644
--- a/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt
+++ b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt
@@ -23,6 +23,7 @@ class BuiltInHandlerApprovalTest {
             "add_dependency",
             "run_app",
             "gradle_sync",
+            "run_gradle_task",
             "generate_from_template",
         )
 
diff --git a/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLineTest.kt b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLineTest.kt
new file mode 100644
index 00000000..e1e436cc
--- /dev/null
+++ b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/GradleCommandLineTest.kt
@@ -0,0 +1,72 @@
+package com.itsaky.androidide.plugins.aicore.tool.handlers
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Unit tests for [GradleCommandLine] — how the model's `tasks` and `arguments` become the task list
+ * and Gradle arguments that [RunGradleTaskHandler] hands the host (ADFA-6337).
+ */
+class GradleCommandLineTest {
+
+    @Test
+    fun givenOptionsInsideTasks_whenParsing_thenTheyMoveToTheArguments() {
+        val invocation = GradleCommandLine.parse("clean test --tests FooTest", "-Pci=true")
+
+        assertEquals(listOf("clean", "test"), invocation.tasks)
+        assertEquals(listOf("--tests", "FooTest", "-Pci=true"), invocation.arguments)
+    }
+
+    @Test
+    fun givenAListOfTasks_whenParsing_thenEachEntryIsATask() {
+        val invocation = GradleCommandLine.parse(listOf("lint", " test "), null)
+
+        assertEquals(listOf("lint", "test"), invocation.tasks)
+        assertTrue(invocation.arguments.isEmpty())
+    }
+
+    @Test
+    fun givenListEntriesWithSpaces_whenParsing_thenEachEntryIsSplit() {
+        val invocation = GradleCommandLine.parse(listOf("test"), listOf("--tests com.example.FooTest"))
+
+        assertEquals(listOf("test"), invocation.tasks)
+        assertEquals(listOf("--tests", "com.example.FooTest"), invocation.arguments)
+    }
+
+    @Test
+    fun givenAnOptionBeforeTheTasks_whenParsing_thenTheTasksAreStillFound() {
+        val invocation = GradleCommandLine.parse("-Pci=true test --info", null)
+
+        assertEquals(listOf("test"), invocation.tasks)
+        assertEquals(listOf("-Pci=true", "--info"), invocation.arguments)
+    }
+
+    @Test
+    fun givenALeadingExclusion_whenParsing_thenTheExcludedTaskIsNotRun() {
+        val invocation = GradleCommandLine.parse("-x lint build", null)
+
+        assertEquals(listOf("build"), invocation.tasks)
+        assertEquals(listOf("-x", "lint"), invocation.arguments)
+    }
+
+    @Test
+    fun givenAQuotedValue_whenSplitting_thenItStaysOneToken() {
+        val tokens = GradleCommandLine.tokensOf("--tests \"com.example.Foo*\" --tests 'Bar Baz'")
+
+        assertEquals(listOf("--tests", "com.example.Foo*", "--tests", "Bar Baz"), tokens)
+    }
+
+    @Test
+    fun givenAnEmptyQuotedValue_whenSplitting_thenNoEmptyTokenIsKept() {
+        assertTrue(GradleCommandLine.tokensOf("\"\"  ''").isEmpty())
+    }
+
+    @Test
+    fun givenOnlyOptions_whenParsing_thenNoTaskIsNamed() {
+        val invocation = GradleCommandLine.parse("--info --stacktrace", null)
+
+        assertTrue(invocation.tasks.isEmpty())
+        assertEquals(listOf("--info", "--stacktrace"), invocation.arguments)
+    }
+}
diff --git a/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandlerTest.kt b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandlerTest.kt
new file mode 100644
index 00000000..163ea8c1
--- /dev/null
+++ b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/RunGradleTaskHandlerTest.kt
@@ -0,0 +1,205 @@
+package com.itsaky.androidide.plugins.aicore.tool.handlers
+
+import com.itsaky.androidide.plugins.PluginContext
+import com.itsaky.androidide.plugins.ServiceRegistry
+import com.itsaky.androidide.plugins.aicore.tool.Validation
+import com.itsaky.androidide.plugins.services.GradleTaskResult
+import com.itsaky.androidide.plugins.services.IdeBuildService
+import io.mockk.every
+import io.mockk.mockk
+import io.mockk.verify
+import kotlinx.coroutines.cancelAndJoin
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.test.runCurrent
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import java.util.concurrent.CompletableFuture
+
+/**
+ * Unit tests for [RunGradleTaskHandler] — the tool that runs any Gradle task with arguments on the
+ * IDE's tooling server, so the agent can run the tests it was asked to run (ADFA-6337).
+ */
+class RunGradleTaskHandlerTest {
+
+    private lateinit var context: PluginContext
+    private lateinit var services: ServiceRegistry
+    private lateinit var buildService: IdeBuildService
+    private lateinit var handler: RunGradleTaskHandler
+
+    @Before
+    fun setup() {
+        buildService = mockk(relaxed = true)
+        services = mockk()
+        context = mockk()
+        every { context.services } returns services
+        every { context.logger } returns mockk(relaxed = true)
+        every { services.get(IdeBuildService::class.java) } returns buildService
+        every { buildService.getBuildOutput() } returns "BUILD SUCCESSFUL in 4s"
+        handler = RunGradleTaskHandler(context)
+    }
+
+    private fun answerWith(result: GradleTaskResult) {
+        every { buildService.executeTasks(any<List<String>>(), any()) } returns
+            CompletableFuture.completedFuture(result)
+    }
+
+    @Test
+    fun givenNoBuildService_whenRunning_thenItFails() = runTest {
+        every { services.get(IdeBuildService::class.java) } returns null
+
+        val result = handler.execute(mapOf("tasks" to "test"))
+
+        assertFalse(result.success)
+        assertTrue(result.message.contains("not available"))
+    }
+
+    @Test
+    fun givenNoTasks_whenValidating_thenItIsRejectedBeforeApproval() = runTest {
+        val validation = handler.validate(mapOf("tasks" to "  "))
+
+        assertTrue(validation is Validation.Rejected)
+    }
+
+    @Test
+    fun givenNoTasks_whenRunning_thenNoBuildStarts() = runTest {
+        val result = handler.execute(emptyMap())
+
+        assertFalse(result.success)
+        verify(exactly = 0) { buildService.executeTasks(any<List<String>>(), any()) }
+    }
+
+    @Test
+    fun givenTasksAndArguments_whenRunning_thenTheHostGetsThemSeparately() = runTest {
+        answerWith(GradleTaskResult.Success)
+
+        handler.execute(mapOf("tasks" to ":app:testDebugUnitTest", "arguments" to "--tests \"com.example.Foo*\" --info"))
+
+        verify {
+            buildService.executeTasks(
+                listOf(":app:testDebugUnitTest"),
+                listOf("--tests", "com.example.Foo*", "--info"),
+            )
+        }
+    }
+
+    @Test
+    fun givenOnlyOptions_whenValidating_thenItIsRejected() = runTest {
+        val validation = handler.validate(mapOf("tasks" to "--info \"\""))
+
+        assertTrue(validation is Validation.Rejected)
+    }
+
+    @Test
+    fun givenAFailedFutureStage_whenRunning_thenTheHostErrorIsReported() = runTest {
+        every { buildService.executeTasks(any<List<String>>(), any()) } returns
+            CompletableFuture.failedFuture<GradleTaskResult>(IllegalStateException("tooling server down"))
+                .thenApply { it }
+
+        val result = handler.execute(mapOf("tasks" to "test"))
+
+        assertFalse(result.success)
+        assertEquals("Error: IllegalStateException", result.message)
+        assertTrue(result.error_details!!.startsWith("tooling server down"))
+    }
+
+    @Test
+    fun givenASuccessfulTask_whenRunning_thenItSucceedsWithTheBuildOutput() = runTest {
+        answerWith(GradleTaskResult.Success)
+
+        val result = handler.execute(mapOf("tasks" to "test"))
+
+        assertTrue(result.success)
+        assertEquals("BUILD SUCCESSFUL in 4s", result.data)
+    }
+
+    @Test
+    fun givenEveryTaskUpToDate_whenRunning_thenTheResultSaysNothingRanAndHowToRerun() = runTest {
+        answerWith(GradleTaskResult.Success)
+        every { buildService.getBuildOutput() } returns
+            "> Task :app:compileDebugKotlin UP-TO-DATE\n> Task :app:testDebugUnitTest UP-TO-DATE\nBUILD SUCCESSFUL"
+
+        val result = handler.execute(mapOf("tasks" to "test"))
+
+        assertTrue(result.success)
+        assertTrue(result.message.contains("up to date"))
+        assertTrue(result.data!!.contains("--rerun"))
+    }
+
+    @Test
+    fun givenATaskThatRan_whenCheckingTheOutput_thenSomethingRan() {
+        val output = "> Task :app:compileDebugKotlin UP-TO-DATE\n> Task :app:testDebugUnitTest\nBUILD SUCCESSFUL"
+
+        assertFalse(RunGradleTaskHandler.nothingRan(output))
+    }
+
+    @Test
+    fun givenColouredTaskLines_whenCheckingTheOutput_thenTheEscapesAreIgnored() {
+        val output = "\u001B[1m> Task :app:compileDebugKotlin\u001B[m UP-TO-DATE\n" +
+            "\u001B[1m> Task :app:testDebugUnitTest\u001B[m\nBUILD SUCCESSFUL"
+
+        assertFalse(RunGradleTaskHandler.nothingRan(output))
+        assertTrue(RunGradleTaskHandler.nothingRan("\u001B[33m> Task :app:test UP-TO-DATE\u001B[0m"))
+    }
+
+    @Test
+    fun givenNoTaskLines_whenCheckingTheOutput_thenNothingIsClaimed() {
+        assertFalse(RunGradleTaskHandler.nothingRan("BUILD SUCCESSFUL in 4s"))
+    }
+
+    @Test
+    fun givenAFailedTask_whenRunning_thenItFailsWithTheReasonAndTheFirstError() = runTest {
+        answerWith(GradleTaskResult.Failed("BUILD_FAILED"))
+        every { buildService.getBuildOutput() } returns
+            "> Task :app:testDebugUnitTest\nFooTest > adds FAILED\nFAILURE: Build failed with an exception."
+
+        val result = handler.execute(mapOf("tasks" to "test"))
+
+        assertFalse(result.success)
+        assertTrue(result.message.contains("BUILD_FAILED"))
+        assertTrue(result.error_details!!.contains("FAILURE: Build failed"))
+    }
+
+    @Test
+    fun givenARefusedTask_whenRunning_thenItSaysNoBuildRan() = runTest {
+        answerWith(GradleTaskResult.Refused("another build is in progress"))
+
+        val result = handler.execute(mapOf("tasks" to "test"))
+
+        assertFalse(result.success)
+        assertTrue(result.message.contains("did not start: another build is in progress"))
+    }
+
+    @Test
+    fun givenACancelledTask_whenRunning_thenItReportsTheCancellation() = runTest {
+        answerWith(GradleTaskResult.Cancelled)
+
+        val result = handler.execute(mapOf("tasks" to "test"))
+
+        assertFalse(result.success)
+        assertTrue(result.message.contains("cancelled"))
+    }
+
+    @Test
+    fun givenARunningTask_whenTheAgentIsStopped_thenTheBuildIsCancelled() = runTest {
+        every { buildService.executeTasks(any<List<String>>(), any()) } returns CompletableFuture()
+
+        val job = launch { handler.execute(mapOf("tasks" to "test")) }
+        runCurrent()
+        job.cancelAndJoin()
+
+        verify(exactly = 1) { buildService.cancelBuild() }
+    }
+
+    @Test
+    fun givenATaskThatFinished_whenRunning_thenNoBuildIsCancelled() = runTest {
+        answerWith(GradleTaskResult.Success)
+
+        handler.execute(mapOf("tasks" to "test"))
+
+        verify(exactly = 0) { buildService.cancelBuild() }
+    }
+}

From 90c9818b6e63666ca838812d0c0725936729c120 Mon Sep 17 00:00:00 2001
From: John Trujillo <johnandrestrujillo@gmail.com>
Date: Tue, 6 Oct 2026 18:30:44 -0500
Subject: [PATCH 2/2] feat(ai-core): add list_gradle_tasks so the agent finds
 custom tasks

Lists the project's tasks by group from the last sync, filterable by path, group or description, kept within the 4000-char tool-result cap.

Refs: ADFA-6337
---
 plugins/AI-Core/ai-core.html                  |   4 +-
 .../AI-Core/src/main/assets/docs/index.html   |   3 +
 .../main/assets/prompts/tool_descriptions.yml |  12 +-
 .../tool/handlers/BuiltInToolHandlers.kt      |   7 +-
 .../tool/handlers/ListGradleTasksHandler.kt   | 141 ++++++++++++++
 .../handlers/BuiltInHandlerApprovalTest.kt    |   1 +
 .../handlers/ListGradleTasksHandlerTest.kt    | 174 ++++++++++++++++++
 7 files changed, 338 insertions(+), 4 deletions(-)
 create mode 100644 plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandler.kt
 create mode 100644 plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandlerTest.kt

diff --git a/plugins/AI-Core/ai-core.html b/plugins/AI-Core/ai-core.html
index 8ed34862..afaccd6d 100644
--- a/plugins/AI-Core/ai-core.html
+++ b/plugins/AI-Core/ai-core.html
@@ -61,8 +61,8 @@ <h2>Executive overview</h2>
   <h2>Core functionality</h2>
   <ul>
     <li><b>Agent chat</b> — a conversational editor tab that can read and edit
-      project files, add dependencies, run a Gradle sync or any Gradle task
-      (tests, lint, clean) and launch the app, with every file-changing action
+      project files, add dependencies, run a Gradle sync, list and run any Gradle
+      task (tests, lint, clean, your own) and launch the app, with every file-changing action
       gated behind an approval dialog.</li>
     <li><b>Agent settings</b> — one screen to pick the backend and configure it;
       each backend contributes its own portion of that screen.</li>
diff --git a/plugins/AI-Core/src/main/assets/docs/index.html b/plugins/AI-Core/src/main/assets/docs/index.html
index 10733c78..afd6e6ff 100644
--- a/plugins/AI-Core/src/main/assets/docs/index.html
+++ b/plugins/AI-Core/src/main/assets/docs/index.html
@@ -108,6 +108,9 @@ <h2>What the agent can do</h2>
       <code>--tests com.example.FooTest</code>. It asks first, runs on the IDE's
       own Gradle daemon, and reports whether the task passed along with the test
       failures or compiler errors. Pressing Stop cancels the task.</li>
+    <li>List the project's Gradle tasks, your own custom tasks included, with
+      each task's group and description as of the last sync, so it runs a task
+      that exists. A task you just added appears after the next Gradle sync.</li>
     <li>Read <b>App Logs</b> and <b>IDE Logs</b>, so it can find the exception
       behind a crash without you copying log lines into the chat. It never
       asks first: reading a log changes nothing.</li>
diff --git a/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml b/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml
index e393189b..1927d0e9 100644
--- a/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml
+++ b/plugins/AI-Core/src/main/assets/prompts/tool_descriptions.yml
@@ -73,7 +73,7 @@ built_in_tools:
       Run any Gradle task in the project — tests, lint, clean, assemble — and get back whether it
       passed and the build output, test failures and compiler errors included. A result from an
       earlier message is out of date: whenever the user asks to run a task, call this tool again
-      instead of repeating that result
+      instead of repeating that result. Unsure of a task's name? Call list_gradle_tasks first
     arguments:
       tasks: >-
         The Gradle tasks to run, separated by spaces, e.g. "test" or ":app:testDebugUnitTest".
@@ -82,6 +82,16 @@ built_in_tools:
         or "--info". A task option such as --tests applies to the last task. Gradle skips a task
         whose inputs have not changed; add "--rerun" to run the last task anyway. Omit when there
         are none.
+  list_gradle_tasks:
+    # Without "custom tasks" models answer from Gradle and Android defaults and miss the project's own.
+    description: >-
+      List the Gradle tasks this project has, the project's own custom tasks included, with each
+      task's path, group and what it does. Call it before run_gradle_task when you are unsure a
+      task exists or which task does what the user asked
+    arguments:
+      filter: >-
+        Text to search task paths, groups and descriptions for, e.g. ":app", "test" or "lint".
+        Omit to list the tasks that have a group or a description.
   generate_from_template:
     description: Generate files from Pebble templates with variable substitution
     arguments:
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt
index 999fca77..dd8fcdd5 100644
--- a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInToolHandlers.kt
@@ -37,7 +37,8 @@ object BuiltInToolHandlers {
         // Build tools
         RunAppHandler(context, hasLogTools = hostHasLogApi()),
         GradleSyncHandler(context),
-    ) + (if (hostHasGradleTaskApi()) listOf(RunGradleTaskHandler(context)) else emptyList()) + listOf(
+    ) + (if (hostHasGradleTaskApi()) listOf(RunGradleTaskHandler(context)) else emptyList()) +
+        (if (hostHasTaskListApi()) listOf(ListGradleTasksHandler(context)) else emptyList()) + listOf(
         // Template tool
         GenerateFromTemplateHandler(context),
         // Web tools
@@ -52,6 +53,10 @@ object BuiltInToolHandlers {
     // Same reason: a 26.41 host from before ADFA-6373 lacks executeTasks(tasks, arguments).
     private fun hostHasGradleTaskApi(): Boolean =
         runCatching { Class.forName("com.itsaky.androidide.plugins.services.GradleTaskResult") }.isSuccess
+
+    // Same reason: a host from before IdeBuildService.getTasks lacks the class, and the call would throw.
+    private fun hostHasTaskListApi(): Boolean =
+        runCatching { Class.forName("com.itsaky.androidide.plugins.services.GradleTaskInfo") }.isSuccess
 }
 
 /** The log tools, kept apart so [LogSource] is only touched on a host that has it. */
diff --git a/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandler.kt b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandler.kt
new file mode 100644
index 00000000..2645ba83
--- /dev/null
+++ b/plugins/AI-Core/src/main/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandler.kt
@@ -0,0 +1,141 @@
+package com.itsaky.androidide.plugins.aicore.tool.handlers
+
+import com.itsaky.androidide.plugins.PluginContext
+import com.itsaky.androidide.plugins.aicore.logging.AgentTrace
+import com.itsaky.androidide.plugins.aicore.models.ToolResult
+import com.itsaky.androidide.plugins.aicore.tool.ToolHandler
+import com.itsaky.androidide.plugins.aicore.tool.ToolSchema
+import com.itsaky.androidide.plugins.services.GradleTaskInfo
+import com.itsaky.androidide.plugins.services.IdeBuildService
+import kotlinx.coroutines.CancellationException
+
+/**
+ * Handler for listing the project's Gradle tasks with their group and description, from the IDE's
+ * last sync, so the agent picks a task that exists before it calls run_gradle_task.
+ */
+class ListGradleTasksHandler(
+    private val pluginContext: PluginContext,
+) : ToolHandler {
+    override val toolName = "list_gradle_tasks"
+    override val requiresApproval = false
+
+    override val parametersSchema = ToolSchema.objectOf(
+        "filter" to ToolSchema.string(),
+    )
+
+    override val argAliases = mapOf(
+        "query" to "filter",
+        "search" to "filter",
+        "module" to "filter",
+        "group" to "filter",
+    )
+
+    override suspend fun execute(args: Map<String, Any?>): ToolResult {
+        val filter = (args["filter"] as? String)?.trim().orEmpty()
+        return try {
+            val buildService = pluginContext.services.get(IdeBuildService::class.java)
+            if (buildService == null) {
+                AgentTrace.refusal("BUILD", "$toolName rejected", "IdeBuildService not available")
+                return ToolResult.failure(
+                    "Build service not available",
+                    "The IDE build service is not available."
+                )
+            }
+            val tasks = buildService.getTasks()
+            AgentTrace.detail("BUILD", "$toolName filter='$filter' hostTasks=${tasks.size}")
+            resultFor(tasks, filter)
+        } catch (ce: CancellationException) {
+            // An Exception on the JVM, so the catch below would report Stop as a listing failure.
+            throw ce
+        } catch (e: Exception) {
+            AgentTrace.refusal("BUILD", "$toolName failed", e.toString())
+            pluginContext.logger.error("$toolName failed", e)
+            ToolResult.failure(
+                "Error listing Gradle tasks",
+                "${e.message ?: "Unknown error"}\n\n${e.stackTraceToString()}"
+            )
+        }
+    }
+
+    companion object {
+        /** Maximum characters of the whole result, message included: the prompt cuts a longer one. */
+        internal const val MAX_LIST_CHARS = LogWindowCalculator.MAX_OUTPUT_CHARS
+
+        private const val NOT_SYNCED =
+            "The IDE has no task list: the project is not open or has not synced. Call gradle_sync " +
+                "and then list the tasks again."
+
+        private const val NO_DESCRIPTIONS =
+            "\n\n[Descriptions left out to fit every task. Pass a filter to see them.]"
+
+        private const val CUT_SHORT =
+            "\n[List cut short. Pass a filter such as a module (\":app\") or a group " +
+                "(\"verification\") to see the rest.]"
+
+        /**
+         * The listing for [tasks]. Without [filter] it shows grouped tasks and described ones, so a
+         * user's ungrouped task shows; a filter searches every task by path, group and description.
+         */
+        internal fun resultFor(tasks: List<GradleTaskInfo>, filter: String): ToolResult {
+            if (tasks.isEmpty()) return ToolResult.failure("No Gradle tasks", NOT_SYNCED)
+
+            val shown = if (filter.isEmpty()) {
+                // Plugin-internal tasks such as compileDebugKotlin carry neither; a user's task has one.
+                tasks.filter { it.group != null || it.description != null }
+            } else {
+                tasks.filter { it.matches(filter) }
+            }
+            if (shown.isEmpty()) {
+                return ToolResult.success(
+                    message = "No Gradle task matches \"$filter\"",
+                    data = "None of the ${tasks.size} tasks matches. Try a shorter filter, or omit " +
+                        "it to see the main tasks. A task added since the last sync needs " +
+                        "gradle_sync first."
+                )
+            }
+
+            val hidden = tasks.size - shown.size
+            val note = if (filter.isEmpty() && hidden > 0) {
+                "\n\n$hidden tasks with no group or description are not shown; pass a filter to " +
+                    "search them too."
+            } else {
+                ""
+            }
+            val message = if (filter.isEmpty()) {
+                "${shown.size} Gradle tasks"
+            } else {
+                "${shown.size} Gradle tasks matching \"$filter\""
+            }
+            // The prompt sends the message, a newline and the data, so the listing gets what is left.
+            val room = MAX_LIST_CHARS - message.length - 1 - note.length
+
+            // Descriptions go before tasks do: a cut drops the last groups, the user's own among them.
+            val full = render(shown, withDescriptions = true)
+            val listing = if (full.length <= room) {
+                full
+            } else {
+                render(shown, withDescriptions = false) + NO_DESCRIPTIONS
+            }
+            val text = if (listing.length > room) {
+                listing.take(room - CUT_SHORT.length).substringBeforeLast('\n') + CUT_SHORT
+            } else {
+                listing
+            }
+            return ToolResult.success(message = message, data = "$text$note")
+        }
+
+        private fun GradleTaskInfo.matches(filter: String): Boolean =
+            listOfNotNull(path, group, description).any { it.contains(filter, ignoreCase = true) }
+
+        /** One block per group, "path — description" per task; ungrouped tasks come last. */
+        private fun render(tasks: List<GradleTaskInfo>, withDescriptions: Boolean): String =
+            tasks.groupBy { it.group ?: "other" }
+                .entries
+                .sortedWith(compareBy({ it.key == "other" }, { it.key }))
+                .joinToString("\n\n") { (group, inGroup) ->
+                    "$group:\n" + inGroup.joinToString("\n") { task ->
+                        task.description?.takeIf { withDescriptions }?.let { "${task.path} — $it" } ?: task.path
+                    }
+                }
+    }
+}
diff --git a/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt
index 52c1d27d..955fa0bd 100644
--- a/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt
+++ b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/BuiltInHandlerApprovalTest.kt
@@ -40,6 +40,7 @@ class BuiltInHandlerApprovalTest {
             "search_project",
             "open_file",
             "read_build_output",
+            "list_gradle_tasks",
             // Its query goes to the provider already holding the conversation; no new party sees it.
             "web_search",
             "read_app_logs",
diff --git a/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandlerTest.kt b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandlerTest.kt
new file mode 100644
index 00000000..8a1836e8
--- /dev/null
+++ b/plugins/AI-Core/src/test/kotlin/com/itsaky/androidide/plugins/aicore/tool/handlers/ListGradleTasksHandlerTest.kt
@@ -0,0 +1,174 @@
+package com.itsaky.androidide.plugins.aicore.tool.handlers
+
+import com.itsaky.androidide.plugins.PluginContext
+import com.itsaky.androidide.plugins.ServiceRegistry
+import com.itsaky.androidide.plugins.aicore.models.ToolResult
+import com.itsaky.androidide.plugins.aicore.prompt.ToolResultsPrompt
+import com.itsaky.androidide.plugins.aicore.tool.normalizeToolArgs
+import com.itsaky.androidide.plugins.services.GradleTaskInfo
+import com.itsaky.androidide.plugins.services.IdeBuildService
+import io.mockk.every
+import io.mockk.mockk
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+
+/**
+ * Unit tests for [ListGradleTasksHandler] — the tool that tells the agent which Gradle tasks the
+ * project has, so it runs a task that exists rather than one it guessed.
+ */
+class ListGradleTasksHandlerTest {
+
+    private lateinit var services: ServiceRegistry
+    private lateinit var buildService: IdeBuildService
+    private lateinit var handler: ListGradleTasksHandler
+
+    private val greet = GradleTaskInfo(":greet", "greet", ":", "custom", "Prints a greeting")
+    private val unitTests = GradleTaskInfo(":app:testDebugUnitTest", "testDebugUnitTest", ":app", "verification", "Run unit tests")
+    private val lint = GradleTaskInfo(":app:lint", "lint", ":app", "verification", null)
+    private val compile = GradleTaskInfo(":app:compileDebugKotlin", "compileDebugKotlin", ":app", null, null)
+
+    @Before
+    fun setup() {
+        buildService = mockk(relaxed = true)
+        services = mockk()
+        val context = mockk<PluginContext>()
+        every { context.services } returns services
+        every { context.logger } returns mockk(relaxed = true)
+        every { services.get(IdeBuildService::class.java) } returns buildService
+        every { buildService.getTasks() } returns listOf(greet, unitTests, lint, compile)
+        handler = ListGradleTasksHandler(context)
+    }
+
+    @Test
+    fun givenNoBuildService_whenListing_thenItFails() = runTest {
+        every { services.get(IdeBuildService::class.java) } returns null
+
+        val result = handler.execute(emptyMap())
+
+        assertFalse(result.success)
+        assertTrue(result.message.contains("not available"))
+    }
+
+    @Test
+    fun givenUnsyncedProject_whenListing_thenItAsksForASync() = runTest {
+        every { buildService.getTasks() } returns emptyList()
+
+        val result = handler.execute(emptyMap())
+
+        assertFalse(result.success)
+        assertTrue(result.error_details!!.contains("gradle_sync"))
+    }
+
+    @Test
+    fun givenNoFilter_whenListing_thenGroupedTasksShowWithDescriptionsByGroup() = runTest {
+        val result = handler.execute(emptyMap())
+
+        assertTrue(result.success)
+        assertEquals("3 Gradle tasks", result.message)
+        assertTrue(
+            result.data!!.startsWith(
+                "custom:\n:greet — Prints a greeting\n\n" +
+                    "verification:\n:app:testDebugUnitTest — Run unit tests\n:app:lint"
+            )
+        )
+    }
+
+    @Test
+    fun givenNoFilter_whenListing_thenUngroupedTasksAreCountedNotShown() = runTest {
+        val data = handler.execute(emptyMap()).data!!
+
+        assertFalse(data.contains(":app:compileDebugKotlin"))
+        assertTrue(data.contains("1 tasks with no group or description are not shown"))
+    }
+
+    @Test
+    fun givenUngroupedTaskWithDescription_whenListingWithoutFilter_thenItShowsUnderOther() = runTest {
+        val handshake = GradleTaskInfo(":app:secretHandshake", "secretHandshake", ":app", null, "Prints a hidden greeting")
+        every { buildService.getTasks() } returns listOf(greet, compile, handshake)
+
+        val result = handler.execute(emptyMap())
+
+        assertEquals("2 Gradle tasks", result.message)
+        assertTrue(result.data!!.contains("other:\n:app:secretHandshake — Prints a hidden greeting"))
+        assertFalse(result.data!!.contains(":app:compileDebugKotlin"))
+    }
+
+    @Test
+    fun givenFilter_whenListing_thenUngroupedTasksAreSearchedToo() = runTest {
+        val result = handler.execute(mapOf("filter" to "compile"))
+
+        assertEquals("1 Gradle tasks matching \"compile\"", result.message)
+        assertEquals("other:\n:app:compileDebugKotlin", result.data)
+    }
+
+    @Test
+    fun givenFilterMatchingDescription_whenListing_thenTheTaskIsFoundIgnoringCase() = runTest {
+        val result = handler.execute(mapOf("filter" to "GREETING"))
+
+        assertEquals("custom:\n:greet — Prints a greeting", result.data)
+    }
+
+    @Test
+    fun givenModuleAlias_whenListing_thenItFiltersByPath() = runTest {
+        val data = handler.execute(normalizeToolArgs(handler, mapOf("module" to ":app"))).data!!
+
+        assertFalse(data.contains(":greet"))
+        assertTrue(data.contains(":app:lint"))
+    }
+
+    @Test
+    fun givenFilterMatchingNothing_whenListing_thenItSucceedsWithAHint() = runTest {
+        val result = handler.execute(mapOf("filter" to "deploy"))
+
+        assertTrue(result.success)
+        assertTrue(result.data!!.contains("gradle_sync"))
+    }
+
+    @Test
+    fun givenDescriptionsTooLongToFit_whenListing_thenEveryTaskKeepsItsPathAndOtherSurvives() {
+        val many = (1..150).map { GradleTaskInfo(":app:task$it", "task$it", ":app", "build", "Does step $it of the build, at some length") }
+        val handshake = GradleTaskInfo(":app:secretHandshake", "secretHandshake", ":app", null, "Prints a greeting")
+
+        val result = ListGradleTasksHandler.resultFor(many + handshake, "")
+        val data = result.data!!
+
+        assertTrue(promptBody(result).length <= ToolResultsPrompt.DEFAULT_CHAR_LIMIT)
+        assertTrue(data.contains("Descriptions left out"))
+        assertTrue(data.contains("other:\n:app:secretHandshake"))
+        assertTrue(data.contains(":app:task150\n"))
+        assertFalse(data.contains("List cut short"))
+    }
+
+    @Test
+    fun givenTooManyTasksEvenWithoutDescriptions_whenListing_thenTheListIsCutAtALineWithAHint() {
+        val many = (1..1000).map { GradleTaskInfo(":feature:module:task$it", "task$it", ":feature:module", "build", null) }
+
+        val result = ListGradleTasksHandler.resultFor(many, "")
+        val data = result.data!!
+
+        assertTrue(promptBody(result).length <= ToolResultsPrompt.DEFAULT_CHAR_LIMIT)
+        assertTrue(data.contains("List cut short"))
+        assertTrue(data.lines().filter { it.startsWith(":feature") }.all { it.matches(Regex(":feature:module:task\\d+")) })
+    }
+
+    @Test
+    fun givenListBetweenPromptCapAndOldBudget_whenListing_thenTheLastTaskReachesTheModel() {
+        // Shaped like a stock app module: about 6000 characters with descriptions, under the old 8000 budget.
+        val agp = (1..70).map { GradleTaskInfo(":app:agpTask$it", "agpTask$it", ":app", "build", "Runs step $it of the Android build pipeline") }
+        val handshake = GradleTaskInfo(":app:secretHandshake", "secretHandshake", ":app", null, "Prints a greeting")
+        val hiddenTasks = (1..200).map { GradleTaskInfo(":app:internal$it", "internal$it", ":app", null, null) }
+
+        val result = ListGradleTasksHandler.resultFor(agp + handshake + hiddenTasks, "")
+
+        assertTrue(promptBody(result).length <= ToolResultsPrompt.DEFAULT_CHAR_LIMIT)
+        assertTrue(result.data!!.contains(":app:secretHandshake"))
+        assertTrue(result.data!!.contains("200 tasks with no group or description"))
+    }
+
+    // What ToolResultsPrompt hands the model for a successful result, before its own cut.
+    private fun promptBody(result: ToolResult): String = result.message + "\n" + result.data
+}