pi-prompt-template-model 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-03-20
+
+### Added
+- Added delegated prompt execution via direct extension event bus communication with `subagent` (`prompt-template:subagent:*` channels), including delegated custom-message persistence for loop summaries and context carry-forward.
+- Added prompt frontmatter support for `subagent` and `inheritContext`, with `inheritContext: true` mapped to delegated fork context.
+- Fork context preamble is handled by the subagent extension directly (via `DEFAULT_FORK_PREAMBLE` in `types.ts`), applying to all fork-context subagent runs universally.
+- Added runtime delegation override flags: `--subagent`, `--subagent=<name>`, and `--subagent:<name>`.
+- Added live progress widget above editor during delegated subagent runs showing elapsed time, tool count, tokens, current tool, and task preview — matching the native subagent tool card layout.
+- Added styled completion card with task preview, tool call history, expandable output (Ctrl+O), and usage stats footer.
+
+### Changed
+- Updated provider priority for ambiguous bare model IDs to prefer `openai-codex` before `anthropic`, `github-copilot`, and `openrouter`.
+- Updated loop convergence and fresh-summary analysis to account for delegated subagent message payloads.
+
+### Fixed
+- Delegated start-time hangs now fail fast with explicit timeout errors when a subagent run never emits a start signal.
+- Delegated runs no longer treat arbitrary escape-sequence-bearing terminal input as an Esc cancellation signal; only literal Esc cancels.
+- Chain and loop restore paths now use live runtime model/thinking state during cleanup, preventing skipped restore on mid-step failures.
+
+## [0.6.0] - 2026-03-19
+
+### Changed
+
+- Clarified the README chain examples so the optional ` -- ` shared-args separator is clearly distinct from loop flags like `--loop`, `--fresh`, and `--no-converge`.
+- Clarified in the README that chain frontmatter declarations support per-step `--loop N` inside the `chain:` value.
+- Argument substitution now accepts `@$` as an alias for `$@` for compatibility with commonly-typed placeholder variants.
+- Skill injection now uses a next-turn context message from `before_agent_start` instead of mutating the turn system prompt.
+- Non-chain templates can now omit `model` and inherit the current session model, so inline `<if-model ...>` rendering and skill injection still work without explicit model frontmatter.
+- Chain steps without `model` now inherit a fixed chain-start model snapshot, so model-less chain steps behave as if that model were declared in frontmatter while remaining deterministic across step switches.
+
+### Fixed
+
+- Chain step execution now avoids implicit previous-step model bleed for model-less templates by resolving them against the chain-start model snapshot instead of whichever model was active after the prior step.
+- Model-less prompt loading now skips plain templates that do not use extension features, preventing command collisions with other extension commands like `/review` and `/handover`.
+- Model-less prompt loading now also ignores no-op/invalid-only extension metadata (for example `restore`-only or invalid loop flags), so ineffective frontmatter does not unnecessarily claim command names.
+- Model-less prompt loading now recognizes invalid conditional closers like `</else>` as extension-relevant markup, so those templates stay in this extension path and surface proper conditional-parse warnings instead of silently bypassing extension handling.
+- Model-less prompt execution now tracks runtime model changes (`model_select` + internal switches/restores) and uses that tracked model instead of potentially stale command-context snapshots.
+- Prompt commands now fail fast when a configured `skill` file is missing or unreadable, instead of silently sending the prompt without skill context.
+- Skill resolution now returns a typed success/error outcome that callers handle explicitly, rather than emitting notifications from inside the resolver and returning sentinel `null` values.
+- Session start/switch now clear any queued skill context message so stale pending skill payloads cannot leak across session boundaries.
+- Session start/switch now also clear pending single-command restore state (`previousModel`/`previousThinking`) so restore writes cannot leak into a different session.
+- Skill frontmatter resolution now checks registered skill commands first (`pi.getCommands()` skill entries), accepts both `<name>` and `skill:<name>` values, searches additional standard pi skill locations (`.agents/skills` in project ancestors and `~/.agents/skills`), supports direct `<skill>.md` files alongside `SKILL.md` directories, and rejects traversal-like skill names for path fallback.
+- `extractLoopCount()` now strips repeated unquoted `--loop` tokens once looping is active, preventing stray loop flags from leaking into prompt arguments.
+- Chain frontmatter step parsing now strips repeated per-step `--loop` tokens once a valid per-step loop is resolved, and keeps the first valid value (including mixed invalid/valid numeric sequences like `--loop 1000 --loop 2`).
+- Loop-mode restore now tracks runtime model/thinking state per iteration instead of relying on command-context model snapshots, so model restoration remains correct even when command context values are stale.
+- Chain execution now restores model/thinking state in a `finally` path, so restore still runs after unexpected runtime errors during a chain step and chain cleanup state is still reset even when restore itself fails.
+- Loop and chain executions no longer report `Loop finished`/`Loop converged` when runtime errors abort execution mid-loop.
+- Loop and chain error propagation now preserves thrown falsy values (for example `throw 0`) instead of treating them as success, preventing swallowed errors and false completion notifications.
+
 ## [0.5.0] - 2026-03-17
 
 ### Added

package/README.md

@@ -15,7 +15,7 @@
 │  /debug-python  ──►  Extension detects model + skill                        │
 │       │                                                                     │
 │       ▼                                                                     │
-│  Switches to Sonnet  ──►  Injects tmux skill into system prompt             │
+│  Switches to Sonnet  ──►  Queues tmux skill context for next turn           │
 │       │                                                                     │
 │       ▼                                                                     │
 │  Agent responds with Sonnet + tmux expertise                                │
@@ -47,9 +47,17 @@ pi install npm:pi-prompt-template-model
 
 Restart pi to load the extension.
 
+For delegated subagent execution (`subagent` and `inheritContext` frontmatter), install [pi-subagents](https://github.com/nicobailon/pi-subagents/) separately:
+
+```bash
+pi install npm:pi-subagents
+```
+
+pi-subagents is optional — everything else works without it. If you use `subagent: true` in a prompt template without pi-subagents installed, execution fails fast with a clear error.
+
 ## Quick Start
 
-Add `model` and optionally `skill` to any prompt template:
+Add `model` (or omit it to inherit the current session model) and optionally `skill` to any prompt template:
 
 ```markdown
 ---
@@ -80,16 +88,56 @@ skill: surf
 $@
 ```
 
-Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its content directly into the system prompt before the agent even sees your task. No decision-making, no read tool, just immediate expertise. It's a forcing function for when you know exactly what workflow the agent needs.
+Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its content as a context message on the next turn before the agent handles your task. No decision-making, no read tool, just immediate expertise. It's a forcing function for when you know exactly what workflow the agent needs.
+
+## Delegated Subagent Execution
+
+You can delegate a prompt template directly to the `subagent` extension without metaprompted tool-call instructions.
+
+```markdown
+---
+model: anthropic/claude-sonnet-4-20250514
+subagent: true
+---
+Review and simplify this code: $@
+```
+
+`subagent: true` uses the default `worker` agent. To target a specific agent, set a string value:
+
+```markdown
+---
+model: anthropic/claude-sonnet-4-20250514
+subagent: reviewer
+inheritContext: true
+---
+Audit this diff for correctness and edge cases: $@
+```
+
+`inheritContext: true` maps to delegated `context: "fork"`. It is valid only when `subagent` is configured.
+
+Forked subagents receive a default preamble (from the subagent extension's `DEFAULT_FORK_PREAMBLE`) that anchors them to the task and prevents them from continuing the parent conversation.
+
+During execution, a live progress widget appears above the editor showing elapsed time, tool count, token usage, and the current/last tool — matching the native subagent tool card layout. The widget updates in real-time and clears when the run completes, replaced by a styled completion card with task preview, tool call history, output, and usage stats.
+
+You can override delegation at runtime per invocation:
+
+- `--subagent`
+- `--subagent=<name>`
+- `--subagent:<name>`
+
+Runtime flags take precedence for that invocation only. Bare `--subagent` keeps template agent when present, otherwise defaults to `worker`.
 
 ## Frontmatter Fields
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
-| `model` | Conditional | - | Required for non-chain templates; ignored when `chain` is set |
+| `model` | No | `current` | Target model(s). If omitted on a non-chain template, execution inherits the current session model. Ignored when `chain` is set. |
 | `chain` | Conditional | - | Chain declaration (`step -> step --loop 2`) for orchestration templates; body is ignored |
-| `skill` | No | - | Skill name to inject into system prompt |
+| `skill` | No | - | Skill name to inject as next-turn context message |
 | `thinking` | No | - | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `subagent` | No | - | Delegate execution to subagent mode (`true` for default `worker`, or explicit agent name string) |
+| `inheritContext` | No | `false` | Only with `subagent`; when `true`, delegates with subagent `context: "fork"` |
+
 | `description` | No | - | Shown in autocomplete |
 | `restore` | No | `true` | Restore previous model and thinking level after response |
 | `fresh` | No | `false` | Collapse context between loop iterations (applies when looping via `--loop` or frontmatter `loop`) |
@@ -153,7 +201,7 @@ Do a deeper pass and call out subtle risks.
 </if-model>
 ```
 
-Conditionals are evaluated against the model that actually runs the command after fallback resolution. That means the same template can render differently depending on which candidate was selected.
+Conditionals are evaluated against the model that actually runs the command. For fallback prompts, that means after candidate resolution; for prompts without `model`, that means the current session model. The same template can render differently depending on which model is active.
 
 Supported matches inside `is="..."`:
 
@@ -183,6 +231,7 @@ Prompt bodies support argument placeholders that expand to command arguments:
 |-------------|-------------|
 | `$1`, `$2`, ... | Positional argument (1-indexed) |
 | `$@` | All arguments joined with spaces |
+| `@$` | Alias for `$@` |
 | `$ARGUMENTS` | Same as `$@` |
 | `${@:N}` | All arguments from position N onward |
 | `${@:N:L}` | L arguments starting from position N |
@@ -203,17 +252,22 @@ Running `/analyze src/main.ts performance edge cases error handling` expands to:
 
 ## Skill Resolution
 
-The `skill` field matches the skill's directory name:
+The `skill` field accepts either a bare skill name or a slash-command style name:
 
 ```yaml
 skill: tmux
+# also valid
+skill: skill:tmux
 ```
 
-Resolves to (checked in order):
-1. `<cwd>/.pi/skills/tmux/SKILL.md` (project)
-2. `~/.pi/agent/skills/tmux/SKILL.md` (user)
+Resolution order:
+1. Registered skill commands from `pi.getCommands()` (`source: "skill"`), matched by `skill:name` or `name`
+2. `<cwd>/.pi/skills/<name>/SKILL.md` or `<cwd>/.pi/skills/<name>.md`
+3. `.agents/skills` in `cwd` and ancestor directories (up to git repo root)
+4. `~/.pi/agent/skills/<name>/SKILL.md` or `~/.pi/agent/skills/<name>.md`
+5. `~/.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>.md`
 
-This matches pi's precedence - project skills override user skills.
+If the configured skill file is missing or unreadable, the command fails fast and does not send the prompt body to the model.
 
 ## Subdirectories
 
@@ -310,13 +364,13 @@ Switched to Haiku. How can I help?
 
 ## Chaining Templates
 
-The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model, renders any inline model conditionals against that step’s resolved model, injects its own skill, and the conversation context carries forward between steps.
+The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model (or, if the step has no `model`, to the chain-start model snapshot), renders inline model conditionals against that resolved step model, injects its own skill context message, and conversation context carries forward between steps.
 
 ```
 /chain-prompts analyze-code -> fix-plan -> summarize -- src/main.ts
 ```
 
-This runs `analyze-code` first, then `fix-plan` (which sees the analysis in conversation context), then `summarize`. The `-- src/main.ts` provides shared args substituted into every template's `$@`.
+This runs `analyze-code` first, then `fix-plan` (which sees the analysis in conversation context), then `summarize`. The ` -- src/main.ts` part is optional. The literal ` -- ` separator means "shared args start here": everything after it is passed to each step as `$@`, unless that step already has its own inline args.
 
 Each step can also receive its own args, overriding the shared args for that step:
 
@@ -348,7 +402,7 @@ chain: double-check --loop 2 -> deslop --loop 2
 ignored — chain templates don't use the body
 ```
 
-This registers `/review-then-clean` as a command that runs `double-check` twice, then `deslop` twice. Each step references a separate prompt template with its own `model`. The chain template itself doesn't need a `model` field — each step uses whatever model its template specifies.
+This registers `/review-then-clean` as a command that runs `double-check` twice, then `deslop` twice. Each step references a separate prompt template. Steps with `model` use their configured model; steps without `model` inherit the chain-start model snapshot (the model active when the chain command began), so behavior stays deterministic even if earlier steps switch models.
 
 Per-step `--loop N` repeats that step N times before moving to the next. Per-step convergence applies: if a step makes no file changes on an iteration, its inner loop stops early (unless the step's template has `converge: false`).
 
@@ -440,14 +494,15 @@ Review the codebase and improve code quality. $@
 Chains support the same looping forms:
 
 ```
+/chain-prompts analyze -> fix --loop 3
+/chain-prompts analyze -> fix --loop=3
+/chain-prompts analyze -> fix --loop
+/chain-prompts analyze -> fix --loop 3 --fresh
+/chain-prompts analyze -> fix --loop 3 --no-converge
 /chain-prompts analyze -> fix --loop 3 -- src/main.ts
-/chain-prompts analyze -> fix --loop=3 -- src/main.ts
-/chain-prompts analyze -> fix --loop -- src/main.ts
-/chain-prompts analyze -> fix --loop 3 --fresh -- src/main.ts
-/chain-prompts analyze -> fix --loop 3 --no-converge -- src/main.ts
 ```
 
-This runs the full chain (analyze → fix) three times. Convergence detection applies across all steps in each iteration — if no step made file changes, the loop stops. Each iteration re-reads prompts from disk, so template edits take effect between iterations. The status bar shows `loop 2/3` during execution.
+This runs the full chain (analyze → fix) three times. The final example adds optional shared args: ` -- src/main.ts` means "pass `src/main.ts` to any step that doesn't already have its own args." If you don't need shared args, leave that part out entirely. Convergence detection applies across all steps in each iteration — if no step made file changes, the loop stops. Each iteration re-reads prompts from disk, so template edits take effect between iterations. The status bar shows `loop 2/3` during execution. Chain frontmatter declarations also support per-step `--loop N` inside the `chain:` value (for example `chain: double-check --loop 3 -> simplify -> deslop`).
 
 ## Agent Tool
 
@@ -462,6 +517,8 @@ Once enabled, the agent sees `run-prompt` in its tool list and can call it with
 ```
 run-prompt({ command: "deslop --loop 5 --fresh" })
 run-prompt({ command: "deslop --loop" })
+run-prompt({ command: "deslop --subagent" })
+run-prompt({ command: "deslop --subagent:reviewer" })
 run-prompt({ command: "chain-prompts analyze -> fix --loop 3" })
 ```
 
@@ -499,11 +556,13 @@ These commands work in print mode too:
 pi -p "/debug-python my code crashes on line 42"
 ```
 
-The model switches, skill injects, agent responds, and output prints to stdout. Useful for scripting or piping to other tools.
+The model switches, a skill context message is injected, the agent responds, and output prints to stdout. Useful for scripting or piping to other tools.
 
 ## Limitations
 
 - Prompt files are reloaded on session start and whenever an extension-owned prompt command runs. If you add a brand-new prompt file while already inside a session, run another extension-owned command such as `/chain-prompts`, start a new session, or reload pi so the new slash command is registered.
 - Model restore state is in-memory. Closing pi mid-response loses restore state.
-- Chain steps must reference templates with a `model` field. Chain templates themselves use `chain` and do not execute their own body.
+- Model-less templates are only managed by this extension when they use extension features (for example `skill`, `thinking`, loop flags, or inline `<if-model ...>`). Plain prompt templates without extension features stay with pi's default prompt loader to avoid command conflicts.
+- In chains, model-less steps inherit the chain-start model snapshot, not the immediately previous step model. This is intentional for deterministic behavior.
+- Delegated `subagent` prompts require [pi-subagents](https://github.com/nicobailon/pi-subagents/) (`pi install npm:pi-subagents`).
 - The `run-prompt` tool must be explicitly enabled with `/prompt-tool on` before the agent can use it.

package/args.ts

@@ -11,12 +11,23 @@ export interface LoopFlags {
 	converge: boolean;
 }
 
+export interface SubagentOverride {
+	enabled: true;
+	agent?: string;
+}
+
+export interface SubagentOverrideExtraction {
+	args: string;
+	override?: SubagentOverride;
+}
+
 export function extractLoopCount(argsString: string): LoopExtraction | null {
 	let loopCount: number | null = null;
 	let loopFound = false;
 	let fresh = false;
 	let noConverge = false;
 	const tokensToRemove: Array<{ start: number; end: number }> = [];
+	const loopTokenRanges: Array<{ start: number; end: number }> = [];
 
 	let i = 0;
 	while (i < argsString.length) {
@@ -39,45 +50,46 @@ export function extractLoopCount(argsString: string): LoopExtraction | null {
 		while (i < argsString.length && !/\s/.test(argsString[i])) i++;
 		const token = argsString.slice(tokenStart, i);
 
-		if (!loopFound && (token === "--loop" || token.startsWith("--loop="))) {
-			if (token.startsWith("--loop=")) {
-				const value = token.slice("--loop=".length);
-				if (/^\d+$/.test(value)) {
-					const parsed = parseInt(value, 10);
-					if (parsed >= 1 && parsed <= 999) {
-						loopFound = true;
-						loopCount = parsed;
-						tokensToRemove.push({ start: tokenStart, end: i });
-					}
+		if (token.startsWith("--loop=")) {
+			loopTokenRanges.push({ start: tokenStart, end: i });
+			const value = token.slice("--loop=".length);
+			if (/^\d+$/.test(value)) {
+				const parsed = parseInt(value, 10);
+				if (parsed >= 1 && parsed <= 999 && !loopFound) {
+					loopFound = true;
+					loopCount = parsed;
 				}
-			} else {
-				let lookahead = i;
-				while (lookahead < argsString.length && /\s/.test(argsString[lookahead])) lookahead++;
-
-				if (lookahead < argsString.length && argsString[lookahead] !== '"' && argsString[lookahead] !== "'") {
-					const nextTokenStart = lookahead;
-					while (lookahead < argsString.length && !/\s/.test(argsString[lookahead])) lookahead++;
-					const nextToken = argsString.slice(nextTokenStart, lookahead);
-
-					if (/^\d+$/.test(nextToken)) {
-						const parsed = parseInt(nextToken, 10);
-						if (parsed >= 1 && parsed <= 999) {
-							loopFound = true;
-							loopCount = parsed;
-							tokensToRemove.push({ start: tokenStart, end: i }, { start: nextTokenStart, end: lookahead });
-							i = lookahead;
-						}
-					} else {
+			}
+			continue;
+		}
+
+		if (token === "--loop") {
+			let lookahead = i;
+			while (lookahead < argsString.length && /\s/.test(argsString[lookahead])) lookahead++;
+
+			if (lookahead < argsString.length && argsString[lookahead] !== '"' && argsString[lookahead] !== "'") {
+				const nextTokenStart = lookahead;
+				while (lookahead < argsString.length && !/\s/.test(argsString[lookahead])) lookahead++;
+				const nextToken = argsString.slice(nextTokenStart, lookahead);
+
+				if (/^\d+$/.test(nextToken)) {
+					loopTokenRanges.push({ start: tokenStart, end: i }, { start: nextTokenStart, end: lookahead });
+					const parsed = parseInt(nextToken, 10);
+					if (parsed >= 1 && parsed <= 999 && !loopFound) {
 						loopFound = true;
-						loopCount = null;
-						tokensToRemove.push({ start: tokenStart, end: i });
+						loopCount = parsed;
 					}
-				} else {
-					loopFound = true;
-					loopCount = null;
-					tokensToRemove.push({ start: tokenStart, end: i });
+					i = lookahead;
+					continue;
 				}
 			}
+
+			loopTokenRanges.push({ start: tokenStart, end: i });
+			if (!loopFound) {
+				loopFound = true;
+				loopCount = null;
+			}
+			continue;
 		}
 
 		if (token === "--fresh") {
@@ -91,15 +103,16 @@ export function extractLoopCount(argsString: string): LoopExtraction | null {
 		}
 	}
 
-	if (loopCount === null && !loopFound) return null;
+	if (!loopFound) return null;
 
-	tokensToRemove.sort((a, b) => b.start - a.start);
+	const allRanges = [...tokensToRemove, ...loopTokenRanges];
+	allRanges.sort((a, b) => b.start - a.start);
 	let cleaned = argsString;
-	for (const { start, end } of tokensToRemove) {
+	for (const { start, end } of allRanges) {
 		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
 	}
 
-	const converge = loopFound && loopCount === null ? true : !noConverge;
+	const converge = loopCount === null ? true : !noConverge;
 	return { args: cleaned.trim(), loopCount, fresh, converge };
 }
 
@@ -149,6 +162,58 @@ export function extractLoopFlags(argsString: string): LoopFlags {
 	return { args: cleaned.trim(), fresh, converge: !noConverge };
 }
 
+export function extractSubagentOverride(argsString: string): SubagentOverrideExtraction {
+	let override: SubagentOverride | undefined;
+	const tokensToRemove: Array<{ start: number; end: number }> = [];
+
+	let i = 0;
+	while (i < argsString.length) {
+		const char = argsString[i];
+
+		if (char === '"' || char === "'") {
+			const quote = char;
+			i++;
+			while (i < argsString.length && argsString[i] !== quote) i++;
+			if (i < argsString.length) i++;
+			continue;
+		}
+
+		if (/\s/.test(char)) {
+			i++;
+			continue;
+		}
+
+		const tokenStart = i;
+		while (i < argsString.length && !/\s/.test(argsString[i])) i++;
+		const token = argsString.slice(tokenStart, i);
+
+		if (token === "--subagent") {
+			tokensToRemove.push({ start: tokenStart, end: i });
+			override = { enabled: true };
+			continue;
+		}
+
+		if (token.startsWith("--subagent=") || token.startsWith("--subagent:")) {
+			tokensToRemove.push({ start: tokenStart, end: i });
+			const value = token.includes("=") ? token.slice("--subagent=".length) : token.slice("--subagent:".length);
+			override = value ? { enabled: true, agent: value } : { enabled: true };
+		}
+	}
+
+	if (!override) return { args: argsString.trim() };
+
+	tokensToRemove.sort((a, b) => b.start - a.start);
+	let cleaned = argsString;
+	for (const { start, end } of tokensToRemove) {
+		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
+	}
+
+	return {
+		args: cleaned.trim(),
+		override,
+	};
+}
+
 export function splitByUnquotedSeparator(input: string, separator: string): string[] {
 	const parts: string[] = [];
 	let start = 0;
@@ -227,6 +292,7 @@ export function substituteArgs(content: string, args: string[]): string {
 	const allArgs = args.join(" ");
 	result = result.replace(/\$ARGUMENTS/g, allArgs);
 	result = result.replace(/\$@/g, allArgs);
+	result = result.replace(/@\$/g, allArgs);
 
 	return result;
 }

package/chain-parser.ts

@@ -76,19 +76,20 @@ function scanSegmentTokens(segment: string): SegmentToken[] {
 
 function extractStepLoopCount(segment: string): { cleanedSegment: string; loopCount?: number } {
 	const tokens = scanSegmentTokens(segment);
+	const loopTokenRanges: Array<{ start: number; end: number }> = [];
+	let loopCount: number | undefined;
 
 	for (let i = 1; i < tokens.length; i++) {
 		const token = tokens[i];
 		if (token.quoted) continue;
 
 		if (token.value.startsWith("--loop=")) {
+			loopTokenRanges.push({ start: token.start, end: token.end });
 			const value = token.value.slice("--loop=".length);
-			if (/^\d+$/.test(value)) {
-				const parsed = parseInt(value, 10);
-				if (parsed >= 1 && parsed <= 999) {
-					const cleanedSegment = `${segment.slice(0, token.start)}${segment.slice(token.end)}`.trim();
-					return { cleanedSegment, loopCount: parsed };
-				}
+			if (!/^\d+$/.test(value)) continue;
+			const parsed = parseInt(value, 10);
+			if (parsed >= 1 && parsed <= 999 && loopCount === undefined) {
+				loopCount = parsed;
 			}
 			continue;
 		}
@@ -96,16 +97,28 @@ function extractStepLoopCount(segment: string): { cleanedSegment: string; loopCo
 		if (token.value === "--loop" && i + 1 < tokens.length) {
 			const next = tokens[i + 1];
 			if (!next.quoted && /^\d+$/.test(next.value)) {
+				loopTokenRanges.push({ start: token.start, end: token.end }, { start: next.start, end: next.end });
 				const parsed = parseInt(next.value, 10);
-				if (parsed >= 1 && parsed <= 999) {
-					const cleanedSegment = `${segment.slice(0, token.start)}${segment.slice(next.end)}`.trim();
-					return { cleanedSegment, loopCount: parsed };
+				if (parsed >= 1 && parsed <= 999 && loopCount === undefined) {
+					loopCount = parsed;
 				}
+				i++;
+				continue;
 			}
 		}
 	}
 
-	return { cleanedSegment: segment };
+	if (loopCount === undefined || loopTokenRanges.length === 0) {
+		return { cleanedSegment: segment };
+	}
+
+	loopTokenRanges.sort((a, b) => b.start - a.start);
+	let cleanedSegment = segment;
+	for (const { start, end } of loopTokenRanges) {
+		cleanedSegment = `${cleanedSegment.slice(0, start)}${cleanedSegment.slice(end)}`;
+	}
+
+	return { cleanedSegment: cleanedSegment.trim(), loopCount };
 }
 
 export function parseChainSteps(args: string): ParsedChainSteps {
@@ -122,12 +135,13 @@ export function parseChainSteps(args: string): ParsedChainSteps {
 			invalidSegments.push(rawSegment);
 			continue;
 		}
-		const tokens = parseCommandArgs(segment);
+		const { cleanedSegment, loopCount } = extractStepLoopCount(segment);
+		const tokens = parseCommandArgs(cleanedSegment);
 		if (tokens.length === 0) {
 			invalidSegments.push(segment);
 			continue;
 		}
-		steps.push({ name: tokens[0], args: tokens.slice(1) });
+		steps.push({ name: tokens[0], args: tokens.slice(1), loopCount });
 	}
 
 	return { steps, sharedArgs: parseCommandArgs(argsPart), invalidSegments };