ayder-cli 2.5.0__tar.gz → 2.5.1__tar.gz

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/.github/workflows/python-package.yml

@@ -11,6 +11,9 @@ on:
 
 jobs:
   build-and-publish:
+    # The pypi environment admits only main and release-*/beta-* tags, so on a
+    # pull request the job is refused before any step runs and the PR shows red.
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
     # This job only runs in the context of your 'pypi' environment
     environment: pypi 

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ayder-cli
-Version: 2.5.0
+Version: 2.5.1
 Summary: AI agent for any LLMs
 Project-URL: Homepage, https://github.com/ayder/ayder-cli
 Project-URL: Repository, https://github.com/ayder/ayder-cli.git
@@ -82,7 +82,7 @@ LLMs on their own can only generate text. To be a useful coding assistant, the m
 
 Each tool has an OpenAI-compatible JSON schema so models that support function calling can use them natively. For models that don't, ayder-cli also parses a custom XML-like syntax (`<function=name><parameter=key>value</parameter></function>`) as a fallback.
 
-- **Path sandboxing**: All file operations are confined to the project root via `ProjectContext`. Path traversal attacks (`../`) and absolute paths outside the project are blocked.
+- **Path sandboxing**: All file operations are confined to the project root via `ProjectContext`. Path traversal attacks (`../`) and absolute paths outside the project are blocked. The one exception is the session scratch directory, `/tmp/ayder-<uid>/<project>-<hash>/<session>/` (mode 0700, one subdirectory per agent run), which the system prompt names as the place for temporary files and which the file tools accept. It is not cleaned up; the OS clears `/tmp`.
 - **Safe mode** (TUI): Blocks `file_editor`, `run_shell_command`, `run_background_process`, `kill_background_process`, and `fetch_web`.
 - Every tool call requires your confirmation before it runs -- you always stay in control. Use `-r`, `-w`, `-x` flags to auto-approve tool categories.
 - You may also prefer to run ayder-cli in a container for additional security.
@@ -208,7 +208,7 @@ max_output_tokens = 32768     # Max tokens in LLM response
 max_history_messages = 30     # Messages kept in history
 prompt = "STANDARD"           # System prompt tier: MINIMAL, STANDARD, EXTENDED
 tool_tags = ["core", "metadata"]  # Enabled tool tags (see /plugin)
-# skills = ["engineering"]    # or "none"; default: the built-in skills
+# skills = ["development-workflow"]    # or "none"; default: the built-in skills
 agent_timeout = 300           # Seconds before a background agent is cancelled
 
 [logging]
@@ -354,7 +354,8 @@ ayder -f instructions.txt
 ayder --stdin < prompt.txt
 
 # Override the main LLM system prompt with a file
-# (tool instructions are still appended)
+# (the environment section with working directory and start time,
+#  and the tool instructions, are still appended)
 ayder --system-prompt prompt-file.md "refactor this code"
 ```
 
@@ -478,8 +479,9 @@ later one overrides an earlier one with the same name:
 2. your skills in `~/.ayder/skills/<name>/`
 3. project skills in `<project>/.ayder/skills/<name>/`
 
-ayder ships an `engineering` skill (build, change, debug or review code;
-research; plan multi-step work). The system prompt is a general assistant;
+ayder ships a `development-workflow` skill for multi-step software work: a plan
+note and tasks, approval before any project file changes, then execution with
+per-task status. Small edits and questions skip it. The system prompt is a general assistant;
 when a skill fits the request, the model loads it itself.
 
 The skills enabled for a session are listed in the system prompt under
@@ -488,7 +490,7 @@ model. The `skills` setting chooses them:
 
 | `skills` | Enabled skills |
 |---|---|
-| not set | the built-in skills (`engineering`), including your or the project's copy of the same name |
+| not set | the built-in skills (`development-workflow`), including your or the project's copy of the same name |
 | `"none"` or `[]` | none: no skill tool, no catalog |
 | `["a", "b"]` | exactly these names, from any layer |
 

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/README.md

@@ -39,7 +39,7 @@ LLMs on their own can only generate text. To be a useful coding assistant, the m
 
 Each tool has an OpenAI-compatible JSON schema so models that support function calling can use them natively. For models that don't, ayder-cli also parses a custom XML-like syntax (`<function=name><parameter=key>value</parameter></function>`) as a fallback.
 
-- **Path sandboxing**: All file operations are confined to the project root via `ProjectContext`. Path traversal attacks (`../`) and absolute paths outside the project are blocked.
+- **Path sandboxing**: All file operations are confined to the project root via `ProjectContext`. Path traversal attacks (`../`) and absolute paths outside the project are blocked. The one exception is the session scratch directory, `/tmp/ayder-<uid>/<project>-<hash>/<session>/` (mode 0700, one subdirectory per agent run), which the system prompt names as the place for temporary files and which the file tools accept. It is not cleaned up; the OS clears `/tmp`.
 - **Safe mode** (TUI): Blocks `file_editor`, `run_shell_command`, `run_background_process`, `kill_background_process`, and `fetch_web`.
 - Every tool call requires your confirmation before it runs -- you always stay in control. Use `-r`, `-w`, `-x` flags to auto-approve tool categories.
 - You may also prefer to run ayder-cli in a container for additional security.
@@ -165,7 +165,7 @@ max_output_tokens = 32768     # Max tokens in LLM response
 max_history_messages = 30     # Messages kept in history
 prompt = "STANDARD"           # System prompt tier: MINIMAL, STANDARD, EXTENDED
 tool_tags = ["core", "metadata"]  # Enabled tool tags (see /plugin)
-# skills = ["engineering"]    # or "none"; default: the built-in skills
+# skills = ["development-workflow"]    # or "none"; default: the built-in skills
 agent_timeout = 300           # Seconds before a background agent is cancelled
 
 [logging]
@@ -311,7 +311,8 @@ ayder -f instructions.txt
 ayder --stdin < prompt.txt
 
 # Override the main LLM system prompt with a file
-# (tool instructions are still appended)
+# (the environment section with working directory and start time,
+#  and the tool instructions, are still appended)
 ayder --system-prompt prompt-file.md "refactor this code"
 ```
 
@@ -435,8 +436,9 @@ later one overrides an earlier one with the same name:
 2. your skills in `~/.ayder/skills/<name>/`
 3. project skills in `<project>/.ayder/skills/<name>/`
 
-ayder ships an `engineering` skill (build, change, debug or review code;
-research; plan multi-step work). The system prompt is a general assistant;
+ayder ships a `development-workflow` skill for multi-step software work: a plan
+note and tasks, approval before any project file changes, then execution with
+per-task status. Small edits and questions skip it. The system prompt is a general assistant;
 when a skill fits the request, the model loads it itself.
 
 The skills enabled for a session are listed in the system prompt under
@@ -445,7 +447,7 @@ model. The `skills` setting chooses them:
 
 | `skills` | Enabled skills |
 |---|---|
-| not set | the built-in skills (`engineering`), including your or the project's copy of the same name |
+| not set | the built-in skills (`development-workflow`), including your or the project's copy of the same name |
 | `"none"` or `[]` | none: no skill tool, no catalog |
 | `["a", "b"]` | exactly these names, from any layer |
 

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/docs/GATE.md

@@ -12,7 +12,7 @@ Input: the candidate SHA.
    gates and the test suite, and stops at the first failing task.
 4. Copy the final pytest summary line (`=== N passed, M skipped in …s ===`) verbatim.
 
-Last measured: `2707 passed, 2 skipped` on `chore/prompt-tests-injection-only` (2026-10-16).
+Last measured: `2743 passed, 2 skipped` on `fix/session-environment-prompt` (2026-10-19, 2.5.1).
 
 ## Report format
 

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/docs/PROJECT_STRUCTURE.md

@@ -100,7 +100,7 @@ ayder-cli is an AI agent chat client with a modular, layered architecture:
 4. **Single Loop**: `ChatLoop` (in `loops/chat_loop.py`) owns the full async LLM + tool execution loop; both CLI and TUI route through it
 5. **Single Execution Path**: `ExecutionPolicy.execute_with_registry()` is the sole tool execution entry point; validation → permission → execute, no inline policy in loop code
 6. **Single Validation Path**: `ValidationAuthority → SchemaValidator` is the only validation stage; schema derived from live `TOOL_DEFINITIONS` registry (no hardcoded lists)
-7. **Sandboxed Paths**: All file operations go through `ProjectContext` for security
+7. **Sandboxed Paths**: All file operations go through `ProjectContext` for security (project root plus the session scratch directory from `new_scratch_dir`)
 8. **Single Execution Engine**: Both TUI and CLI drive `ChatLoop.run()` through the `ChatCallbacks` protocol (`AppCallbacks` and `CliCallbacks` respectively); CLI runs it via `asyncio.run`
 
 ---
@@ -594,7 +594,7 @@ AyderApp is the main Textual application implementing a chat-style interface:
 The application manages:
 - LLM provider setup and configuration
 - Tool registry initialization with middleware
-- System prompt construction (base prompt + tool prompts + skill catalog; no project tree)
+- System prompt construction (base prompt + environment section + tool prompts + skill catalog; no project tree). The environment section (`prompts.build_environment_prompt`) gives the absolute working directory and the session start date and time (ISO 8601, local time with UTC offset). It is built once per session and reused on `/model` rebuilds.
 - Process manager for background operations
 
 ### Chat Loop Summary (src/ayder_cli/loops/chat_loop.py)

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/docs/config.toml.example

@@ -100,7 +100,7 @@ tool_tags = ["core", "metadata", "background", "http"]
 # Skills the session's model may load (listed under "### Skills" in the system
 # prompt). Not set = the built-in skills; "none" = no skill tool; or a strict
 # list. A [llm.*] profile's skills wins over this one for the session.
-# skills = ["engineering"]
+# skills = ["development-workflow"]
 
 [ui]
 # TUI layout (theme) — picks the chrome/layout:
@@ -229,7 +229,7 @@ think = true                        # default; set false if the selected model r
 [agents.pm_spec]
 provider = "ollama_cloud"
 model = "glm-5.2:cloud"
-# skills = ["engineering"]          # wins over the provider profile's skills; [app] is never read
+# skills = ["development-workflow"] # wins over the provider profile's skills; [app] is never read
 temperature = 0.4
 max_output_tokens = 8192
 reasoning_effort = "high"

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ayder-cli"
-version = "2.5.0"
+version = "2.5.1"
 description = "AI agent for any LLMs"
 readme = "README.md"
 requires-python = ">=3.12"

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/agents/registry.py

@@ -384,7 +384,9 @@ class AgentRegistry:
                                 worktree_path = wt_dir
                                 self._session_worktrees.add(wt_dir)
                                 run.worktree_path = wt_dir
-                                project_ctx = ProjectContext(wt_dir)
+                                project_ctx = ProjectContext(
+                                    wt_dir, scratch_dir=self._project_ctx.scratch_dir
+                                )
                                 head_before = await asyncio.to_thread(
                                     branch_head, repo_root, run.branch_name
                                 )

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/application/runtime_factory.py

@@ -6,7 +6,9 @@ eliminating the duplicate `_build_services()` / `AyderApp.__init__()` wiring.
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass, field
+from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -16,13 +18,14 @@ from ayder_cli.core.context_manager_factory import context_manager_factory
 
 if TYPE_CHECKING:
     from ayder_cli.agents.config import AgentConfig
-from ayder_cli.core.context import ProjectContext
+from ayder_cli.core.context import ProjectContext, new_scratch_dir
 from ayder_cli.core.skills import build_scope
 from ayder_cli.providers import AIProvider, provider_orchestrator
 from ayder_cli.providers.retry import RetryConfig, RetryingProvider
 from ayder_cli.tools.registry import ToolRegistry, create_default_registry
 from ayder_cli.process_manager import ProcessManager
 from ayder_cli.prompts import (
+    build_environment_prompt,
     get_system_prompt,
 )
 from ayder_cli.log import get_logger
@@ -41,6 +44,7 @@ class RuntimeComponents:
     tool_registry: ToolRegistry
     system_prompt: str
     context_manager: Any = field(default=None)  # ContextManagerProtocol
+    environment_prompt: str = ""  # frozen for the session; reused by TUI rebuilds
 
 
 def apply_skill_setting(
@@ -95,6 +99,9 @@ def create_runtime(
 
     llm_provider: AIProvider = provider_orchestrator.create(cfg)
     project_ctx = ProjectContext(project_root)
+    scratch_dir = new_scratch_dir(project_ctx.root)
+    if scratch_dir is not None:
+        project_ctx.scratch_dir = scratch_dir.resolve()
     process_manager = ProcessManager(max_processes=cfg.max_background_processes)
 
     # Create context manager before registry so tools can receive it via DI.
@@ -111,9 +118,12 @@ def create_runtime(
         base_prompt = system_prompt_override
     else:
         base_prompt = get_system_prompt(cfg.prompt)
+    environment_prompt = build_environment_prompt(
+        project_ctx.root, datetime.now().astimezone(), project_ctx.scratch_dir
+    )
     tool_tags = frozenset(cfg.tool_tags) if cfg.tool_tags else None
     tool_prompts = tool_registry.get_system_prompts(tags=tool_tags)
-    system_prompt = base_prompt + tool_prompts
+    system_prompt = base_prompt + environment_prompt + tool_prompts
 
     # Freeze system prompt after tool schemas are known.
     tool_schemas = tool_registry.get_schemas(tags=tool_tags)
@@ -129,6 +139,7 @@ def create_runtime(
         tool_registry=tool_registry,
         system_prompt=system_prompt,
         context_manager=context_mgr,
+        environment_prompt=environment_prompt,
     )
 
 
@@ -232,7 +243,19 @@ def create_agent_runtime(
     )
     tool_tags = frozenset(cfg.tool_tags) if cfg.tool_tags else None
     tool_prompts = tool_registry.get_system_prompts(tags=tool_tags)
-    system_prompt = identity_prefix + agent_config.system_prompt + tool_prompts + deliverable_directive
+    # Each run gets its own directory inside the session's scratch directory,
+    # which the shared ProjectContext already admits.
+    agent_scratch = None
+    if project_ctx.scratch_dir is not None:
+        label = "agent-" + re.sub(r"[^A-Za-z0-9_-]", "-", agent_config.name)
+        agent_scratch = new_scratch_dir(project_ctx.root, parent=project_ctx.scratch_dir, label=label)
+    environment_prompt = build_environment_prompt(
+        project_ctx.root, datetime.now().astimezone(), agent_scratch
+    )
+    system_prompt = (
+        identity_prefix + agent_config.system_prompt + environment_prompt
+        + tool_prompts + deliverable_directive
+    )
 
     # Freeze agent system prompt after tool schemas are known.
     tool_schemas = tool_registry.get_schemas(tags=tool_tags)

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/core/context.py

@@ -1,7 +1,64 @@
+import getpass
+import hashlib
 import os
+import secrets
+import stat
+import tempfile
+from datetime import datetime
 from pathlib import Path
 
 
+def _default_scratch_base() -> Path:
+    """``/tmp/ayder-<uid>``: where models already look for temporary space."""
+    if hasattr(os, "getuid"):
+        return Path("/tmp") / f"ayder-{os.getuid()}"
+    return Path(tempfile.gettempdir()) / f"ayder-{getpass.getuser()}"
+
+
+# Per-user parent of every session scratch directory; tests point it elsewhere.
+SCRATCH_BASE = _default_scratch_base()
+
+
+def _owned_private_dir(path: Path) -> bool:
+    """True when ``path`` itself (not a symlink) is a directory this user owns."""
+    st = os.lstat(path)
+    if not stat.S_ISDIR(st.st_mode):
+        return False
+    return not hasattr(os, "getuid") or st.st_uid == os.getuid()
+
+
+def new_scratch_dir(
+    project_root: Path | str, parent: Path | None = None, label: str = "agent"
+) -> Path | None:
+    """Create a private (0700) scratch directory and return it.
+
+    Without ``parent`` it is a session directory,
+    ``SCRATCH_BASE/<project>-<hash>/<YYYYmmdd-HHMMSS>-<hex>``; with ``parent``
+    it is ``<parent>/<label>-<hex>``. Returns None when the per-user base is a
+    symlink, belongs to someone else, or cannot be created: the session then
+    runs without one and the sandbox stays the project root.
+    """
+    try:
+        if parent is None:
+            SCRATCH_BASE.mkdir(mode=0o700, parents=True, exist_ok=True)
+            if not _owned_private_dir(SCRATCH_BASE):
+                return None
+            os.chmod(SCRATCH_BASE, 0o700)
+            root = Path(project_root).resolve()
+            digest = hashlib.sha256(str(root).encode("utf-8")).hexdigest()[:8]
+            folder = SCRATCH_BASE / f"{root.name}-{digest}"
+            folder.mkdir(mode=0o700, exist_ok=True)
+            name = f"{datetime.now():%Y%m%d-%H%M%S}-{secrets.token_hex(3)}"
+        else:
+            folder = Path(parent)
+            name = f"{label}-{secrets.token_hex(3)}"
+        path = folder / name
+        path.mkdir(mode=0o700)
+        return path
+    except OSError:
+        return None
+
+
 class ProjectContext:
     """Handles path validation and translation between relative and absolute paths.
 
@@ -9,17 +66,21 @@ class ProjectContext:
     macOS ~ paths.
     """
 
-    def __init__(self, root_dir: str = "."):
+    def __init__(self, root_dir: str = ".", scratch_dir: Path | str | None = None):
         """Initialize ProjectContext with a root directory.
 
         Args:
             root_dir: Root directory path (defaults to current directory)
+            scratch_dir: The session scratch directory, a second root the file
+                tools may use (see ``new_scratch_dir``); None allows only the root.
         """
         expanded_root = os.path.expanduser(root_dir)
         self.root = Path(expanded_root).resolve()
+        self.scratch_dir = Path(scratch_dir).resolve() if scratch_dir is not None else None
 
     def validate_path(self, file_path: str) -> Path:
-        """Validate and resolve a file path, ensuring it stays within the project root.
+        """Validate and resolve a file path, ensuring it stays within the project root
+        or the session scratch directory.
 
         Args:
             file_path: Path to validate (relative or absolute)
@@ -37,7 +98,8 @@ class ProjectContext:
         else:
             target_path = (self.root / clean_path).resolve()
 
-        if not target_path.is_relative_to(self.root):
+        in_scratch = self.scratch_dir is not None and target_path.is_relative_to(self.scratch_dir)
+        if not target_path.is_relative_to(self.root) and not in_scratch:
             raise ValueError(
                 f"Security Alert: Path '{target_path}' is outside project root '{self.root}'"
             )

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/core/skills.py

@@ -365,7 +365,8 @@ def render_skill_block(info: SkillInfo) -> str | ToolError:
     _, body = parse_frontmatter(text)
     lines = [
         f"{LOADED_MARKER}{info.name}",
-        f"Source: {info.layer} ({info.path.parent})",
+        # Layer only: models took the skill's absolute path for the project root.
+        f"Source: {info.layer}",
     ]
     resources = skill_resources(info)
     if resources:

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/prompts.py

@@ -4,6 +4,9 @@ Each prompt template is labeled with a comment indicating which module/function
 is responsible for using it, along with the REASON for prompting the LLM.
 """
 
+from datetime import datetime
+from pathlib import Path
+
 # =============================================================================
 # CORE SYSTEM PROMPT
 # =============================================================================
@@ -34,6 +37,55 @@ MINIMAL_SYSTEM_PROMPT = """You are a developer and coding assistant. Analyze und
 
 EXTENDED_SYSTEM_PROMPT = STANDARD_SYSTEM_PROMPT
 
+# =============================================================================
+# SESSION ENVIRONMENT SECTION
+# =============================================================================
+# Used by: runtime_factory.create_runtime() / create_agent_runtime(), after the
+# base prompt and before the tool prompts, for every tier and override.
+# REASON: Without the project's absolute path a model guessed one (the home
+# directory, from a skill header) and ran `git init` there. Built once per
+# session so the frozen prompt and its cache prefix never change.
+
+ENVIRONMENT_PROMPT = """
+
+## Environment
+Working directory: {working_directory}
+Session start: {started_at}{scratch_line}
+
+Your workspace is {workspace}.
+Outside it, read only paths the user names or the task requires, and create,
+modify or initialize nothing (including `git init`) without the user's consent.{scratch_rule}
+"""
+
+# REASON: Models put temporary files in /tmp by habit. A per-session directory
+# there (core/context.py:new_scratch_dir) gives them a sanctioned place, and
+# the file tools accept it. Omitted when the directory could not be created.
+SCRATCH_LINE = "\nScratch directory: {scratch_dir}"
+
+SCRATCH_RULE = "\nPut temporary files in the scratch directory, not in /tmp or ~/tmp."
+
+
+def build_environment_prompt(
+    working_directory: Path, started_at: datetime, scratch_dir: Path | None = None
+) -> str:
+    """Render the session environment section for the system prompt.
+
+    ``started_at`` should be timezone-aware local time; it renders as ISO 8601
+    to the minute with its UTC offset (e.g. 2026-10-19T03:33+03:00).
+    ``scratch_dir`` adds the scratch directory line and its rule.
+    """
+    return ENVIRONMENT_PROMPT.format(
+        working_directory=working_directory,
+        started_at=started_at.isoformat(timespec="minutes"),
+        workspace=(
+            "the working directory and the scratch directory"
+            if scratch_dir
+            else "the working directory"
+        ),
+        scratch_line=SCRATCH_LINE.format(scratch_dir=scratch_dir) if scratch_dir else "",
+        scratch_rule=SCRATCH_RULE if scratch_dir else "",
+    )
+
 # =============================================================================
 # AGENTIC ORCHESTRATOR SYSTEM PROMPT
 # =============================================================================

ayder_cli-2.5.1/src/ayder_cli/skills/development-workflow/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: development-workflow
+description: Multi-step software work - a new feature, a refactor, a bug whose cause is unknown, a change across several files. Not for small, obvious edits, quick fixes or questions that need no change.
+---
+
+# Development workflow
+
+1. Orient: read `AGENTS.md` and `README.md` if they exist, then the code the task touches.
+2. Plan: write the plan with `note(action="create", note_id="plan-<slug>")`: the steps,
+   the files each step touches, and how each step is verified. Create one task per step,
+   in dependency order, with `task(action="create", title=..., body=..., dependencies=...)`.
+   Change no project files before the plan is approved.
+3. Approve: show the user the steps and their verification, name the plan note, and end
+   your turn until the user approves. When the user asks for a reviewer agent, it
+   approves instead: find it with `agent(action="list")`, send it the plan with
+   `agent(action="call", name=..., task=...)`, and collect the verdict with
+   `agent(action="read_result", run_id=..., wait=true)`. On requested changes, update
+   the note and the tasks and ask again.
+4. Execute: work through the tasks in order. Set each one `in_progress` with
+   `task(action="update_status", identifier=..., status="in_progress")` when you start
+   it, `done` when its verification passes, or `blocked` when you need the user, and
+   tell the user why. A large, parallelizable or specialized task can go to an agent with
+   `agent(action="call", task_id=...)`.
+5. Report: one short line at plan created, task started, task done and final delivery.
+   The final delivery says what changed and how it was verified.
+6. Finish: ask before committing, unless the user gave commit instructions. Then unload
+   this skill with `skill(action="unload", name="development-workflow")`.

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/tools/builtins/filesystem_definitions.py

@@ -115,21 +115,21 @@ TOOL_DEFINITIONS: Tuple[ToolDefinition, ...] = (
                 "content": {
                     "type": "string",
                     "description": (
-                        "Content for 'write' (the complete file) or 'insert' (the line). "
+                        "Required for 'write' (the complete file) and 'insert' (the line). "
                         "Accepted up to 10MB."
                     ),
                 },
                 "old_string": {
                     "type": "string",
-                    "description": "Exact string to find for 'replace' operation",
+                    "description": "Required for 'replace'. Exact string to find.",
                 },
                 "new_string": {
                     "type": "string",
-                    "description": "New string to substitute for 'replace' operation",
+                    "description": "Required for 'replace'. New string to substitute.",
                 },
                 "line_number": {
                     "type": "integer",
-                    "description": "Line number (1-based) for 'insert' or 'delete' operations",
+                    "description": "Required for 'insert' and 'delete'. Line number (1-based).",
                 },
                 "replace_all": {
                     "type": "boolean",

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/tools/builtins/shell_definitions.py

@@ -13,7 +13,8 @@ TOOL_DEFINITIONS: Tuple[ToolDefinition, ...] = (
         name="bash",
         description=(
             "Run a shell command and return its exit code, stdout, and stderr. "
-            "Use for builds, tests, git, file inspection, and other terminal tasks."
+            "Use for builds, tests, git, file inspection, and other terminal tasks. "
+            "Each call starts in the working directory; a `cd` does not carry over."
         ),
         description_template="Command `{command}` will be executed",
         tags=("core",),

{ayder_cli-2.5.0 → ayder_cli-2.5.1}/src/ayder_cli/tools/builtins/task_definitions.py

@@ -18,7 +18,8 @@ TOOL_DEFINITIONS: Tuple[ToolDefinition, ...] = (
         name="task",
         description=(
             "Manage .ayder/tasks/ task files. Single tool, dispatched on "
-            "`action`: create | list | show | status | update_status | update. "
+            "`action`: create | list | show | status | update_status | update | "
+            "update_dependencies. "
             "Output is bounded plain text (use offset/limit/max_chars/section to "
             "page); prefer this over file_editor for all task operations."
         ),
@@ -39,12 +40,14 @@ TOOL_DEFINITIONS: Tuple[ToolDefinition, ...] = (
                         "status",
                         "update_status",
                         "update",
+                        "update_dependencies",
                     ],
                     "description": (
                         "Operation to perform. create: new task. list: paged "
                         "rows. show: bounded body/section. status: current "
                         "status. update_status: change status. update: replace "
-                        "one PRD section."
+                        "one PRD section. update_dependencies: replace the "
+                        "dependency list."
                     ),
                 },
                 "title": {
@@ -63,8 +66,11 @@ TOOL_DEFINITIONS: Tuple[ToolDefinition, ...] = (
                 "dependencies": {
                     "type": "string",
                     "description": (
-                        "[create] Comma-separated task IDs this depends on, e.g. "
-                        "'TASK-003,TASK-004' or '3,4'."
+                        "[create/update_dependencies] Comma-separated IDs of "
+                        "existing tasks this one depends on, e.g. 'TASK-003,TASK-004' "
+                        "or '3,4'. A task cannot depend on itself, on a task not yet "
+                        "created, or close a cycle. [update_dependencies] Empty "
+                        "clears the list."
                     ),
                 },
                 "branch": {
@@ -85,7 +91,8 @@ TOOL_DEFINITIONS: Tuple[ToolDefinition, ...] = (
                 "identifier": {
                     "type": "string",
                     "description": (
-                        "[show/status/update_status/update] Task identifier: ID "
+                        "[show/status/update_status/update/update_dependencies] Task "
+                        "identifier: ID "
                         "('7', '007', 'TASK-007'), filename, path, or slug."
                     ),
                 },