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

[jdx]

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

[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

• 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)
• 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)
• All 563 unit tests pass

🤖 Generated with Claude Code

---

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.

^{Reviewed by Cursor Bugbot for commit 076b9c5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR introduces {{usage.*}} template interpolation inside depends, depends_post, and wait_for declarations, allowing parent task arguments to flow into their dependency tasks. The implementation uses a two-phase rendering strategy: dependencies with {{usage.*}} refs are deferred during initial config loading (in Task::render()), then resolved at runtime either from CLI args (in run.rs) or when a parent task passes args to a child (in Deps::new()). A new depends_raw / depends_post_raw / wait_for_raw trio stores the original templates so they can be re-rendered with the correct usage context later.

Key behaviors:

• dep_has_usage_ref() correctly strips whitespace before pattern-matching {{usage. to handle Tera's {{ usage.foo }} style without false positives
• parse_usage_values_from_task() parses a task's usage spec against its current args and emits a {name → value} map; keys are derived by stripping the usage_ env-var prefix from po.as_env() output
• Dependency chain propagation (A→B→C) is handled in Deps::new() by checking depends_raw for usage refs when a task has non-empty args, then calling render_depends_with_usage before graph edges are added
• String-syntax deps like \"build {{usage.app}}\" work because TaskDep::render() already splits a fully-rendered multi-token task string into a task name + args via shell_words
• E2E test covers positional args, flags, parallel fan-out, string syntax, and three-level chaining

Confidence Score: 5/5

Safe to merge — implementation is correct, prior review concerns have been addressed, and only minor P2 style suggestions remain.

All P0/P1 concerns from previous review threads have been resolved: dep_has_usage_ref now correctly strips whitespace and matches {{usage. as a unit (no false positives), debug logging was added on parse failure, and the has_usage_deps guard properly inspects raw dep lists rather than just checking Option::is_some(). The two remaining findings are P2: a double-rendering of non-usage deps that is functionally a no-op in all realistic cases, and a mildly fragile echo-based test assertion. The e2e coverage is thorough (positional args, flags, parallel fan-out, string syntax, three-level chain) and all 563 unit tests pass.

src/task/mod.rs (render_depends_with_usage re-renders all deps from raw); e2e/tasks/test_task_dep_args (echo "$output" assertion pattern)

Important Files Changed

Filename	Overview
src/task/mod.rs	Core of the feature: adds depends_raw/depends_post_raw/wait_for_raw fields, deferred rendering in render(), new render_depends_with_usage() method, dep_has_usage_ref() helper, and parse_usage_values_from_task(). Logic is sound; minor concern around rendering all deps (not just usage ones) from raw in render_depends_with_usage.
src/task/deps.rs	Adds usage-template re-rendering to Deps::new() before resolving edges; correctly checks raw dep lists for {{usage.*}} before calling parse_usage_values_from_task.
src/cli/run.rs	Adds a pre-Deps loop that re-renders top-level task deps with CLI-resolved usage values; straightforward integration with existing task_list flow.
e2e/tasks/test_task_dep_args	New E2E test covers positional args, flags, parallel deps, string syntax, and three-level chaining. Uses a slightly fragile pattern (assert_contains "echo "$output"") for parallel-task output capture.
docs/tasks/task-configuration.md	New documentation section for parent-to-dependency argument forwarding with clear examples for args, flags, string syntax, and chain propagation.
docs/tasks/task-arguments.md	Adds a cross-reference paragraph pointing users to the new depends-forwarding section; minimal, correct change.

Sequence Diagram

sequenceDiagram
    participant CLI as mise run deploy myapp
    participant Run as run.rs
    participant TaskList as get_task_lists()
    participant Mod as Task::render()
    participant RDU as render_depends_with_usage()
    participant Deps as Deps::new()
    participant Resolve as resolve_depends()

    CLI->>Run: task="deploy", args=["myapp"]
    Run->>TaskList: get_task_lists(skip_deps=false)
    TaskList->>Mod: task.render() for each task
    Note over Mod: Saves depends_raw/depends_post_raw/wait_for_raw<br/>Defers deps with {{usage.*}} — renders rest
    Mod-->>TaskList: tasks with deferred usage deps
    TaskList-->>Run: task_list=[deploy(args=["myapp"])]

    Run->>Run: For each task with args in task_list
    Run->>Mod: parse_usage_values_from_task(deploy)<br/>→ {"app": "myapp"}
    Run->>RDU: deploy.render_depends_with_usage({"app":"myapp"})
    Note over RDU: Restores from depends_raw<br/>Renders "build {{usage.app}}" → task="build", args=["myapp"]
    RDU-->>Run: deploy.depends = [build(args=["myapp"])]

    Run->>Resolve: resolve_depends(task_list)
    Resolve-->>Run: resolved_tasks

    Run->>Deps: Deps::new(resolved_tasks)
    loop For each task popped from stack
        Deps->>Deps: has_usage_deps(task.depends_raw)?
        alt task has args AND raw usage deps
            Deps->>Mod: parse_usage_values_from_task(build)<br/>→ {"app": "myapp"}
            Deps->>RDU: build.render_depends_with_usage({"app":"myapp"})
        end
        Deps->>Resolve: task.resolve_depends() — filters remaining {{usage.*}} deps
        Deps->>Deps: add edges to graph
    end
    Deps-->>Run: dependency graph built

Loading

_{Reviews (3): Last reviewed commit: "[autofix.ci] apply automated fixes (atte..." | Re-trigger Greptile}

[gemini-code-assist]

Code Review

This pull request enables passing arguments and flags from a parent task to its dependencies using {{usage.*}} templates. It implements deferred rendering for dependency templates containing usage references, ensuring they are resolved only after the parent task's arguments are available. The changes include updates to the task model to store raw templates, logic in the CLI and dependency resolver to trigger re-rendering, and a new E2E test suite. Review feedback suggests simplifying the Tera context insertion by leveraging direct serialization and broadening the template reference detection to support a wider range of Tera syntax.

[gemini-code-assist]

The manual conversion of usage_values to a HashMap<String, tera::Value> is unnecessary. Tera's Context::insert can directly handle any type that implements serde::Serialize, and IndexMap<String, String> already does. This simplification avoids redundant allocations and cloning.

Suggested change

	let usage_ctx: HashMap<String, tera::Value> = usage_values
	.iter()
	.map(|(k, v)| (k.clone(), tera::Value::String(v.clone())))
	.collect();
	tera_ctx.insert("usage", usage_values);

[gemini-code-assist]

The heuristic for detecting usage references in dependency templates is a bit narrow. It currently only checks for {{ tags and dot notation (e.g., usage.app). Tera also supports statement tags ({% ... %}) and bracket notation (e.g., usage['app']). Expanding this check will make the deferred rendering more robust for complex templates.

Suggested change

	let has_ref = |s: &str| s.contains("{{") && s.contains("usage.");
	let has_ref = |s: &str| {
	(s.contains("{{") || s.contains("{%") || s.contains("{#"))
	&& (s.contains("usage.") || s.contains("usage["))
	};

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3f32496. Configure here.}

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.3 x -- echo	22.4 ± 0.4	21.6	24.9	1.00
mise x -- echo	22.9 ± 0.5	22.1	26.5	1.02 ± 0.03

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.3 env	22.0 ± 0.7	21.1	27.1	1.00
mise env	22.7 ± 0.6	21.7	26.0	1.03 ± 0.04

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.3 hook-env	22.8 ± 0.5	21.8	24.8	1.00
mise hook-env	23.4 ± 0.6	22.3	25.7	1.03 ± 0.03

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.3 ls	19.8 ± 0.4	19.1	21.9	1.00
mise ls	20.6 ± 0.5	19.5	23.3	1.04 ± 0.03

xtasks/test/perf

Command	mise-2026.4.3	mise	Variance
install (cached)	149ms	149ms	+0%
ls (cached)	79ms	78ms	+1%
bin-paths (cached)	83ms	83ms	+0%
task-ls (cached)	806ms	804ms	+0%