Agent Y

Agent Y: CLI channels and pull-request handoffs

Release status: Agent Y is included in the current 1.11.0-alpha.6 interface. Earlier 1.8.9-alpha.1 installations do not contain agent-y commands. Select a verified exact release; see Versions and changelog.

The current release review identifies the exact source, checks, and inherited limits. Tier 2 Agent Alpha adds selected specialist context; it does not alter Agent Y PR authority gates.

Agent Y is the optional CLI channel role (agent.y). Agent 0 can delegate one bounded, existing task to a chosen external CLI assistant, such as Codex CLI, Copilot CLI, or another provider actually installed on the user's machine. Agent Y keeps the provider run, isolated Git work, and GitHub pull-request (PR) handoff attributable to that task. The app or IDE running Agent 0 may also have its own subagents; those workers and an external CLI are different execution contexts. A role record does not launch either one.

The public template ships with only agent.0 registered. Preview roles-init, then explicitly apply it with compatible selected defaults to add blank X/Y/Z records in the chosen root .SYSTEMX or child .SYSTEMXP scope. This does not run a CLI, open a PR, or rewrite existing records. The user or Agent 0 chooses a provider per task. There is no preferred model, hidden fallback provider, or automatic sharing of one provider's private context with another. For the built-in Codex/Copilot adapters, prepare --model NAME can request a model supported by the installed CLI and account. A configured adapter uses its reviewed --arg values for model selection. Report the model observed in the actual run when it matters to the task. Agent Y does not silently route across models after a failure.

Alpha boundary: The saved channel is a coordination record. Real execution comes from the installed CLI, Git, GitHub CLI/API, and their existing permissions. Verify which command, account, repository, branch, and checkout are active before allowing writes. A task packet or draft PR is not proof that work ran or met acceptance criteria.

The controller has offline checks, but real Codex/Copilot provider execution and GitHub write paths have not been exercised end to end for this alpha. Treat the first authorized run in a project as a controlled trial with independent checks and remote-state readback.

At prepare, the controller resolves the selected CLI to a canonical absolute regular executable and records its SHA-256, device, inode, and size in the ignored owner-only local sidecar. Built-in codex or copilot can be found through PATH at preparation; run uses the pinned absolute target even if PATH changes. A configured adapter needs the same reviewed absolute, unlinked --command at both prepare and run. If the executable has changed, run refuses before provider start, with a final identity check immediately before launch. Review the new binary and prepare a new handoff. This binds the selected CLI file, not its interpreter, dependencies, or authentication. It does not remove the same-user check/launch race or create an OS sandbox.

Native Windows alpha limit: agent-y run Y-ID --apply refuses before starting a provider or creating a worktree because descendant-process termination has not been verified there. Provider detection, previews, and record inspection remain available. This Agent Y execution limit does not change the separate Windows installer/PowerShell or core record workflows.

One task, one owned channel

Agent 0 remains the sole coordinator of the canonical WORK/TASKS.json ledger and Master Plan. It selects a dependency-ready task, checks the current base revision and actual authorization, assigns it to agent.y, and records in_progress when the delegated task workflow begins. The Agent Y prepare command requires that existing assigned, in-progress task and gives the CLI a bounded packet:

Channel input	What Agent 0 must establish
Scope	Exact .SYSTEMX or named .SYSTEMXP, task ID, acceptance criteria, dependency state, and stop condition
Provider	A CLI the user has installed and authorized for this task; the model or provider can differ from the app or IDE's model
Git target	Repository identity, base branch and observed commit, unique task branch, checkout or worktree, and permitted files
External authority	Whether the CLI may run, push a branch, open a draft PR after successful work, mark it ready, close an abandoned PR, or clean up the owned branch after a verified merge; merge requires a separate authorized process, while cancelled unmerged branches are retained for manual review
Return evidence	CLI exit status, changed paths, commit SHA, PR URL/number, and current remote state; Agent 0 must run and cite project checks separately

No task owner string or Agent Y registry entry grants those permissions. Review the project's Access Matrix and the actual host/repository permissions. Keep tokens and credentials out of the channel record, prompts, logs, and PR body.

An applied Agent Y run uses an isolated worktree and a dedicated task branch for the assigned code change. It must inspect local edits before branching, avoid overwriting work, and record the verified base and head revisions. Worktrees isolate files but do not isolate ports, cloud resources, credentials, caches, or the canonical ledger. Give each task a distinct channel and a single integration owner. Do not have several CLI sessions edit the same branch or project records at once.

Lifecycle and authority gates

flowchart TD
    A["Agent 0: selected scope and authorized task packet"] --> B["Agent Y: selected Codex, Copilot, or configured CLI"]
    B --> C["Pinned executable; isolated worktree; controller scope/Git checks"]
    C --> D{"Zero exit, scoped commit, and draft-PR opt-in?"}
    D -->|Yes| E["Push absent owned branch; open draft PR"]
    D -->|No| F["Retain local result or failure for inspection"]
    E --> G["Agent 0: independent project checks; X observed events; Z matching review"]
    F --> G
    G --> H{"Agent 0/user records disposition"}
    H -->|Accepted done and PR exists| I["Separate pr-ready; recheck recorded base/head"]
    H -->|Accepted without PR| N["Keep local accepted handoff; no PR operation"]
    H -->|Cancelled and PR exists| J["Separate pr-close with reason; retain branch/worktree"]
    H -->|Cancelled without PR| O["Keep local cancellation/evidence; no PR operation"]
    H -->|Concrete gap| K["Return bounded next action or blocker"]
    I --> M["Separate authorized merge outside Agent Y"]
    M --> L["Merged + accepted + exact owned head + no local material to discard"]
    L --> Archive["Separate pr-cleanup: verify private bundle, then remove owned branch/worktree"]

Loading

Text equivalent: Agent 0 authorizes a task and provider. Agent Y runs the chosen CLI in an isolated branch and returns actual evidence. With opt-in, a zero CLI exit, and a scoped controller commit, it may push and open a draft PR before independent project checks. Agent Z may review the evidence; Agent 0 independently checks the result against the original task. The channel stays open until an accepted or cancelled decision is recorded. If there is no owned PR, acceptance or cancellation remains a local task decision and no PR transition applies. Ready, merge, abandoned close, and branch cleanup are separate GitHub actions, each requiring the applicable authority and remote-state readback.

An opt-in draft PR is a review handoff, not acceptance. Making a draft PR ready does not merge it. Merging an accepted PR changes repository history; Agent Y has no merge command. A merged PR with an accepted task can use a separate pr-cleanup only after exact remote PR and owned branch/head checks. Its applied form first creates and verifies a private local Git bundle under state/agent-y/archives/, records its digest, then conditionally deletes the unchanged owned branch and worktree. Retain that bundle separately before uninstalling or moving hosts. Cleanup checks tracked, untracked, and ignored worktree files before removal and again after a remote branch deletion. It refuses to remove a worktree containing provider caches or any other local material, even when ordinary git status looks clean. Inspect and preserve that material before manually discarding only expendable files. A refusal before remote deletion can be retried after review; a refusal afterward may leave the archive and remote deletion complete with the local worktree still present. Reconcile the exact branch, PR, worktree, and archive in that case; do not remove the archive merely to force a retry. Closing an abandoned PR leaves its commits unmerged and is allowed only for a cancelled task with an explicit reason; Agent Y retains its branch and worktree. Agent Y must not infer any of those operations from a high Agent Z score, a green local check, or the mere existence of a draft PR. Agent 0 or the project owner must authorize the specific action and verify the remote result afterward. GitHub documents ready, close, and merge as distinct operations.

Before pr-ready, Agent Y compares the live remote base branch SHA with the immutable baseOid recorded for the prepared handoff. It checks in preview, immediately before calling GitHub under the coordination lock, and before saving the ready state. If the base moved, the draft stays draft: review the new base, reconcile the work, and prepare a new bounded handoff. A base update during the GitHub call is not atomic with marking the PR ready; inspect the actual remote PR state if that race occurs.

If the CLI task fails, times out, or stops with partial work, inspect the actual process and files before retrying. Preserve the channel identity and evidence; do not open a draft PR merely because a branch was created. If a network action has an unknown outcome, query GitHub for the branch and PR before repeating it. Avoid creating duplicate PRs for retries. Remote push, draft-PR creation, ready, or close can succeed while the following GitHub read or local JOBS.json write fails. Treat that as unknown, not failed or safe to retry. Preserve the branch and worktree. Read GitHub and Git without mutation to verify the exact repository owner, base branch, task branch, head commit, PR number/URL, and current draft/open/closed/merged state. Compare those facts with the saved job and original task, then perform a reviewed manual reconciliation before any further action. This alpha has no agent-y reconcile command and does not automatically repair partial remote operations. For a job stranded in running after a controller crash, preview agent-y recover Y-ID. Its --apply form is allowed only when the recorded owner is on this host and its process is confirmed gone. It marks the job failed but preserves worktree and remote state for manual inspection; it does not kill a live provider, retry a task, or delete a branch.

Command sequence

Preview activation first, then apply it in the selected root scope. For a named child, use projects roles-init --project NAME and its --apply form.

bash .SYSTEMX/SYSTEMX.sh roles-init
bash .SYSTEMX/SYSTEMX.sh roles-init --apply
bash .SYSTEMX/SYSTEMX.sh agent-y providers

Create the task through the normal task workflow and assign it to agent.y. After Agent 0 confirms its dependencies and starts the delegated workflow, the task must be in_progress. prepare rejects a target repository with staged, unstaged, or untracked changes. If task edits occurred in that same repository, review and commit the coordination changes through the project's normal process, then refresh and inspect the local origin/BASE tracking revision before preparing. If .SYSTEMX is outside the code repository, still verify the selected code checkout is clean. Use the real task ID, an absolute path to the intended local Git repository, the observed base branch, a reviewed prompt file, and a narrow relative allowed path. The prompt file must be a regular, unlinked file inside that repository, at most 64 KiB; keep sensitive packets private and ignored by Git. The example assumes that repository has a local .SYSTEMX whose local/ directory is ignored; otherwise use a reviewed ignored path inside the selected repository and outside the allowed edit scope. The portable AGENTS/agent.y/JOBS.json stores task/provider identity, allowed paths, Git base/head and PR references, state, and evidence references. It does not store the raw prompt, provider transcript, or absolute host paths. An ignored state/agent-y/Y-<id>.json file in the selected .SYSTEMX or .SYSTEMXP stores that host's absolute repository, prompt, and worktree paths and any configured executable arguments. Treat this sidecar as private host-local execution state: do not put credentials in it, publish it, or assume a synced JOBS.json can resume a run on another host. Whole-folder backups or sync clients may still copy ignored files, so inspect their scope. For a Git-backed .SYSTEMX, Agent Y checks before writing that local sidecars and cleanup bundles are ignored and that no file under state/agent-y/ is already tracked. A customized preserved .gitignore without /state/ makes prepare --apply refuse before creating the job; add an appropriate rule, verify it with git check-ignore, and investigate any prior commit containing private state. The same check applies when reading existing sidecars, so later ignore removal blocks further actions. A Git ignore rule cannot undo Git history, stop a force-add, or stop whole-folder backup and external sync. An older prepared Agent Y job without pinned executable identity fails closed under this runner. Agent 0 can inspect its job and sidecar, then preview and apply agent-y abandon Y_RETURNED_ID --reason "Reprepare with reviewed CLI" while it remains prepared with no branch or worktree. That retires the unrun handoff without deleting an external artifact. Reconcile the task ledger and clean checkout, then prepare a new branch and job. Already-run older jobs remain readable for PR readiness, closure, cleanup, and recovery under their normal gates. Do not copy another host's private sidecar to bypass identity checks. copilot also receives a temporary .agent-y-packet.md inside its isolated worktree. The controller removes it after a normal return, but a crashed run may leave that task packet behind; inspect retained worktrees before recovery, backup, or disposal. prepare previews by default; its --apply form saves a channel and returns a Y-... job ID. The draft-PR flag is an explicit opt-in to a later action after a successful run, not permission to merge or delete anything. Repeat --allow-path for other narrow paths; optionally supply --branch or inspect the proposed generated branch in the preview. The preview must be side-effect-free: it must not start a provider, create a worktree, push, or contact GitHub to open a PR.

bash .SYSTEMX/SYSTEMX.sh agent-y prepare \
  --task TASK-001 --provider codex --repo /path/to/project \
  --base OBSERVED_REMOTE_BASE_BRANCH \
  --prompt-file /path/to/project/.SYSTEMX/local/agent-y/approved-task.md \
  --allow-path src/
# After inspecting the preview, apply the same packet to get Y_RETURNED_ID.
bash .SYSTEMX/SYSTEMX.sh agent-y prepare \
  --task TASK-001 --provider codex --repo /path/to/project \
  --base OBSERVED_REMOTE_BASE_BRANCH \
  --prompt-file /path/to/project/.SYSTEMX/local/agent-y/approved-task.md \
  --allow-path src/ --apply
bash .SYSTEMX/SYSTEMX.sh agent-y run Y_RETURNED_ID --apply
bash .SYSTEMX/SYSTEMX.sh agent-y show Y_RETURNED_ID
bash .SYSTEMX/SYSTEMX.sh agent-y validate
# Only for a stranded running job after checking its owner process:
# bash .SYSTEMX/SYSTEMX.sh agent-y recover Y_RETURNED_ID
# bash .SYSTEMX/SYSTEMX.sh agent-y recover Y_RETURNED_ID --apply

For a legacy job that remains prepared without pinned executable identity, retire only that unrun handoff after inspection:

bash .SYSTEMX/SYSTEMX.sh agent-y abandon Y_RETURNED_ID \
  --reason "Reprepare with reviewed CLI"
bash .SYSTEMX/SYSTEMX.sh agent-y abandon Y_RETURNED_ID \
  --reason "Reprepare with reviewed CLI" --apply

Select codex or copilot only after agent-y providers shows the CLI installed and the account permissions are checked. A configured provider uses an explicit reviewed absolute executable: pass --command ABSOLUTE_EXE at prepare and again at run --apply, with repeatable --arg VALUE options for that run. Preparation pins that same executable in the private sidecar; run rechecks it before launch and refuses replacement or drift. The provider listing cannot authenticate this adapter or decide whether its flags are safe. Keep tokens out of those arguments and the sidecar. Provider versions differ. If a selected CLI refuses the scoped permissions or noninteractive mode, stop and report that limit; do not automatically retry with broad all-tools access or silently switch providers. The Codex adapter requests a worktree-write scope. Copilot and configured adapters do not gain an equivalent operating-system sandbox from Agent Y. The coordination-path guard also rejects .SYSTEMX/ROOT/ and .SYSTEMX/AUTOBOT/ as Agent Y edit scopes, with case-insensitive path comparison. New preparation and the selected job's run and pr-ready actions enforce the current guard before side effects; returned changed-path checks remain strict. Historical jobs that were valid under the earlier ROOT/AUTOBOT path policy stay readable without changing their recorded scope. Inspection, validation, and the existing abandonment/cancellation/recovery paths retain their normal lifecycle gates. Historical readability does not permit an old protected handoff to run or become ready. Preserve its history and review the intended coordination change with Agent 0 or the appropriate authorized record owner; do not erase the job or silently rewrite its allow list to bypass the refusal. Post-run allowed-path checks detect a changed local diff; they cannot reverse network calls, external writes, or provider-side effects. Give each provider only the host permissions and task resources it needs. The example makes a local handoff without a push or PR. For an explicitly authorized draft-PR task, add --open-draft-pr to both the preview and applied prepare command in place of that local-only pair; inspect target repository automation and cost first. Do not create a second job for the same handoff just to change its PR policy. run invokes the selected provider with the task prompt, checks the bounded worktree result, and returns the observed CLI/Git/PR outcome. Read its job state and GitHub after any interrupted or uncertain run before retrying. On native Windows, this applied run intentionally refuses before provider or worktree mutation in this alpha; use a verified supported host for CLI execution. The controller's path and Git checks do not run or replace the project's acceptance tests. Require original test/check evidence in the task packet and review what actually ran before Agent 0 accepts the result. This alpha job records CLI exit status, changed paths, commit/head and PR metadata. It does not retain provider stdout/stderr or test output. Agent 0 must run and cite independent project checks and use Agent X/Z records where relevant; a zero CLI exit code cannot certify application behavior. Opening a draft PR may trigger GitHub Actions, webhooks, or paid services in the target repository, even though dotSYSTEMX's own GitHub Actions are disabled. Inspect target-repository automation and cost rules before opting in. See GitHub's workflow-trigger reference and Actions billing guide.

After Agent 0 accepts the task with evidence and the canonical ledger says done, a separately authorized pr-ready can mark the owned draft PR ready for review. It does not merge the PR. After another authorized process merges it, pr-cleanup verifies that remote outcome and exact ownership before cleaning up the owned task branch or worktree. A cancelled task can instead use pr-close with a reason to close its owned unmerged PR. That close retains the branch and worktree; Agent Y does not automatically delete unmerged cancelled work in this alpha interface. Unpublished local work likewise keeps its sole branch/worktree for reviewed manual handling; Agent Y offers no automatic no-PR cleanup command.

Define the delegated code task's acceptance criteria for the reviewed candidate change. If the original objective also requires merge, deployment, or live verification, preserve that objective in the Master Plan and track those outcomes as dependent delivery tasks. Close each delivery task only after its outcome is actually observed. Do not mark any unmet criterion complete just to unlock a draft-PR transition.

bash .SYSTEMX/SYSTEMX.sh agent-y pr-ready Y_RETURNED_ID --apply
# After an independently authorized merge has been verified:
bash .SYSTEMX/SYSTEMX.sh agent-y pr-cleanup Y_RETURNED_ID --apply
# On a cancelled task instead of the accepted path:
bash .SYSTEMX/SYSTEMX.sh agent-y pr-close Y_RETURNED_ID \
  --reason 'Objective cancelled by project owner' --apply

agent-y list and agent-y show Y_RETURNED_ID inspect saved channels. In a child, use the projects agent-y ... --project NAME route so the job and task resolve to the same .SYSTEMXP. These commands are alpha interfaces; use the selected release's help for exact flags and verify the installed defaults version before invoking them.

How the four standard roles cooperate

Role	Owns	Does not imply
Agent 0	Task selection, delegation, canonical ledger, integration, acceptance, and authority decisions	That a CLI or PR action has occurred
Agent X	Timestamped observations for CLI start/finish, branch push, draft/ready/merge/close decisions, and later live verification	A scheduler, GitHub webhook, or independent proof of the event
Agent Y	One selected external CLI task channel, provider/run identity, Git base/head and branch/PR handoff, return evidence, and authorized lifecycle actions	Provider installation, credentials, execution sandbox, or permission grant
Agent Z	One fixed-policy review of a prompt or changed result at a meaningful boundary	Automatic acceptance, merge, deployment, or another work loop

Record actual GitHub state rather than desired state. A PR URL is evidence of a PR, but it does not establish that checks ran, the PR was merged, or the result is live. Agent X can record the observed event with its occurrence time, source revision, and original GitHub or CLI evidence reference. Agent Z may review the changed code and evidence using its existing 100 questions. Agent 0 decides whether the original acceptance criteria are met, whether another bounded task is needed, and whether an authorized PR transition should occur. Keep the task ledger as the only task-status authority.

Example: app coordinator with an external CLI

1. In Codex App or VS Code, Agent 0 reads the selected project's .SYSTEMX state and assigns TASK-001. App-native subagents may handle independent research or tests within the user's chosen worker ceiling.
2. For a distinct code scope, Agent 0 selects Codex CLI, Copilot CLI, or another available CLI for this task. It supplies the task packet, observed base revision, branch name, checkout, allowed files, required checks, and PR opt-in/authority boundary to Agent Y.
3. Agent Y invokes the installed CLI through the host's real toolchain. It records process status and the scoped Git result, then, only when authorized and successful, pushes the task branch and opens a draft PR. It returns the PR number and URL plus the observed head SHA to Agent 0.
4. Agent X records meaningful occurrences. Agent Z may review the relevant change and evidence. Agent 0 runs/cites the project's required checks, independently checks the candidate change, and moves the canonical task to needs_review, then to done only on acceptance.
5. Agent 0 makes a separate decision to request review, authorize an external merge, or close an abandoned PR. Agent Y performs only its supported and authorized ready/close action; after verified merge and acceptance, it may perform guarded branch cleanup. It reads GitHub back and records the final disposition. A cancelled unmerged branch stays available for reviewed archival or manual disposition.

This also works when the app and CLI use different model providers. The shared contract is the explicit task packet, repo revision, scoped artifacts, evidence, and handoff—not a claim that one model inherits another model's hidden context. App-native subagents and external CLI runs consume a shared project budget for concurrent work, tokens, tool time, and contested resources. An Agent Y job does not grant another free set of worker slots. .SYSTEMX does not enforce a cross-harness scheduler; Agent 0 must track this allocation. The CLI session has separate runtime memory; only deliberately saved and verified notes/evidence cross into the selected .SYSTEMX or .SYSTEMXP records. For a chat-only environment without local CLI or GitHub access, keep the channel as a proposed handoff and use an authorized human or external host to execute it; do not mark it as run.

Multi-project and shared-workspace limits

In SYSTEMX PROJECTS, identify the registry name and child record path in every packet, for example Project-A:TASK-001 at .SYSTEMX/Projects/Project-A/.SYSTEMXP. Equal task IDs in two children are different tasks and must not share a channel or PR association accidentally. The outer Agent 0 coordinates cross-project changes. The child Agent 0 owns its own task ledger and acceptance. Git branch/PR state belongs to the actual repository, which may not have the same boundaries as .SYSTEMXP; verify that mapping in the System MAP.

A local .SYSTEMX lock is not a distributed Git, Drive, or cloud lock. Multiple app sessions or CLIs must establish one canonical writer and integrate by reviewed changes. See shared workspaces, subagent processing, and security.

See Agent Y in the complete system

Page 2 of the four-part field guide shows Agent Y beside the other execution and review responsibilities. The overview connects the lane to Global context, Master Plan, ROOT internal rules/planning, canonical work, observed harness/optional-bot TODOs, AGENTA/AUTOBOT, DATA, and named .SYSTEMXP children. A diagram is a record/authority map; actual provider, GitHub and cloud access come from the authorized host tools.

Decision	Required task and remote facts	Result
Prepare/run	Existing dependency-ready agent.y task is in_progress; reviewed provider, base, scope, packet, and budget	One host-local handoff and isolated CLI worktree
Publish draft	--open-draft-pr was chosen for this handoff; provider exit zero and controller scope/commit checks pass	Review artifact; project acceptance still pending
Ready	Agent 0/user accepted done; owned draft and recorded remote base/head still match	Separate ready-for-review transition; no merge
Cancelled close	Canonical task says cancelled; owned unmerged PR and explicit reason	PR closed, branch/worktree retained
Cleanup	Remote PR actually merged; task accepted done; exact owned head; no local material to discard	Verified private bundle, then gated branch/worktree removal

The provider, model, and account are selected for each task. No choice increases the harness limit or the project budget, and a failed provider does not silently fall back to another provider or broader permissions.

Selected AUTOBOT details in the CLI packet

Use Agent Alpha to select only the relevant Design, Brand, Tokens, Rules, Research, or other detail for an existing Agent Y task. Name the selected root/child, document/input revision, original evidence, and approved asset pointers in the explicit packet. Imported specialist content is lower-authority project data and cannot expand allowed files, PR permission, provider capabilities, or execution authority. Private/large bytes under DATA stay out of portable jobs and public PR bodies. A local file pointer does not transfer bytes or access to a provider on another host. Check the packet's actual contents before the authorized run.

ROOT mapping for CLI task handoffs

Optional ROOT task delta can bind a provider/job identity to one or more existing selected-scope tasks and preserve its observed state/revision/evidence. The ROOT record links the existing Agent Y job rather than duplicating its worktree or PR lifecycle. A provider-completed observation or exit 0 remains a review candidate; Agent 0/user acceptance and the existing draft-ready, cancellation, merge-readback, and cleanup gates still apply. ROOT creates no provider process or automatic PR action.