feat(task): allow passing arguments to task dependencies via {{usage.*}} templates (#8893)

## Summary
- Task dependencies can now reference parent task arguments using
`{{usage.*}}` templates in `depends`, `depends_post`, and `wait_for`
- Arguments flow through dependency chains (A -> B -> C) — each task
parses its own usage spec and re-renders child dependency templates with
resolved values
- Works with both positional args (`arg`) and flags (`flag`), and with
both string and structured dependency syntax

### Example

```toml
[tasks.build]
usage = 'arg "<app>"'
run = 'echo "building {{usage.app}}"'

[tasks.deploy]
usage = 'arg "<app>"'
depends = [{ task = "build", args = ["{{usage.app}}"] }]
run = 'echo "deploying {{usage.app}}"'
```

```
$ mise run deploy myapp
[build] building myapp
[deploy] deploying myapp
```

Closes discussion #4331

## Implementation

Dependency templates containing `{{usage.*}}` are deferred during
initial config loading (since CLI args aren't available yet). They are
re-rendered later with actual usage values at two points:

1. **Top-level tasks** — after CLI args are resolved in `run.rs`, before
dependency graph construction
2. **Dependency chain tasks** — during `Deps::new()` graph building,
when a task receives args from its parent

Key changes:
- `Task` stores raw (unrendered) dependency templates in
`depends_raw`/`depends_post_raw`/`wait_for_raw`
- New `render_depends_with_usage()` method re-renders deps with a
`usage` context
- New `parse_usage_values_from_task()` parses a task's usage spec
against its args to extract named values
- Dependency resolution (`resolve_depends`, `all_depends`) skips deps
with unresolved `{{usage.*}}` refs

## Test plan
- [x] E2E test `test_task_dep_args` covering:
  - Basic arg passing to dependency
  - Flag passing to dependency
  - Multiple parallel dependencies receiving the same arg
  - String syntax (`depends = ["child {{usage.name}}"]`)
  - Dependency chaining (A -> B -> C, args flow through all levels)
- [x] All existing dep-related e2e tests pass (dep_env, deps,
run_depends, depends_post, depends_post_multiple, deps_circular,
skip_deps, failure_hang_depends, delegation_dedup, double_dash_behavior,
args_position)
- [x] All 563 unit tests pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches task dependency resolution and graph building to defer and
later re-render dependency specs, which can affect what tasks run and
with what args across chains. Added e2e coverage reduces risk but
dependency parsing/rendering changes can have edge cases (e.g.,
`skip_deps`, mixed template/env syntax).
> 
> **Overview**
> Enables `{{usage.*}}` templates inside `depends`, `depends_post`, and
`wait_for` so a task can forward its resolved usage args/flags to
dependency tasks (including through multi-level dependency chains).
> 
> Implements deferred rendering for dependency entries that reference
`{{usage.*}}` by preserving raw dependency templates on `Task`, skipping
unresolved deps during initial resolution, then re-rendering them later
once CLI/parent-provided args are known (during `mise run` task list
creation and again while building the dependency graph).
> 
> Adds an end-to-end test covering positional args, flags, string vs
structured dependency syntax, fan-out dependencies, and chained
forwarding, and updates docs to describe the new argument-forwarding
behavior.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
076b9c5. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/tasks/task-arguments.md

@@ -70,6 +70,11 @@ used with Tera's `for` loops and filters like `length`. The `usage` map is
 `flag()`) described later on this page—you should not mix the two approaches in
 the same task.
 
+<span v-pre>`{{usage.*}}`</span> templates can also be used in `depends`, `depends_post`, and
+`wait_for` to forward arguments to dependency tasks. See
+[Passing parent task arguments to dependencies](/tasks/task-configuration#passing-parent-task-arguments-to-dependencies)
+for details.
+
 **Help output example:**
 
 ```shellsession

docs/tasks/task-configuration.md

@@ -129,6 +129,49 @@ run = "./deploy.sh"
 
 Note: These environment variables are passed only to the specified dependency, not to the current task or other dependencies.
 
+#### Passing parent task arguments to dependencies
+
+You can forward a parent task's arguments to its dependencies using <span v-pre>`{{usage.*}}`</span> templates.
+Both the parent and child tasks must define a `usage` spec for the arguments they accept:
+
+```mise-toml
+[tasks.build]
+usage = 'arg "<app>"'
+run = 'echo "building {{usage.app}}"'
+
+[tasks.deploy]
+usage = 'arg "<app>"'
+depends = [{ task = "build", args = ["{{usage.app}}"] }]
+run = 'echo "deploying {{usage.app}}"'
+```
+
+Running `mise run deploy myapp` passes `"myapp"` to both `deploy` and its `build` dependency.
+
+This also works with the string syntax:
+
+```mise-toml
+[tasks.deploy]
+usage = 'arg "<app>"'
+depends = ["build {{usage.app}}"]
+run = 'echo "deploying {{usage.app}}"'
+```
+
+And with flags:
+
+```mise-toml
+[tasks.compile]
+usage = 'flag "--target <target>"'
+run = 'echo "compiling for $usage_target"'
+
+[tasks.package]
+usage = 'flag "--target <target>"'
+depends = [{ task = "compile", args = ["--target", "{{usage.target}}"] }]
+run = 'echo "packaging for $usage_target"'
+```
+
+Arguments flow through dependency chains — if A depends on B which depends on C, each task can
+forward its resolved arguments to its own dependencies.
+
 ### `depends_post`
 
 - **Type**: `string | string[] | { task: string, args?: string[], env?: { [key]: string } }[]`

e2e/tasks/test_task_dep_args

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+
+# Test passing arguments to task dependencies via {{usage.*}} templates
+
+# Basic test: parent task passes its arg to a dependency
+cat <<'EOF' >mise.toml
+[tasks.build]
+usage = 'arg "<app>"'
+run = 'echo "building {{usage.app}}"'
+
+[tasks.deploy]
+usage = 'arg "<app>"'
+depends = [{ task = "build", args = ["{{usage.app}}"] }]
+run = 'echo "deploying {{usage.app}}"'
+EOF
+
+assert_contains "mise run deploy myapp" "building myapp"
+assert_contains "mise run deploy myapp" "deploying myapp"
+
+# Test with flag syntax
+cat <<'EOF' >mise.toml
+[tasks.compile]
+usage = 'flag "--target <target>"'
+run = 'echo "compiling for $usage_target"'
+
+[tasks.package]
+usage = 'flag "--target <target>"'
+depends = [{ task = "compile", args = ["--target", "{{usage.target}}"] }]
+run = 'echo "packaging for $usage_target"'
+EOF
+
+assert_contains "mise run package --target linux" "compiling for linux"
+assert_contains "mise run package --target linux" "packaging for linux"
+
+# Test with multiple args
+cat <<'EOF' >mise.toml
+[tasks.start-backend]
+usage = 'arg "<app>"'
+run = 'echo "backend {{usage.app}}"'
+
+[tasks.start-frontend]
+usage = 'arg "<app>"'
+run = 'echo "frontend {{usage.app}}"'
+
+[tasks.start]
+usage = 'arg "<app>"'
+depends = [
+    { task = "start-backend", args = ["{{usage.app}}"] },
+    { task = "start-frontend", args = ["{{usage.app}}"] },
+]
+run = 'echo "started {{usage.app}}"'
+EOF
+
+output=$(mise run start myapp 2>&1)
+assert_contains "echo \"$output\"" "backend myapp"
+assert_contains "echo \"$output\"" "frontend myapp"
+assert_contains "echo \"$output\"" "started myapp"
+
+# Test with string syntax for depends args
+cat <<'EOF' >mise.toml
+[tasks.greet]
+usage = 'arg "<name>"'
+run = 'echo "hello {{usage.name}}"'
+
+[tasks.welcome]
+usage = 'arg "<name>"'
+depends = ["greet {{usage.name}}"]
+run = 'echo "welcome {{usage.name}}"'
+EOF
+
+assert_contains "mise run welcome world" "hello world"
+assert_contains "mise run welcome world" "welcome world"
+
+# Test dependency chaining: A -> B -> C, args flow through
+cat <<'EOF' >mise.toml
+[tasks.step1]
+usage = 'arg "<val>"'
+run = 'echo "step1 {{usage.val}}"'
+
+[tasks.step2]
+usage = 'arg "<val>"'
+depends = [{ task = "step1", args = ["{{usage.val}}"] }]
+run = 'echo "step2 {{usage.val}}"'
+
+[tasks.step3]
+usage = 'arg "<val>"'
+depends = [{ task = "step2", args = ["{{usage.val}}"] }]
+run = 'echo "step3 {{usage.val}}"'
+EOF
+
+output=$(mise run step3 hello 2>&1)
+assert_contains "echo \"$output\"" "step1 hello"
+assert_contains "echo \"$output\"" "step2 hello"
+assert_contains "echo \"$output\"" "step3 hello"

src/cli/run.rs

@@ -324,6 +324,18 @@ impl Run {
                 task.args.extend(self.args_last.clone());
             }
         }
+
+        // Re-render dependency templates with parent task's usage arg/flag values.
+        // This enables patterns like: depends = ["child {{usage.app}}"]
+        for task in &mut task_list {
+            if !task.args.is_empty() {
+                let usage_values = crate::task::parse_usage_values_from_task(&config, task).await?;
+                if !usage_values.is_empty() {
+                    task.render_depends_with_usage(&config, &usage_values)
+                        .await?;
+                }
+            }
+        }
         time!("run get_task_lists");
 
         // Resolve transitive dependencies once upfront so we can:

src/task/deps.rs

@@ -1,5 +1,5 @@
 use crate::config::env_directive::EnvDirective;
-use crate::task::Task;
+use crate::task::{Task, dep_has_usage_ref, parse_usage_values_from_task};
 use crate::{config::Config, task::task_list::resolve_depends};
 use itertools::Itertools;
 use petgraph::Direction;
@@ -63,11 +63,27 @@ impl Deps {
             add_idx(t, &mut graph);
         }
         let all_tasks_to_run = resolve_depends(config, tasks).await?;
-        while let Some(a) = stack.pop() {
+        while let Some(mut a) = stack.pop() {
             if seen.contains(&a) {
                 // prevent infinite loop
                 continue;
             }
+            // If this task received args (from a parent dependency), re-render
+            // its dependency templates with usage values so {{usage.*}} resolves.
+            let has_usage_deps = |raw: &Option<Vec<_>>| {
+                raw.as_ref()
+                    .is_some_and(|r| r.iter().any(dep_has_usage_ref))
+            };
+            if !a.args.is_empty()
+                && (has_usage_deps(&a.depends_raw)
+                    || has_usage_deps(&a.depends_post_raw)
+                    || has_usage_deps(&a.wait_for_raw))
+            {
+                let usage_values = parse_usage_values_from_task(config, &a).await?;
+                if !usage_values.is_empty() {
+                    a.render_depends_with_usage(config, &usage_values).await?;
+                }
+            }
             let a_idx = add_idx(&a, &mut graph);
             let (pre, post) = a.resolve_depends(config, &all_tasks_to_run).await?;
             for b in pre {