refactor: rename session_command to command_expansion

AGENTS.md

@@ -64,9 +64,10 @@ packages/opencode/.opencode/ # Generated OpenCode output for review
 - For navigator-style commands, separate context loading, blocker checks, delegated execution, and final reporting into distinct workflow subsections so the control flow is easy to follow
 - Prefer explicit subsection names like `### Load ... Context`, `### Check Blockers`, `### Delegate ...`, and `### Mark Complete And Loop` when the command coordinates multiple phases or subagents
 - Treat loader tools and provided attachments as the source of truth for orchestration inputs; avoid extra exploratory commands when an existing tool result already answers the question
-- Before dispatching a same-session command step, say what result should be stored and whether the workflow must stop, pause, or continue based on that result
-- Use literal `<session_command>` tags when the workflow must queue exact text through `session_command`; `agent` and `command` are required, and the block body is the exact rendered body to send for that command
-- Do not use `<task>` blocks in command docs; author navigator delegation with `<session_command>` blocks only
+- Before dispatching a same-session command step, say what delegated result should be stored and whether the workflow must stop, pause, or continue based on that result
+- Use literal `<delegate>` tags when the workflow must delegate exact text through `command_expansion`; `agent` and `command` are required, and the block body is the exact rendered body to send for that command
+- Do not use `<task>` blocks in command docs; author navigator delegation with `<delegate>` blocks only
+- Do not restate `command_expansion` or `task` mechanics inside command docs; navigator owns that execution flow
 - When a command can pause for approval or loop over repeated work, describe the resume condition and the exact cases that must STOP without mutating state
 - Use `## Additional Context` for instructions about how optional guidance, related tickets, focus areas, or other stored context should influence analysis and response formatting
 - Use `### Output` as the final workflow step to define the exact user-facing response shape, including placeholders for generated values
@@ -107,24 +108,25 @@ $ARGUMENTS
 
 ### Delegate Planning
 
-<session_command agent="planner" command="ticket/plan">
+<delegate agent="planner" command="ticket/plan">
 
 Task: <task>
 Task context: <task-context>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the result as `<plan>`
+- Store the delegated result as `<plan>`
 - STOP if planning is blocked or unusable
 
 ### Delegate Implementation
 
-<session_command agent="worker" command="dev">
+<delegate agent="worker" command="dev">
 
 Plan: <plan>
 Constraints: <additional-context>
-</session_command>
+</delegate>
 
+- Store the delegated result as `<implementation-result>`
 - STOP if implementation is blocked or incomplete
 
 ### Output
@@ -136,13 +138,13 @@ Constraints: <additional-context>
 Example delegation rule:
 
 ```text
-Before dispatching, write the exact `<session_command ...>...</session_command>` block, say what queue acknowledgement should be stored, and whether the workflow should continue or STOP based on that acknowledgement.
+Before delegation, write the exact `<delegate ...>...</delegate>` block, say what delegated result should be stored, and whether the workflow should continue or STOP based on that result.
 ```
 
 Example literal session command rule:
 
 ```text
-Before literal command forwarding, write the exact `<session_command ...>...</session_command>` block, then call `session_command` with the rendered body, exact `agent`, and exact `command`, and say what queue acknowledgement should be stored and whether the workflow should continue or STOP based on that acknowledgement.
+Before literal command forwarding, write the exact `<delegate ...>...</delegate>` block, then let navigator expand and execute it, and say what delegated result should be stored and whether the workflow should continue or STOP based on that result.
 ```
 
 ## Component Authoring

README.md

@@ -20,7 +20,7 @@ Kompass keeps AI coding agents on course with token-efficient, composable workfl
 
 - Commands cover direct work (`/ask`, `/commit`, `/merge`), orchestration (`/dev`, `/ship`, `/todo`), ticket planning/sync, and PR review/shipping flows.
 - Agents are intentionally narrow: `worker` is generic, `planner` is no-edit planning, `navigator` owns multi-step orchestration, and `reviewer` is a no-edit review specialist.
-- Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `session_command` (resolve a slash command and queue it into the current session), `pr_load`, `pr_sync`, `ticket_load`, `ticket_sync`.
+- Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `command_expansion` (resolve a slash command and return the expanded prompt for immediate delegation), `pr_load`, `pr_sync`, `ticket_load`, `ticket_sync`.
 - Reusable command-template components live in `packages/core/components/` and are documented in the components reference.
 
 ## Installation

kompass.jsonc

@@ -41,7 +41,7 @@
 
   "tools": {
     "changes_load": { "enabled": true },
-    "session_command": { "enabled": true },
+    "command_expansion": { "enabled": true },
     "pr_load": { "enabled": true },
     "pr_sync": { "enabled": true },
     "ticket_load": { "enabled": true },

kompass.schema.json

@@ -184,7 +184,7 @@
         "changes_load": {
           "$ref": "#/$defs/toolConfig"
         },
-        "session_command": {
+        "command_expansion": {
           "$ref": "#/$defs/toolConfig"
         },
         "pr_load": {
@@ -361,7 +361,7 @@
       "type": "string",
       "enum": [
         "changes_load",
-        "session_command",
+        "command_expansion",
         "pr_load",
         "pr_sync",
         "ticket_sync",

packages/core/agents/navigator.md

@@ -8,14 +8,22 @@ You coordinate structured, multi-step workflows.
 - Execute required user-interaction steps exactly as the command defines them; if a required interaction tool is unavailable, use the command's non-interactive fallback.
 - If a step is blocked, incomplete, or fails, stop and report it clearly.
 
-## Session Commands
-
-- Treat each `<session_command agent="AGENT_NAME" command="COMMAND_NAME">...</session_command>` block as literal input.
-- Render variables, then call `session_command` with `command` set to the tag value, `body` set to the rendered block body, and `agent` set to the tag value.
-- `session_command` queues the next same-session user turn and returns immediately; it does not wait for the queued command result.
-- Do not rewrite or interpret the block body; preserve line breaks and ordering.
-- Run `session_command` blocks sequentially unless the workflow clearly makes them independent.
-- If a `session_command` block is malformed, report it as invalid and continue with remaining valid blocks when safe.
+## Delegation
+
+When you see a `<delegate agent="AGENT_NAME" command="COMMAND_NAME">...</delegate>` block, you MUST make TWO tool calls in sequence:
+
+1. **Expand**: Call `command_expansion` with `command` from the tag and `body` set to the rendered block content
+2. **Delegate**: IMMEDIATELY call `task` with `subagent_type: AGENT_NAME` and `prompt` set to the expanded text from step 1
+
+**CRITICAL RULES:**
+- These are TWO SEPARATE tool calls. You must call BOTH.
+- DO NOT execute the expanded content yourself. Your job is to DELEGATE via `task`.
+- The `task` result IS the delegated result. Use it as the source of truth.
+- If you don't call `task`, the delegation is incomplete and will fail.
+
+- Treat each `<delegate>` block as literal input; do not rewrite or interpret before expansion.
+- Run `<delegate>` blocks sequentially unless the workflow clearly makes them independent.
+- If a `<delegate>` block is malformed, the expansion fails, or the delegated `task` fails, stop and report it clearly.
 
 ## Output
 

packages/core/commands/branch.md

@@ -28,7 +28,7 @@ $ARGUMENTS
 ### Check Blockers
 
 - If `<changes>` contains no files, STOP and report that there is nothing to branch from
-- If `<current-branch>` already starts with a conventional work-branch category such as `feature/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`, `feat/`, `bugfix/`, `hotfix/`, `perf/`, `build/`, or `ci/`, STOP and report that branching is being skipped because the current branch already looks like a work branch
+- If `<current-branch>` already starts with a conventional work-branch category such as `feature/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`, `feat/`, `bugfix/`, `hotfix/`, `perf/`, `build/`, or `ci/`, STOP and report that branching was skipped because the current branch already looks like a work branch
 
 ### Create Branch
 
@@ -51,7 +51,9 @@ No additional steps are required.
 
 If branching is skipped because the current branch already looks like a work branch, display:
 ```
-Already on work branch: <current-branch>
+Branching skipped because the current branch already looks like a work branch.
+
+Current branch: <current-branch>
 
 No additional steps are required.
 ```

packages/core/commands/ship.md

@@ -4,7 +4,7 @@ Ship the current work by dispatching branch creation, commit creation, and PR cr
 
 ## Additional Context
 
-Use `<branch-context>` to steer dispatched branch naming. Use `<additional-context>` to refine the dispatched commit and PR summaries. Pass `<base>` through to PR creation when it was provided. This command is session-command-first: send each `<session_command>` body literally through `session_command` and use the result as the source of truth for the next step.
+Use `<branch-context>` to steer delegated branch naming. Use `<additional-context>` to refine the delegated commit and PR summaries. Pass `<base>` through to PR creation when it was provided.
 
 ## Workflow
 
@@ -21,38 +21,37 @@ $ARGUMENTS
 - If the trimmed `<arguments>` is only a branch reference (for example `main` or `origin/develop`), store it as `<base>` and leave the context fields empty
 - Otherwise, store `<arguments>` as both `<branch-context>` and `<additional-context>`
 
-### Ensure Feature Branch
+### Delegate Branch Creation
 
-<session_command agent="worker" command="branch">
+<delegate agent="worker" command="branch">
 Branch naming guidance: <branch-context>
-</session_command>
+</delegate>
 
-- Store the dispatch result as `<branch-result>`
+- Store the delegated result as `<branch-result>`
+- If `<branch-result>` says there was nothing to branch from, continue on the current branch
+- If `<branch-result>` says branching was skipped because the current branch already looks like a work branch, continue on the current branch
 - If `<branch-result>` is blocked or incomplete, STOP and report the branch blocker
-- If `<branch-result>` says there was nothing to branch from, continue without changing branches
 - Otherwise, continue with the created branch
 
 ### Delegate Commit
 
-<session_command agent="worker" command="commit">
+<delegate agent="worker" command="commit">
 Additional context: <additional-context>
-</session_command>
-
-- Store the dispatch result as `<commit-result>`
+</delegate>
 
+- Store the delegated result as `<commit-result>`
 - If `<commit-result>` says there was nothing to commit, continue without creating a new commit
 - If `<commit-result>` is blocked or incomplete, STOP and report the commit blocker
 - Otherwise, continue with the created commit
 
 ### Delegate PR Creation
 
-<session_command agent="worker" command="pr/create">
+<delegate agent="worker" command="pr/create">
 Base branch: <base>
 Additional context: <additional-context>
-</session_command>
-
-- Store the dispatch result as `<pr-result>`
+</delegate>
 
+- Store the delegated result as `<pr-result>`
 - If `<pr-result>` is blocked or incomplete, STOP and report the PR blocker
 - If `<pr-result>` says there is nothing to include in a PR, STOP and report that there is nothing to ship
 - Otherwise, continue with the created or existing PR

packages/core/commands/ticket/dev.md

@@ -4,7 +4,7 @@ Implement a ticket by orchestrating development, branching, commit-and-push, and
 
 ## Additional Context
 
-Use `<additional-context>` to refine scope, sequencing, and tradeoffs across the dispatched `/dev`, `/branch`, `/commit-and-push`, and `/pr/create` steps.
+Use `<additional-context>` to refine scope, sequencing, and tradeoffs across the delegated `/dev`, `/branch`, `/commit-and-push`, and `/pr/create` steps.
 
 ## Workflow
 
@@ -31,55 +31,47 @@ $ARGUMENTS
 
 ### Delegate Implementation
 
-- Before continuing, send the exact `session_command` block below through `session_command`
-
-<session_command agent="worker" command="dev">
+<delegate agent="worker" command="dev">
 Ticket reference: <ticket-ref>
 Ticket context: <ticket-context>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the result as `<implementation-result>`
+- Store the delegated result as `<implementation-result>`
 - If `<implementation-result>` is blocked or incomplete, STOP and report the implementation blocker
 
 ### Delegate Branch Creation
 
-- Before continuing, send the exact `session_command` block below through `session_command`
-
-<session_command agent="worker" command="branch">
+<delegate agent="worker" command="branch">
 Branch naming guidance: <ticket-summary>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the result as `<branch-result>`
+- Store the delegated result as `<branch-result>`
 - If `<branch-result>` is blocked or incomplete, STOP and report the branch blocker
 - If `<branch-result>` says branching was skipped because the current branch already looks like a work branch, continue
 
 ### Delegate Commit And Push
 
-- Before continuing, send the exact `session_command` block below through `session_command`
-
-<session_command agent="worker" command="commit-and-push">
+<delegate agent="worker" command="commit-and-push">
 Ticket reference: <ticket-ref>
 Ticket summary: <ticket-summary>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the result as `<commit-result>`
+- Store the delegated result as `<commit-result>`
 - If `<commit-result>` is blocked or incomplete, STOP and report the commit or push blocker
 - If `<commit-result>` says there was nothing to commit or push, continue to PR creation so already-committed branch work can still be shipped
 
 ### Delegate PR Creation
 
-- Before continuing, send the exact `session_command` block below through `session_command`
-
-<session_command agent="worker" command="pr/create">
+<delegate agent="worker" command="pr/create">
 Ticket reference: <ticket-ref>
 Ticket context: <ticket-context>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the result as `<pr-result>`
+- Store the delegated result as `<pr-result>`
 - If `<pr-result>` is blocked or incomplete, STOP and report the PR blocker
 - Otherwise, continue and store the resulting PR URL as `<pr-url>`
 

packages/core/commands/todo.md

@@ -8,6 +8,7 @@ Work through a todo file one pending item at a time by planning, getting approva
 - Do not merge separate todo items unless the file explicitly frames them as one task
 - If implementation reveals scope that materially changes the approved plan, pause and re-plan before marking the task complete
 - Use `<additional-context>` to prioritize tradeoffs, constraints, or validation expectations during planning and implementation
+- Delegate planner and worker steps through literal `<delegate>` blocks and use the delegated results as the source of truth for planning, implementation, and commit steps.
 
 ## Workflow
 
@@ -41,14 +42,13 @@ $ARGUMENTS
 
 ### Delegate Planning
 
-<session_command agent="planner" command="ticket/plan">
+<delegate agent="planner" command="ticket/plan">
 Task: <task>
 Task context: <task-context>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Ask the planner for a concise implementation plan with clear scope, risks, and validation steps
-- Store the result as `<plan>`
+- Store the delegated result as `<plan>`
 - If the planner is blocked or cannot produce a usable plan, store the blocker as `<pause-reason>`, then STOP and report that planning blocker
 
 ### Review Plan With User
@@ -62,39 +62,42 @@ Additional context: <additional-context>
     - `Revise` - update the plan based on feedback
 - custom answers enabled so the user can provide specific plan changes
 - If the user requests changes, store that feedback as `<user-answer>`
-<session_command agent="planner" command="ticket/plan">
+- Only run the revised planning block below when the user requests changes
+- If the user approves the current plan, skip the revised planning block and continue to implementation
+
+<delegate agent="planner" command="ticket/plan">
 Task: <task>
 Task context: <task-context>
 Current plan: <plan>
 Plan feedback: <user-answer>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the revised result as `<plan>` and continue the review loop
+- Store the revised delegated result as `<plan>` and continue the review loop
 - If the revised planner result is blocked or unusable, store that blocker as `<pause-reason>`, then STOP and report it before continuing the review loop
 - Repeat this review step until the user approves or stops
 - If the user does not approve implementation, store `plan approval not granted` as `<pause-reason>`, then STOP without changing `<todo-file>`
 
 ### Delegate Implementation
 
-<session_command agent="worker" command="dev">
+<delegate agent="worker" command="dev">
 Plan: <plan>
 Task: <task>
 Task context: <task-context>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the dispatch result as `<implementation-result>`
+- Store the delegated result as `<implementation-result>`
 - If `<implementation-result>` is incomplete, blocked, or fails validation, store the issue as `<pause-reason>`, then STOP and report it without marking the task complete
 
 ### Delegate Commit
 
-<session_command agent="worker" command="commit">
+<delegate agent="worker" command="commit">
 Task: <task>
 Additional context: <additional-context>
-</session_command>
+</delegate>
 
-- Store the dispatch result as `<commit-result>`
+- Store the delegated result as `<commit-result>`
 - If `<commit-result>` does not succeed, store the commit status as `<pause-reason>`, then STOP and report it without marking the task complete
 
 ### Mark Complete And Loop

packages/core/index.ts

@@ -17,8 +17,8 @@ export type {
 } from "./lib/config.ts";
 export { createTools } from "./tools/index.ts";
 export { createChangesLoadTool } from "./tools/changes-load.ts";
-export { createSessionCommandTool, resolveSessionCommand } from "./tools/dispatch.ts";
-export type { SessionCommandResolution } from "./tools/dispatch.ts";
+export { createCommandExpansionTool, resolveCommandExpansion } from "./tools/dispatch.ts";
+export type { CommandExpansion } from "./tools/dispatch.ts";
 export { createPrLoadTool } from "./tools/pr-load.ts";
 export { createPrSyncTool } from "./tools/pr-sync.ts";
 export { createTicketLoadTool } from "./tools/ticket-load.ts";

packages/core/kompass.jsonc

@@ -41,7 +41,7 @@
 
   "tools": {
     "changes_load": { "enabled": true },
-    "session_command": { "enabled": true },
+    "command_expansion": { "enabled": true },
     "pr_load": { "enabled": true },
     "pr_sync": { "enabled": true },
     "ticket_load": { "enabled": true },