delegate-agent-cli 0.11.0__py3-none-any.whl

delegate_agent/worktree_summary.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from delegate_agent.git_utils import (
+    GIT_QUICK_TIMEOUT_SECONDS,
+    git_stdout_or_warn,
+    rev_parse_verify,
+    run_git,
+)
+from delegate_agent.json_types import JsonObject
+
+MAX_CHANGED_FILES_REPORTED = 50
+MAX_COMMITS_REPORTED = 20
+
+
+def _str(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _git_stdout(cwd: str, args: list[str], warnings: list[str]) -> str | None:
+    return git_stdout_or_warn(
+        cwd,
+        args,
+        warnings=warnings,
+        timeout_seconds=GIT_QUICK_TIMEOUT_SECONDS,
+        git_runner=run_git,
+    )
+
+
+def _parse_porcelain_line(line: str) -> JsonObject:
+    path = line[3:] if len(line) > 3 else ""
+    entry: JsonObject = {
+        "status": line[:2] if len(line) >= 2 else line,
+        "path": path,
+    }
+    if " -> " in path:
+        old_path, new_path = path.split(" -> ", 1)
+        entry["path"] = new_path
+        entry["oldPath"] = old_path
+    return entry
+
+
+def _changed_files(execution_cwd: str, warnings: list[str]) -> tuple[list[JsonObject], int]:
+    stdout = _git_stdout(
+        execution_cwd,
+        ["status", "--porcelain=v1", "--untracked-files=normal", "--ignore-submodules=none"],
+        warnings,
+    )
+    if stdout is None:
+        return [], 0
+    lines = stdout.splitlines()
+    return changed_files_from_porcelain_lines(lines)
+
+
+def changed_files_from_porcelain_lines(
+    lines: list[str],
+    total: int | None = None,
+) -> tuple[list[JsonObject], int]:
+    return (
+        [_parse_porcelain_line(line) for line in lines[:MAX_CHANGED_FILES_REPORTED]],
+        len(lines) if total is None else total,
+    )
+
+
+_SHORTSTAT_FILES_RE = re.compile(r"(\d+)\s+files?\s+changed")
+_SHORTSTAT_INSERTIONS_RE = re.compile(r"(\d+)\s+insertions?\(\+\)")
+_SHORTSTAT_DELETIONS_RE = re.compile(r"(\d+)\s+deletions?\(-\)")
+
+
+def _parse_shortstat(raw: str) -> JsonObject:
+    payload: JsonObject = {"raw": raw}
+    files = _SHORTSTAT_FILES_RE.search(raw)
+    insertions = _SHORTSTAT_INSERTIONS_RE.search(raw)
+    deletions = _SHORTSTAT_DELETIONS_RE.search(raw)
+    if files is not None:
+        payload["filesChanged"] = int(files.group(1))
+    if insertions is not None:
+        payload["insertions"] = int(insertions.group(1))
+    if deletions is not None:
+        payload["deletions"] = int(deletions.group(1))
+    return payload
+
+
+def _diff_shortstat(execution_cwd: str, rev: str, warnings: list[str]) -> JsonObject:
+    stdout = _git_stdout(execution_cwd, ["diff", "--shortstat", rev], warnings)
+    return _parse_shortstat(stdout or "")
+
+
+def _rev_parse(cwd: str, rev: str, warnings: list[str]) -> str | None:
+    return rev_parse_verify(
+        cwd,
+        rev,
+        warnings=warnings,
+        timeout_seconds=GIT_QUICK_TIMEOUT_SECONDS,
+        git_runner=run_git,
+    )
+
+
+def _rev_list_count(cwd: str, rev_range: str, warnings: list[str]) -> int | None:
+    stdout = _git_stdout(cwd, ["rev-list", "--count", rev_range], warnings)
+    if stdout is None:
+        return None
+    try:
+        return int(stdout.strip())
+    except ValueError:
+        warnings.append(f"git rev-list returned non-integer count for {rev_range!r}: {stdout}")
+        return None
+
+
+def _ahead_behind(cwd: str, left: str, right: str, warnings: list[str]) -> JsonObject | None:
+    stdout = _git_stdout(
+        cwd, ["rev-list", "--left-right", "--count", f"{left}...{right}"], warnings
+    )
+    if stdout is None:
+        return None
+    parts = stdout.split()
+    if len(parts) != 2:
+        warnings.append(f"git rev-list returned unexpected ahead/behind output: {stdout}")
+        return None
+    try:
+        return {"behind": int(parts[0]), "ahead": int(parts[1])}
+    except ValueError:
+        warnings.append(f"git rev-list returned non-integer ahead/behind output: {stdout}")
+        return None
+
+
+def _commits_created(execution_cwd: str, base: str, warnings: list[str]) -> list[JsonObject] | None:
+    stdout = _git_stdout(
+        execution_cwd,
+        [
+            "log",
+            f"--max-count={MAX_COMMITS_REPORTED}",
+            "--reverse",
+            "--format=%H%x01%h%x01%s",
+            f"{base}..HEAD",
+        ],
+        warnings,
+    )
+    if stdout is None:
+        return None
+    commits: list[JsonObject] = []
+    for line in stdout.splitlines():
+        parts = line.split("\x01", 2)
+        if len(parts) != 3:
+            continue
+        oid, short_oid, subject = parts
+        commits.append({"oid": oid, "shortOid": short_oid, "subject": subject})
+    return commits
+
+
+def build_work_summary(
+    *,
+    source_git_root: str | None,
+    execution_cwd: str,
+    branch: str | None,
+    creation_context: JsonObject | None,
+    prefetched_changed_files: tuple[list[JsonObject], int] | None = None,
+) -> JsonObject | None:
+    """Return a compact objective summary for a persistent worktree run.
+
+    The summary is best-effort: unavailable Git metadata is reported in
+    ``warnings`` instead of making launch finalization fail.
+    """
+
+    if not source_git_root or not execution_cwd or not branch:
+        return None
+
+    warnings: list[str] = []
+    creation = creation_context if isinstance(creation_context, dict) else {}
+    base = _str(creation.get("sourceHeadOid"))
+
+    if prefetched_changed_files is None:
+        changed_files, changed_total = _changed_files(execution_cwd, warnings)
+    else:
+        changed_files, changed_total = prefetched_changed_files
+    dirty = changed_total > 0
+    head_commit = _rev_parse(execution_cwd, "HEAD", warnings)
+    source_head = _rev_parse(source_git_root, "HEAD", warnings)
+
+    commits_count: int | None = None
+    commits: list[JsonObject] = []
+    commits_fetch_ok = False
+    branch_ahead_of_base: JsonObject | None = None
+    diff_stat_vs_base: JsonObject | None = None
+    if base is not None:
+        commits_count = _rev_list_count(execution_cwd, f"{base}..HEAD", warnings)
+        behind_base = _rev_list_count(execution_cwd, f"HEAD..{base}", warnings)
+        if commits_count is not None and behind_base is not None:
+            branch_ahead_of_base = {
+                "ahead": commits_count,
+                "behind": behind_base,
+                "baseOid": base,
+            }
+        if commits_count is not None:
+            commits_result = _commits_created(execution_cwd, base, warnings)
+            commits_fetch_ok = commits_result is not None
+            commits = commits_result or []
+        diff_stat_vs_base = _diff_shortstat(execution_cwd, base, warnings)
+    commit_inspection_verified = commits_count is not None
+
+    branch_ahead_of_source = (
+        _ahead_behind(execution_cwd, source_head, "HEAD", warnings) if source_head else None
+    )
+
+    summary: JsonObject = {
+        "dirty": dirty,
+        "changedFilesCount": changed_total,
+        "changedFiles": changed_files,
+        "changedFilesTruncated": changed_total > len(changed_files),
+        "commitsCreatedCount": commits_count,
+        "commitsCreated": commits,
+        "commitsCreatedTruncated": (
+            commits_count > len(commits)
+            if commit_inspection_verified and commits_fetch_ok
+            else False
+        ),
+        "commitInspectionStatus": "verified" if commit_inspection_verified else "unverified",
+        "baseCommit": base,
+        "headCommit": head_commit,
+        "sourceHead": source_head,
+        "branch": branch,
+        "diffStat": _diff_shortstat(execution_cwd, "HEAD", warnings),
+        "noChanges": (not dirty and commits_count == 0 if commit_inspection_verified else False),
+    }
+    if branch_ahead_of_base is not None:
+        summary["branchAheadOfBase"] = branch_ahead_of_base
+    if branch_ahead_of_source is not None:
+        summary["branchAheadOfSource"] = branch_ahead_of_source
+    if diff_stat_vs_base is not None:
+        summary["diffStatVsBase"] = diff_stat_vs_base
+    if warnings:
+        summary["warnings"] = warnings
+    return summary
+
+
+def commits_created_count(summary: JsonObject | None) -> int | None:
+    if not isinstance(summary, dict):
+        return None
+    count = summary.get("commitsCreatedCount")
+    return count if isinstance(count, int) and count >= 0 else None

delegate_agent/wsl.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+WINDOWS_PATH_RE = re.compile(r"^(?:[A-Za-z]:[\\/]|%[A-Za-z_][A-Za-z0-9_]*%)")
+
+
+def is_wsl(env: dict[str, str] | None = None) -> bool:
+    env = os.environ if env is None else env
+    if env.get("WSL_DISTRO_NAME") or env.get("WSL_INTEROP"):
+        return True
+    try:
+        return "microsoft" in Path("/proc/sys/kernel/osrelease").read_text(encoding="utf-8").lower()
+    except OSError:
+        return False
+
+
+def is_windows_path_text(value: str) -> bool:
+    return bool(WINDOWS_PATH_RE.match(value.strip()))
+
+
+def should_reject_windows_path(value: str) -> bool:
+    return is_wsl() and is_windows_path_text(value)
+
+
+def windows_path_message(field: str, value: str) -> str:
+    return (
+        f"{field} must be a POSIX/WSL path, got Windows-style path {value!r}. "
+        "Inside WSL, convert Windows paths with `wslpath -u` or use `/home/...` "
+        "or `/mnt/c/...`."
+    )
+
+
+def drivefs_mount(path: str | Path) -> str | None:
+    parts = Path(path).as_posix().split("/")
+    if len(parts) >= 3 and parts[1] == "mnt" and len(parts[2]) == 1 and parts[2].isalnum():
+        return f"/mnt/{parts[2]}"
+    return None
+
+
+def drivefs_workspace_warning(path: str | Path) -> str | None:
+    if not is_wsl():
+        return None
+    mount = drivefs_mount(path)
+    if mount is None:
+        return None
+    return (
+        f"workspace is on Windows-mounted filesystem {mount}; WSL runs are faster "
+        "and Delegate's private-mode file permissions are more reliable under "
+        "`/home/<user>/...`."
+    )
+
+
+def windows_git_message(git_path: str | None) -> str | None:
+    if not is_wsl() or not git_path:
+        return None
+    path = Path(git_path)
+    if path.name.lower() != "git.exe":
+        return None
+    return (
+        f"git resolves to Windows Git at {git_path!r}. Install Git inside WSL "
+        "(`sudo apt install git`) or put WSL-native Git before Windows PATH entries."
+    )

delegate_agent_cli-0.11.0.dist-info/METADATA

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: delegate-agent-cli
+Version: 0.11.0
+Summary: A tiny CLI for delegating bounded agent tasks to Cursor, Droid, OpenAI Codex, Claude Code, Grok Build, or Kimi Code runtimes.
+Author: Trey Goff
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/treygoff24/delegate-agent
+Project-URL: Repository, https://github.com/treygoff24/delegate-agent
+Project-URL: Issues, https://github.com/treygoff24/delegate-agent/issues
+Project-URL: Documentation, https://github.com/treygoff24/delegate-agent/tree/main/docs
+Project-URL: Security, https://github.com/treygoff24/delegate-agent/security/policy
+Keywords: agents,cli,claude,codex,delegation,cursor,droid,kimi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff==0.15.15; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/delegate-agent-header.png" alt="Delegate Agent" width="100%">
+</p>
+
+# Delegate Agent
+
+Delegate Agent is a small CLI for handing a bounded task to another coding-agent runtime. It normalizes common calls to Cursor Agent, Factory Droid, OpenAI Codex, Claude Code, and Kimi Code so humans or other agents can launch review, investigation, and implementation jobs without remembering each tool's flags.
+
+Use it when you want a predictable wrapper around prompts like:
+
+- "Review this diff and report risks. Do not edit."
+- "Investigate this failure in an isolated copy."
+- "Implement this scoped change, run the named check, and report changed files."
+
+Delegate does **not** commit, push, merge, deploy, publish, or run a background service. It builds the child command, adds safety framing, launches the selected runtime, and records local run metadata for later inspection.
+
+Prompt handling is provider-specific: Codex and Claude prompts are delivered to the child
+runtime over stdin; Droid prompts are delivered through a private temporary
+prompt file using Droid's `--file` option; Cursor Agent and Kimi Code currently
+require prompt argv. Delegate redacts Cursor and Kimi prompt argv in dry-run
+output and run manifests, but true process-argv hiding for those harnesses
+depends on the child CLIs exposing stdin or prompt-file transport.
+
+## Install from source
+
+Delegate requires Python 3.11 or newer. It is currently documented as a GitHub-source install, not a PyPI package.
+
+```bash
+python3 -m pip install "delegate-agent @ git+https://github.com/treygoff24/delegate-agent.git"
+```
+
+For local development or a checkout-only smoke test:
+
+```bash
+git clone https://github.com/treygoff24/delegate-agent.git
+cd delegate-agent
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+python3 bin/delegate.py --json describe
+```
+
+CI currently validates on Linux with Python 3.11, 3.12, 3.13, and 3.14. Windows support is not claimed until it is covered by tests.
+
+## Prerequisites
+
+Delegate wraps other CLIs. Install and authenticate only the runtimes you plan to call:
+
+```bash
+command -v agent   # Cursor Agent CLI (default model: Cursor Composer), used by delegate cursor ...
+command -v droid   # Factory Droid CLI, used by delegate droid ...
+command -v codex   # OpenAI Codex CLI, used by delegate codex ...
+command -v claude  # Claude Code CLI, used by delegate claude ...
+command -v grok    # xAI Grok Build CLI, used by delegate grok ...
+command -v kimi    # Kimi Code CLI, used by delegate kimi ...
+```
+
+Runtime authentication is owned by each child CLI. Delegate cannot log in for you. Dry-runs and CI tests do not require the real child binaries.
+
+Initialize a starter config and replace placeholder Droid model IDs before real Droid runs:
+
+```bash
+delegate config init
+$EDITOR ~/.delegate/config.json
+```
+
+`config init` also writes missing `~/.delegate/config.work.json` and
+`~/.delegate/config.personal.json` profile overlays. For an existing install,
+run `env -u AI_PROFILE delegate config sync-profiles` to materialize any missing
+overlays without overwriting ones you already edited.
+
+Inspect what Delegate sees:
+
+```bash
+delegate --version       # installed version — include this in bug reports
+delegate --json describe --summary
+delegate --json models --summary
+delegate --json describe
+delegate --json models
+delegate --json capabilities
+```
+
+Discover commands as you go: `delegate <command> --help` prints focused help for any command path, and `delegate --json <command> --help` returns an agent-friendly spec of its usage, arguments, and options. For launch and `dry-run` commands, `--json` and `--isolation` may also appear before inline prompt text begins, for example `delegate codex work --prompt-file task.md --json`. `delegate --json describe` includes a `commands` catalog of the whole surface. `delegate --json capabilities` reports reasoning-effort support without launching a child runtime.
+
+From this development checkout, use `python3 bin/delegate.py ...` instead of an installed `delegate` shim.
+
+### WSL setup notes
+
+Delegate is a POSIX/Linux CLI and works best in WSL when everything is WSL-native:
+
+- Install Python, Git, Delegate, and child CLIs inside the WSL distro.
+- Keep projects under `/home/<user>/...`; `/mnt/c/...` works but can be slower and has weaker private-file permission semantics.
+- Pass POSIX paths (`/home/...` or `/mnt/c/...`), not Windows paths like `C:\Users\...`; use `wslpath -u` to convert.
+- If `git` resolves to Windows `git.exe`, Delegate fails with a targeted hint. Install WSL Git, for example `sudo apt install git`.
+
+## Quickstart
+
+Preview the command without launching a child runtime:
+
+```bash
+delegate --json dry-run codex safe "Review this repository. Do not edit files."
+delegate --json dry-run claude safe "Review this repository. Do not edit files."
+```
+
+Run a read-only review in an isolated throwaway workspace:
+
+```bash
+delegate codex safe "Review this repository for correctness risks. Do not edit files."
+delegate claude safe "Review this repository for correctness risks. Do not edit files."
+delegate grok safe "Review this repository for correctness risks. Do not edit files."
+delegate cursor safe "Review the current diff for regressions. Do not edit files."
+delegate kimi safe "Review this repository for regressions. Do not edit files."
+```
+
+Review uncommitted local changes without committing first or pasting a diff — safe mode mirrors your working tree into the isolated copy:
+
+```bash
+# Edit files locally, then launch safe review as-is:
+delegate codex safe "Review my uncommitted changes for regressions. Do not edit files."
+```
+
+Run an edit-capable task in a workspace you trust:
+
+```bash
+delegate cursor work "Fix the parser bug. Run python3 -m unittest tests.test_delegate_parser. Report changed files."
+delegate claude work "Implement the scoped change and run the named check. Report changed files."
+delegate kimi work "Implement the scoped change and run the named check. Report changed files."
+```
+
+For long foreground runs, add `--progress` to emit bounded parent heartbeats to
+stderr while keeping final stdout machine-readable, or set `progress.enabled`
+to `true` in config. Use `--no-progress` to override config for one launch.
+Heartbeat labels are credential-scrubbed before printing but are still
+operational metadata, not raw child output:
+
+```bash
+delegate --json claude safe --progress "Review this repository. Do not edit files."
+```
+
+Run through JSON input for agent callers after copying an example and setting a real `cwd`:
+
+```bash
+cp examples/task.codex.json /tmp/delegate-task.json
+$EDITOR /tmp/delegate-task.json
+delegate --json run --input-json /tmp/delegate-task.json
+```
+
+For Codex fan-outs that must return machine-parseable records, add `--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report injection so the schema owns the final message.
+
+For a one-hop prompt that should not see the current repo or create a tracked
+run, use stateless `call` mode:
+
+```bash
+delegate --json codex call "Summarize this context in three bullets."
+```
+
+Reasoning effort is provider-aware. Unsupported combinations fail before launch. It changes only the requested model thinking depth/cost/latency; it does not change safe/work/call mode, sandboxing, approvals, or edit capability. Codex/Droid validate effort against model capability metadata, Cursor maps effort to configured model selection, Claude maps to Claude Code `--effort`, and Grok maps to Grok `--effort` (`low`, `medium`, `high`, `xhigh`, `max`). Explicit Codex effort can target the harness default model even when `codex.defaultModel` is unset:
+
+```bash
+delegate --json dry-run codex safe --reasoning-effort high "Review this repository. Do not edit files."
+delegate --json dry-run claude safe --reasoning-effort high "Review this repository. Do not edit files."
+```
+
+Inspect tracked output by alias:
+
+```bash
+delegate runs --recent
+delegate snapshot <alias-or-runId>
+delegate run-output <alias-or-runId>
+```
+
+Aliases are always numbered (`codex-1`, `cursor-2`); a **bare harness name
+resolves to the latest matching run**, so `delegate run-output codex` reads the
+newest codex run and `delegate run-output codex:glm` the newest matching
+model. Envelopes echo `requestedHandle`/`resolvedHandle`/`resolutionKind` so you
+can confirm which run you addressed.
+
+`run-output` defaults to the best available parent-facing output: a completion
+report when present, a recovered final assistant message when possible, or
+bounded stdout/stderr diagnostics. Use `--completion-report` when you want that
+selector explicitly. Tracked runs also carry a `resultQuality` classification
+(`ok` / `housekeeping_noop` / `empty` / `suspect_short` / `no_assistant_text`),
+and failed or cancelled runs always get a completion report — synthesized when
+the child produced none — so `--completion-report` never dead-ends.
+
+Block on background runs instead of polling, and cancel them cleanly:
+
+```bash
+delegate wait <alias-or-runId>... [--group NAME] [--timeout SEC] [--completion-report]
+delegate cancel <alias-or-runId>
+```
+
+`wait` uses effective status (a dead child is a terminal failure, not a hang)
+and exits `0` when all waited runs succeeded, `1` when any failed or was
+cancelled, and `124` on timeout. `cancel` signals the run's process group
+(SIGTERM, a short grace period, then SIGKILL) with terminal/stale refusal and a
+start-identity check against PID reuse; a cancelled run reports `cancelled`
+rather than a false success. Tag a batch of launches with `--group NAME` and
+`wait`, `runs`, and the worktree commands can select the whole group at once.
+
+## Task design: cluster related work into fewer, richer delegations
+
+When splitting a project across delegated runs (or any subagents), fewer workers with clustered, related tasks consistently outperform wide fan-outs of narrow siloed tasks. Modern child runtimes carry very large context windows — the scarce resource is coherence across related tasks, not tokens.
+
+- Cluster tasks that share files, schemas, or design trade-offs into one delegation. A single worker that holds the whole entangled cluster can reason about the interactions between its tasks and make globally consistent choices; several siloed workers each make locally reasonable decisions that collide at the seams.
+- Fan out only across genuinely independent units: disjoint file ownership, no shared design decisions, results that do not need to agree with each other.
+- Brief the clustered worker generously. Include the full findings or spec, the decisions already made, and how the tasks relate — context that lets it weigh trade-offs *between* its tasks is the point of clustering.
+
+## Safe mode, work mode, and worktree isolation
+
+Delegate separates three ideas:
+
+| Concept | Meaning |
+| --- | --- |
+| Mode | `safe` is for review/investigation; `work` is edit-capable; `call` is a stateless one-hop model call. |
+| Isolation | The child runtime can run in the source workspace, a temporary copy/worktree, or a persistent Git worktree. |
+| Runtime policy | Extra flags passed to the child runtime, such as Codex `--sandbox read-only`. |
+
+Defaults are intentionally conservative for review paths:
+
+- `delegate cursor safe`, `delegate codex safe`, `delegate claude safe`, `delegate grok safe`, `delegate droid ALIAS safe`, and `delegate kimi safe` run in an isolated throwaway workspace. Safe mode reviews your **current working tree** — uncommitted tracked edits and untracked, non-ignored files are mirrored into an isolated throwaway copy (only gitignored paths are excluded), so you can review local changes without committing first or pasting a diff.
+- Grok safe mode uses Delegate isolated copy plus Grok read-only sandbox/permission controls (`--sandbox read-only`, `--permission-mode dontAsk` by default). It does not use Grok `plan` mode. Prompts are delivered via Grok `--prompt-file` from a Delegate temp file.
+- Claude safe mode invokes `claude -p` with prompt text on stdin, `--permission-mode plan`, `--strict-mcp-config`, Read/Grep/Glob plus selected read-only Bash tools, and `--no-session-persistence` by default. Delegate does not currently prove that Claude Code hooks, plugins, user settings, or other non-MCP customization surfaces are disabled.
+- `work` mode can edit. By default it runs in the real workspace for backward compatibility.
+
+For edit-capable isolation, use a persistent Git worktree:
+
+```bash
+delegate --isolation worktree cursor work "Implement the scoped change and run the named check."
+delegate --isolation worktree cursor work --forbid-commit "Implement the scoped change without creating commits."
+delegate worktree list
+delegate worktree show <alias-or-runId>
+delegate worktree remove <alias-or-runId>
+```
+
+Worktree isolation protects the source checkout from ordinary relative-path edits. It is **not** a full security sandbox; the child process can still use its runtime permissions, credentials, network access, and absolute paths according to the environment and runtime policy.
+
+Persistent worktree completions and `worktree list/show` include a work summary
+with dirty state, changed file counts, diff stat, and commits created by the
+child where that summary is available. `--forbid-commit` fails the run if
+commits remain ahead of the creation base when the child exits, and it now
+implies `--isolation worktree`.
+
+To carry uncommitted local work into the worktree instead of stashing it, add
+`--include-dirty`: it syncs tracked edits and untracked, non-ignored files into
+the worktree through the same snapshot primitives as safe mode, and tears the
+worktree down before launching the child if that sync fails.
+
+Safe isolation and `--include-dirty` recreate an untracked symlink only when it is relative, resolves inside the source workspace, and its target is not gitignored; any symlink that fails those checks — an absolute target, an escape out of the tree, or a target that is itself a gitignored secret — is replaced with an inert placeholder file, failing closed on any ambiguity. Delegate reports a warning listing the symlink paths it blocked. In Git repositories with no commits yet, Cursor/Codex/Claude/Droid/Kimi safe isolation falls back to a directory copy because Git cannot create a detached worktree from an unborn `HEAD`.
+
+Snapshots and `run-output` redact common credential shapes by default, including authorization headers, bearer/basic tokens, JWT-like strings, and common `token=` / `api_key=` / `password=` values. Use `--no-redact` only when exact output is necessary and safe to display.
+
+## Profile-aware auth and env
+
+A **profile** selects which credentials and environment every delegated harness inherits, so one session can run under, say, a work account and another under a personal account without editing config between runs. Define profiles under the top-level `profiles` block, then either let Delegate detect the active one from an environment variable (`profiles.detectFrom`) or pin it explicitly with `--auth-profile NAME`:
+
+```bash
+delegate --json --auth-profile work profiles    # inspect the resolved profile (read-only)
+delegate --auth-profile work codex safe "Review this diff."
+```
+
+Delegate resolves the profile once per request and injects its env into every spawned child across tracked, pass-through, safe-isolation, and persistent-worktree paths. Profile `env` holds **non-secret routing pointers only** (for example `CODEX_HOME`); secret-shaped keys are rejected at config load, so real credentials stay in your shell or a harness-native key store. See [Configuration](docs/configuration.md#profiles) for the full schema.
+
+If `AI_PROFILE=work|personal` points at a missing profile overlay, Delegate
+blocks launch and mutation commands, but lets read-only diagnostics
+(`profiles`, `runs`, `run-output`, `snapshot`, cached `capabilities`,
+`worktree show`, `worktree list`, `describe`, `models`) continue with a
+warning. This guarantee is enforced in the Python CLI itself (`delegate_agent.cli:main`), so it holds no matter how you invoke Delegate: the
+pip console script, `python -m delegate_agent.cli`, `bin/delegate.py`, or a
+shell shim in front of any of those. The tracked launcher shim template,
+`bin/delegate-profile-shim`, applies the same check earlier, before Python
+even starts, as an additional early gate. Temporary bypasses: `env -u
+AI_PROFILE delegate ...` uses the base config, or set
+`DELEGATE_CONFIG=/path/to/config.json`.
+
+## Useful docs
+
+- [Agent setup](docs/agent-setup.md): human and non-interactive setup flows.
+- [CLI reference](docs/cli-reference.md): commands, exit codes, and JSON contracts.
+- [Configuration](docs/configuration.md): config precedence, sections, and provider-neutral aliases.
+- [Security model](docs/security-model.md): boundaries, limitations, and safe usage.
+- [Worktrees](docs/worktrees.md): persistent-worktree lifecycle and cleanup.
+- [Troubleshooting](docs/troubleshooting.md): common failures and checks.
+- [Contributing](CONTRIBUTING.md) and [Security](SECURITY.md).
+
+## Limitations
+
+- Delegate is an alpha CLI wrapper. Child runtimes can change their own flags or behavior.
+- Safe mode is a policy and isolation pattern, not a guarantee that a runtime cannot perform side effects outside its execution workspace.
+- Persistent worktrees require a Git repository with a valid `HEAD`; work-mode worktree runs require a clean source checkout.
+- `--pass-through` is incompatible with `--json` and with persistent worktree runs.
+- Delegate stores local run metadata under `.delegate/`; do not commit that directory.