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

{ayder_cli-2.5.0 → ayder_cli-2.5.2}/.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.2}/AGENTS.md

@@ -50,115 +50,127 @@ This document provides coding standards, tool configurations, and workflows for
 ayder-cli/
 ├── src/ayder_cli/              # Main source code
 │   ├── cli.py                  # Entry point (argparse)
-│   ├── cli_runner.py           # CLI command execution logic
-│   ├── cli_callbacks.py        # CLI callback implementations
-│   ├── client.py               # ChatSession helpers
+│   ├── __main__.py             # `python -m ayder_cli`
+│   ├── cli_runner.py           # Single-command (non-TUI) runs and task commands
+│   ├── cli_callbacks.py        # CliCallbacks (ChatCallbacks for plain terminal runs)
 │   ├── console.py              # Rich console instance
 │   ├── version.py              # Version info
-│   ├── logging_config.py       # Loguru setup
+│   ├── log.py                  # Channel-scoped loguru accessors
+│   ├── logging_config.py       # Loguru sinks + stdlib-logging bridge
+│   ├── masking.py              # Credential masking for log text
+│   ├── diagnostics.py          # Process-level exception capture
+│   ├── parser.py               # Unified LLM output parser (ContentProcessor)
+│   ├── process_manager.py      # Background processes (own process group, group kill)
+│   ├── prompts.py              # System prompt templates + environment section
+│   ├── ui.py                   # Rich terminal UI helpers
 │   │
 │   ├── core/                   # Core infrastructure
 │   │   ├── config.py           # Pydantic config with validation
-│   │   ├── context.py          # ProjectContext (path sandboxing)
-│   │   └── result.py           # ToolSuccess/ToolError types
+│   │   ├── config_migration.py # Config schema v2.0 migration
+│   │   ├── context.py          # ProjectContext (path sandboxing, scratch dir)
+│   │   ├── result.py           # ToolSuccess/ToolError types
+│   │   ├── session.py          # Save/restore TUI sessions (.ayder/sessions/)
+│   │   ├── skills.py           # Skill discovery, scope, load blocks, active set
+│   │   ├── reasoning.py        # Reasoning settings (think / reasoning_effort)
+│   │   ├── context_manager.py  # ContextManager protocol + shared helpers
+│   │   ├── context_manager_factory.py  # Picks the context manager per provider
+│   │   ├── default_context_manager.py  # Token-budget trimming (non-Ollama)
+│   │   ├── ollama_context_manager.py   # Cache-aware stable-prefix manager (Ollama)
+│   │   └── cache_monitor.py    # KV-cache hit detection
 │   │
 │   ├── agents/                 # Multi-agent system
-│   │   ├── __init__.py         # Package exports
+│   │   ├── config.py           # AgentConfig ([agents.<name>])
+│   │   ├── registry.py         # AgentRegistry (dispatch, queue, lifecycle)
+│   │   ├── run.py              # AgentRun (per-dispatch state the main LLM polls)
+│   │   ├── runner.py           # AgentRunner (one isolated ChatLoop per dispatch)
 │   │   ├── callbacks.py        # AgentCallbacks (ChatCallbacks for agents)
-│   │   ├── config.py           # AgentConfig (Pydantic model)
-│   │   ├── registry.py         # AgentRegistry (lifecycle management)
-│   │   ├── runner.py           # AgentRunner (isolated ChatLoop execution)
-│   │   ├── summary.py          # AgentSummary (structured result)
-│   │   └── tool.py             # call_agent tool definition + handler
+│   │   ├── worktree.py         # Git worktree isolation for agents
+│   │   └── tool.py             # The `agent` tool definition + handler
 │   │
 │   ├── application/            # Shared application layer (CLI + TUI)
-│   │   ├── execution_policy.py         # ExecutionPolicy, PermissionDeniedError
-│   │   ├── message_contract.py         # LLM message format contracts
-│   │   ├── runtime_factory.py          # create_runtime() + create_agent_runtime()
-│   │   ├── temporal_contract.py        # Temporal workflow contracts
-│   │   ├── temporal_metadata.py        # Temporal metadata types
-│   │   └── validation.py              # ValidationAuthority, SchemaValidator
+│   │   ├── execution_policy.py # ExecutionPolicy, PermissionDeniedError
+│   │   ├── message_contract.py # LLM message format contracts
+│   │   ├── runtime_factory.py  # create_runtime() + create_agent_runtime()
+│   │   └── validation.py       # ValidationAuthority, SchemaValidator
 │   │
-│   ├── loops/                  # Shared agent loop + base classes
-│   │   ├── base.py             # AgentLoopBase (iteration, checkpoint, routing)
-│   │   ├── chat_loop.py        # ChatLoop (async LLM + tool execution loop)
-│   │   └── config.py           # Shared LoopConfig dataclass
+│   ├── loops/
+│   │   └── chat_loop.py        # ChatLoop, ChatLoopConfig, ChatCallbacks (the only loop)
 │   │
 │   ├── providers/              # LLM provider implementations
 │   │   ├── base.py             # AIProvider protocol, NormalizedStreamChunk
-│   │   ├── orchestrator.py  # Factory: create(config) → provider
+│   │   ├── orchestrator.py     # Factory: create(config) → provider
+│   │   ├── retry.py            # Retry wrapper (backoff + mid-stream recovery)
 │   │   ├── evren.py            # evren gateway terms-of-use acceptance (/model)
 │   │   └── impl/               # Individual provider drivers
 │   │       ├── openai.py       # OpenAIProvider (base for most drivers)
-│   │       ├── ollama.py       # OllamaProvider (native + XML fallback)
+│   │       ├── ollama.py       # OllamaProvider (routes through ollama_drivers/)
+│   │       ├── ollama_inspector.py  # Model introspection + native tool-call probe
+│   │       ├── ollama_drivers/ # Per-family Ollama chat drivers + resolution matrix
 │   │       ├── claude.py       # ClaudeProvider (Anthropic SDK)
 │   │       ├── gemini.py       # GeminiProvider (Google GenAI SDK)
 │   │       ├── deepseek.py     # DeepSeekProvider (OpenAI-compatible)
 │   │       ├── qwen.py         # QwenNativeProvider (DashScope SDK)
 │   │       └── glm.py          # GLMNativeProvider (ZhipuAI SDK)
 │   │
-│   ├── services/               # Service layer
-│   │   └── interactions.py     # InteractionSink protocol (LLM debug events)
+│   ├── services/
+│   │   ├── interactions.py     # InteractionSink protocol (LLM debug events)
+│   │   └── messaging_inbox.py  # Unix-socket inbox for prompts from peer processes
 │   │
-│   ├── tools/                  # Tool framework + implementations (25 tools)
+│   ├── tools/                  # Tool framework + built-in tools
 │   │   ├── definition.py       # ToolDefinition dataclass + auto-discovery
-│   │   ├── registry.py         # ToolRegistry (schema, execution, system prompts)
+│   │   ├── registry.py         # ToolRegistry (schemas, dispatch, system prompts)
 │   │   ├── schemas.py          # OpenAI-format JSON schemas
-│   │   ├── execution.py        # Tool execution engine
-│   │   ├── hooks.py            # Hook/middleware system
-│   │   ├── normalization.py    # Argument normalization + path resolution
+│   │   ├── execution.py        # Tool execution pipeline
+│   │   ├── hooks.py            # Middleware and execution callbacks
+│   │   ├── normalization.py    # Argument aliases, path resolution, coercion
 │   │   ├── utils.py            # Tool utilities
+│   │   ├── mcp.py              # Built-in MCP tools from .ayder/mcp.json
+│   │   ├── mcp_client.py       # MCP sessions + synchronous dispatch bridge
+│   │   ├── plugin_manager.py   # Install/update/load external plugins
+│   │   ├── plugin_api.py       # Plugin API version checks
+│   │   ├── plugin_github.py    # Plugin download from GitHub
+│   │   ├── plugin_status.py    # Plugin status badges
 │   │   └── builtins/           # Built-in tool implementations
-│   │       ├── *_definitions.py # Distributed tool definitions (13 files)
-│   │       ├── filesystem.py   # file_explorer, read_file, file_editor
-│   │       ├── python_editor.py # CST-based Python structural editor
-│   │       ├── search.py       # search_codebase, get_project_structure
-│   │       ├── shell.py        # run_shell_command
-│   │       ├── venv.py         # Virtualenv management tools
-│   │       ├── utils_tools.py  # manage_environment_vars
-│   │       ├── web.py          # fetch_web
-│   │       ├── dbs_tool.py     # DBS RAG API tool
-│   │       ├── temporal.py     # Temporal workflow tool
-│   │       ├── tasks.py        # Task management (.ayder/tasks/)
-│   │       ├── notes.py        # Note management (.ayder/notes/)
-│   │       └── memory.py       # Cross-session memory storage
+│   │       ├── *_definitions.py       # Tool definitions, auto-discovered
+│   │       ├── filesystem.py          # file_explorer, read_file, file_editor
+│   │       ├── search.py              # search_codebase
+│   │       ├── utils_tools.py         # get_project_structure, manage_environment_vars
+│   │       ├── shell.py               # bash
+│   │       ├── background_process_tool.py  # background_process
+│   │       ├── context.py             # context (stats, save/load, compact)
+│   │       ├── note_tool.py           # note
+│   │       ├── notes.py               # Note storage (.ayder/notes/)
+│   │       ├── task_tool.py           # task
+│   │       ├── tasks.py               # Task files (.ayder/tasks/)
+│   │       ├── skill.py               # skill
+│   │       └── web.py                 # fetch_web
 │   │
 │   ├── tui/                    # Textual TUI (main interface)
 │   │   ├── __init__.py         # run_tui() entry point
 │   │   ├── app.py              # AyderApp main application
-│   │   ├── chat_loop.py        # Backward-compat re-exports → loops/chat_loop.py
-│   │   ├── commands.py         # Slash command handlers (19 commands)
+│   │   ├── commands.py         # Slash command handlers
+│   │   ├── keybindings.py      # Keybinding registry
 │   │   ├── helpers.py          # TUI helper functions
 │   │   ├── adapter.py          # TUIInteractionSink (verbose debug)
-│   │   ├── parser.py           # Message parsing
-│   │   ├── screens.py          # Modal screens (confirm, select, permission, task edit)
+│   │   ├── parser.py           # Re-exports of the unified ContentProcessor
+│   │   ├── rendering.py        # Safe render helpers
+│   │   ├── screens.py          # Modal screens (confirm, select, permission, task edit, …)
 │   │   ├── theme_manager.py    # Theme loading and CSS
 │   │   ├── types.py            # MessageType, ConfirmResult
-│   │   └── widgets.py          # ChatView, ToolPanel, CLIInputBar, StatusBar
+│   │   └── widgets.py          # ChatView, ToolPanel, CLIInputBar, StatusBar, …
 │   │
-│   ├── themes/                 # TUI themes
-│   │   ├── __init__.py         # Theme registry
-│   │   ├── claude.py           # Claude theme CSS (default, RGB)
-│   │   └── ayder.py            # ayder tokenised layout + ANSI/RGB palette overlay ([ui] palette)
+│   ├── skills/                 # Packaged built-in skills (development-workflow/SKILL.md)
 │   │
-│   ├── parser.py               # XML/JSON tool call parser
-│   ├── process_manager.py      # Background process management
-│   ├── prompts.py              # System prompt templates
-│   └── ui.py                   # Rich terminal UI helpers
+│   └── themes/                 # TUI themes
+│       ├── claude.py           # Claude theme CSS (RGB)
+│       └── ayder.py            # ayder tokenised layout + ANSI/RGB palette ([ui] palette)
 │
-├── tests/                      # Test suite (998+ tests)
-│   ├── application/            # Application layer tests
-│   ├── core/                   # Core tests
-│   ├── services/               # Services tests
-│   ├── tools/                  # Tool tests
-│   ├── ui/                     # TUI tests
-│   └── *.py                    # Top-level tests
-│
-├── .ayder/                     # Project-specific data (tasks, notes, memory, skills)
+├── tests/                      # Test suite, mirrors src/ (agents/, core/, loops/, tools/, tui/, …)
+├── docs/                       # GATE.md, PROJECT_STRUCTURE.md, config.toml.example, guides
+├── .ayder/                     # Project data (tasks, notes, sessions, skills); gitignored
 ├── pyproject.toml              # Project configuration
 ├── AGENTS.md                   # This file
-├── README.md                   # Project overview
-└── .claude/                    # Claude Code configuration + skills
+└── README.md                   # Project overview
 ```
 
 ### Key Files Reference
@@ -167,14 +179,12 @@ ayder-cli/
 |------|---------|
 | `cli.py` | Entry point, argument parsing |
 | `tui/app.py` | Main TUI application (AyderApp) |
-| `tui/commands.py` | Slash command handlers (19 commands) |
+| `tui/commands.py` | Slash command handlers |
 | `loops/chat_loop.py` | Async LLM + tool execution loop (ChatLoop + ChatCallbacks protocol) |
-| `tui/chat_loop.py` | Backward-compat re-exports (TuiChatLoop → ChatLoop aliases) |
-| `cli_runner.py` | CLI command execution + sync agent loop |
+| `cli_runner.py` | Single-command (non-TUI) runs |
 | `application/runtime_factory.py` | `create_runtime()` — single composition root for CLI + TUI |
 | `application/execution_policy.py` | Shared permission + tool execution policy |
 | `application/validation.py` | ValidationAuthority + SchemaValidator (single validation path) |
-| `loops/base.py` | AgentLoopBase shared by CLI and TUI loops |
 | `tools/definition.py` | ToolDefinition dataclass + auto-discovery from `*_definitions.py` |
 | `tools/registry.py` | ToolRegistry: schemas, execution, system prompts, tag filtering |
 | `core/config.py` | Configuration with Pydantic validation |
@@ -183,7 +193,7 @@ ayder-cli/
 | `providers/impl/ollama_drivers/` | Per-family Ollama chat-driver package (matrix, registry, drivers, error classifier) |
 | `providers/impl/ollama_inspector.py` | `OllamaInspector` with `probe_native_tool_calling()` for empirical model verification |
 | `docs/README_OLLAMA.md` | **Ollama tool-call compatibility guide.** Read before adding/changing any matrix routing for an Ollama model. Covers the `OllamaInspector.probe_native_tool_calling()` API, equivalent `curl` recipes, the markup-leak detection table, and the decision flow for new families. |
-| `docs/superpowers/specs/2026-05-02-ollama-chat-drivers-design.md` | Design spec for the per-family Ollama chat-drivers architecture. |
+| `docs/GATE.md` | The gate procedure every PR's final SHA passes |
 
 ## Environment Setup
 
@@ -431,7 +441,7 @@ class TestFeature:
 
 ### Runtime Factory
 
-`application/runtime_factory.py` provides `create_runtime()` — the single composition root used by both CLI and TUI. It assembles a `RuntimeComponents` dataclass containing: `config`, `llm_provider`, `process_manager`, `project_ctx`, `tool_registry`, `memory_manager`, `system_prompt`.
+`application/runtime_factory.py` provides `create_runtime()` — the single composition root used by both CLI and TUI. It assembles a `RuntimeComponents` dataclass containing: `config`, `llm_provider`, `process_manager`, `project_ctx`, `tool_registry`, `system_prompt`, `context_manager`, `environment_prompt`.
 
 ### Pluggable Tool System
 
@@ -460,23 +470,21 @@ TOOL_DEFINITIONS: tuple[ToolDefinition, ...] = (
 )
 ```
 
-**Current Tools (25 total):**
+**Built-in Tools** (plugins and MCP servers add more at runtime; `tests/test_agents_md.py` keeps this table in step with the registry):
 
 | Category | Tag | Tools |
 |----------|-----|-------|
 | **Filesystem** | `core` | `file_explorer`, `read_file`, `file_editor` |
 | **Search** | `core` | `search_codebase`, `get_project_structure` |
-| **Shell** | `core` | `run_shell_command` |
-| **Memory** | `metadata` | `save_memory`, `load_memory` |
-| **Notes** | `metadata` | `create_note` |
-| **Tasks** | `metadata` | `list_tasks`, `show_task` |
-| **Python Editor** | `python` | `python_editor` (CST-based structural editing) |
-| **Background Processes** | `background` | `run_background_process`, `get_background_output`, `kill_background_process`, `list_background_processes` |
-| **Virtual Environments** | `venv` | `create_virtualenv`, `install_requirements`, `list_virtualenvs`, `activate_virtualenv`, `remove_virtualenv` |
+| **Shell** | `core` | `bash` |
+| **Session context** | `core` | `context` |
+| **Skills** | `core` | `skill` |
+| **Agents** | `core` | `agent` (registered when agents are configured) |
+| **Notes** | `metadata` | `note` |
+| **Tasks** | `metadata` | `task` |
+| **Background Processes** | `background` | `background_process` |
 | **Web** | `http` | `fetch_web` |
-| **DBS** | `dbs` | `dbs_tool` (RAG API for DBS issues) |
 | **Environment** | `env` | `manage_environment_vars` |
-| **Temporal** | `temporal` | `temporal_workflow` |
 
 **Tag System:** Tools are filtered by tags. Default enabled tags: `["core", "metadata"]`. Use `/plugin` in TUI to toggle additional tags at runtime.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ayder-cli
-Version: 2.5.0
+Version: 2.5.2
 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.
@@ -203,12 +203,12 @@ provider = "openai"           # Active provider profile name
 editor = "vim"                # Editor for /task-edit command
 verbose = false               # Show file contents after write + LLM debug
 max_background_processes = 5  # Max concurrent background processes (1-20)
-max_iterations = 10           # Max agentic iterations per message (1-100)
+max_iterations = 200          # LLM calls per message before the loop stops (0 = unlimited)
 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 |
 
@@ -584,7 +586,7 @@ ayder-cli includes a built-in task system:
 
 Tasks are stored as markdown files in `.ayder/tasks/` using slug-based filenames (e.g., `TASK-001-add-auth-middleware.md`).
 
-The `task` tool resolves identifiers (a path, filename, ID or slug) only to files inside `.ayder/tasks/`. An identifier that points elsewhere, including through a symlink, is not resolved. If `.ayder/tasks/`, `.ayder/context/` or `.ayder/notes/` itself resolves outside the project, those tools return a security error.
+The `task` tool resolves identifiers (a path, filename, ID or slug) only to files inside `.ayder/tasks/`. An identifier that points elsewhere, including through a symlink, is not resolved. If `.ayder/tasks/`, `.ayder/context/` or `.ayder/notes/` itself resolves outside the project, those tools return a security error. An ID (`7`, `007`, `TASK-007`) matches only that task. A slug must match one task (an exact slug wins); if several match, the tool lists them and asks for the ID. `section` names a `##` heading; the `#` title is never a section.
 
 ```
 > /tasks            # Interactive task browser
@@ -774,7 +776,8 @@ project root, then start Ayder:
     "local-tools": {
       "command": "python",
       "args": ["server.py"],
-      "env": {"EXAMPLE_SETTING": "value"}
+      "env": {"EXAMPLE_SETTING": "value"},
+      "parallel": false
     },
     "remote-tools": {
       "url": "http://localhost:8000/mcp"
@@ -790,6 +793,16 @@ is needed. Tool calls retain the usual permissions: `x` for stdio servers and
 `http` for HTTP servers. Configure only servers you intend Ayder to connect to:
 local server commands start during runtime initialization to discover tools.
 
+Calls to MCP tools in one response run at the same time by default. Set
+`"parallel": false` on a server to run its calls one at a time, in the order the
+model sent them. Do this for servers that write local files, so a read sent in
+the same response cannot see the file before the write. `"parallel": true` runs
+all of a server's tools concurrently, whatever the server declares. Without the
+key, the server's own tool annotations decide: a tool marked `readOnlyHint`
+runs concurrently, and one marked `readOnlyHint: false` or `destructiveHint`
+runs alone. MCP calls always wait for built-in tools that change things
+(`file_editor`, `bash`, ...) sent before them.
+
 Tools keep their server-provided names unless they conflict with an existing
 tool; conflicting names receive a `server__` prefix (and a numeric suffix if
 needed). Unreachable servers are skipped so other tools remain available.

{ayder_cli-2.5.0 → ayder_cli-2.5.2}/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.
@@ -160,12 +160,12 @@ provider = "openai"           # Active provider profile name
 editor = "vim"                # Editor for /task-edit command
 verbose = false               # Show file contents after write + LLM debug
 max_background_processes = 5  # Max concurrent background processes (1-20)
-max_iterations = 10           # Max agentic iterations per message (1-100)
+max_iterations = 200          # LLM calls per message before the loop stops (0 = unlimited)
 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 |
 
@@ -541,7 +543,7 @@ ayder-cli includes a built-in task system:
 
 Tasks are stored as markdown files in `.ayder/tasks/` using slug-based filenames (e.g., `TASK-001-add-auth-middleware.md`).
 
-The `task` tool resolves identifiers (a path, filename, ID or slug) only to files inside `.ayder/tasks/`. An identifier that points elsewhere, including through a symlink, is not resolved. If `.ayder/tasks/`, `.ayder/context/` or `.ayder/notes/` itself resolves outside the project, those tools return a security error.
+The `task` tool resolves identifiers (a path, filename, ID or slug) only to files inside `.ayder/tasks/`. An identifier that points elsewhere, including through a symlink, is not resolved. If `.ayder/tasks/`, `.ayder/context/` or `.ayder/notes/` itself resolves outside the project, those tools return a security error. An ID (`7`, `007`, `TASK-007`) matches only that task. A slug must match one task (an exact slug wins); if several match, the tool lists them and asks for the ID. `section` names a `##` heading; the `#` title is never a section.
 
 ```
 > /tasks            # Interactive task browser
@@ -731,7 +733,8 @@ project root, then start Ayder:
     "local-tools": {
       "command": "python",
       "args": ["server.py"],
-      "env": {"EXAMPLE_SETTING": "value"}
+      "env": {"EXAMPLE_SETTING": "value"},
+      "parallel": false
     },
     "remote-tools": {
       "url": "http://localhost:8000/mcp"
@@ -747,6 +750,16 @@ is needed. Tool calls retain the usual permissions: `x` for stdio servers and
 `http` for HTTP servers. Configure only servers you intend Ayder to connect to:
 local server commands start during runtime initialization to discover tools.
 
+Calls to MCP tools in one response run at the same time by default. Set
+`"parallel": false` on a server to run its calls one at a time, in the order the
+model sent them. Do this for servers that write local files, so a read sent in
+the same response cannot see the file before the write. `"parallel": true` runs
+all of a server's tools concurrently, whatever the server declares. Without the
+key, the server's own tool annotations decide: a tool marked `readOnlyHint`
+runs concurrently, and one marked `readOnlyHint: false` or `destructiveHint`
+runs alone. MCP calls always wait for built-in tools that change things
+(`file_editor`, `bash`, ...) sent before them.
+
 Tools keep their server-provided names unless they conflict with an existing
 tool; conflicting names receive a `server__` prefix (and a numeric suffix if
 needed). Unreachable servers are skipped so other tools remain available.

{ayder_cli-2.5.0 → ayder_cli-2.5.2}/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: `2909 passed, 2 skipped` on `fix/docs-skill-list-2.5.2` (2026-10-22, release 2.5.2).
 
 ## Report format
 

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

@@ -97,10 +97,10 @@ ayder-cli is an AI agent chat client with a modular, layered architecture:
 1. **Layered Architecture**: Clear separation between entry → app → service → core → tools
 2. **Protocol-Based**: `ChatCallbacks` protocol decouples the chat loop from UI concerns; `InteractionSink` decouples LLM providers from UI for debug events
 3. **Single Composition Root**: `application/runtime_factory.create_runtime()` assembles all dependencies — no duplicated wiring between CLI and TUI
-4. **Single Loop**: `ChatLoop` (in `loops/chat_loop.py`) owns the full async LLM + tool execution loop; both CLI and TUI route through it
+4. **Single Loop**: `ChatLoop` (in `loops/chat_loop.py`) owns the full async LLM + tool execution loop; both CLI and TUI route through it. A run ends on a text-only reply, a cancel, an error, `max_iterations` LLM calls (`[app]` 200, agents 100), or 3 reasoning-only replies in a row; from the 3rd identical tool call in a row, the result carries a `[harness]` note
 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`). Only a path outside the sandbox (`PathOutsideSandboxError`) is reported as a security error; other bad input, such as a binary file or a non-numeric line number, is a validation error
 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`
 
 ---
@@ -293,7 +293,7 @@ the design rationale.
 | `tools/plugin_github.py` | GitHub-sourced plugin fetcher | remote-plugin loader |
 | `tools/builtins/filesystem.py` | File system tool impls | `file_explorer()`, `read_file()`, `file_editor()` |
 | `tools/builtins/search.py` | Search tool impls | `search_codebase()`, `get_project_structure()` |
-| `tools/builtins/shell.py` | Shell execution impl | `bash()` |
+| `tools/builtins/shell.py` | Shell execution impl: own session, closed stdin, prompts/pagers off (`GIT_TERMINAL_PROMPT=0`, `PAGER`/`GIT_PAGER=cat`; `environment` overrides), process-group kill on timeout with partial output, per-stream output bounds | `bash()` |
 | `tools/builtins/context.py` | Session context snapshots | `context` |
 | `tools/builtins/notes.py` | Note-taking tool | `create_note()` |
 | `tools/builtins/tasks.py` | Task-management tools | `list_tasks()`, `show_task()` |
@@ -306,7 +306,7 @@ the design rationale.
 
 | Module | Purpose | Key Classes/Functions |
 |--------|---------|----------------------|
-| `process_manager.py` | Background processes | `ProcessManager`, `background_process()` |
+| `process_manager.py` | Background processes (closed stdin; `stop` and exit cleanup kill the whole process group, also after the leader exited) | `ProcessManager`, `background_process()` |
 | `prompts.py` | System prompts | `SYSTEM_PROMPT`, `PLANNING_PROMPT_TEMPLATE`, `get_system_prompt()` |
 | `parser.py` | XML tool-call parsing | `parse_custom_tool_calls()` |
 
@@ -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. A resumed session (`--resume`) restores the provider it last used (the session file stores it; a provider no longer configured falls back to the default with a warning) and its `--system-prompt` text, keeps its history, and rebuilds the system prompt for the current session, so the scratch directory, start time, tool prompts and agent capability prompts are current; `/model` rebuilds keep the capability prompts.
 - Process manager for background operations
 
 ### Chat Loop Summary (src/ayder_cli/loops/chat_loop.py)
@@ -609,7 +609,7 @@ previously-split `AgentLoopBase` and `LoopConfig` were merged back in):
 - Routes *every* LLM response through the injected `ContextManagerProtocol` (`prepare_messages()` / `update_from_response()`); tool outputs are truncated at insertion time via `truncate_tool_result()` so the KV-cache prefix remains stable
 
 Key features:
-- Auto-approved tools run in parallel (`asyncio.as_completed`); confirmation-required tools run sequentially
+- Tool calls run in emission order. Consecutive calls that are parallel-safe (`ToolDefinition.parallel_safe`, default False) and auto-approved run concurrently (`asyncio.as_completed`). Every other call runs alone, after confirmation if required. Once the user answers a confirmation with instructions, no later call in the batch runs. MCP tools default to parallel-safe; `.ayder/mcp.json` `"parallel"` and the tools' annotations override that
 - Confirmation gate applies to **both** OpenAI-format and XML/JSON custom tool calls
 - `ExecutionPolicy.execute_with_registry()` is the single execution entry (object check → `canonicalize_arguments()` → validate → permission → execute). Canonicalization applies aliases and `"123"`/`"true"`/`"false"` coercion; the loop's required-argument gate uses the same function
 - Argument integrity: `_parse_tool_arguments()` reports `ok`, `repaired` or `invalid`. Non-object arguments never run. Arguments repaired after being cut off (output token limit) run only for tools registered explicitly as `r`; other tools get an error asking the model to resend in smaller calls
@@ -645,6 +645,7 @@ Schema-driven tool definitions with auto-discovery:
 - **Required-tool validation**: Raises `ImportError` if core tools (`file_explorer`, `read_file`, `file_editor`, `bash`) are absent
 - **Permissions**: `"r"` (read), `"w"` (write), `"x"` (execute), `"http"` (network)
 - **Safety flags**: `safe_mode_blocked`, `is_terminal` per definition
+- **Scheduling**: `parallel_safe` per definition: a bool, or a predicate over the call's arguments (`parallel_safe_when("action", ...)`); unknown tools are never parallel-safe
 - **Path parameters**: Names listed in `path_parameters` are automatically resolved via `ProjectContext`
 - **Aliases**: `parameter_aliases` tuples for common name normalisation
 - **Schema generation**: `to_openai_schema()` returns the OpenAI function-calling dict

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

@@ -92,6 +92,8 @@ max_output_tokens = 8192            # orchestrator response cap
 # window on a large-context model and wastes most of it. Set a finite number
 # only if you want a hard message cap regardless of window size.
 max_history_messages = 0
+# LLM calls per user message before the loop stops and asks for input. 0 = unlimited.
+max_iterations = 200
 agent_timeout = 1800               # seconds before a background agent is cancelled (30 min; reasoning+coding can be slow)
 # Tools the agents inherit. A coding harness needs file/shell/search (core),
 # tasks/notes (metadata), background process control for test suites
@@ -100,7 +102,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,9 +231,10 @@ 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
+# max_iterations = 100           # LLM calls per run (default 100; 0 = unlimited)
 reasoning_effort = "high"
 system_prompt = """
 You are Project Manager #1 — the requirements analyst and spec author.

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

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

{ayder_cli-2.5.0 → ayder_cli-2.5.2}/src/ayder_cli/agents/config.py

@@ -31,6 +31,8 @@ class AgentConfig(BaseModel):
     num_ctx: int | None = None
     temperature: float | None = None
     max_output_tokens: int | None = None
+    # LLM calls per run before the loop stops; None = 100, 0 = unlimited.
+    max_iterations: int | None = None
     think: ThinkOption = None
     reasoning_effort: ReasoningEffort = None
     # None: the provider profile's setting; "none" or a list: see Config.skills.
@@ -57,7 +59,7 @@ class AgentConfig(BaseModel):
                     new_data[key] = float(val)
                 except ValueError:
                     pass
-        for key in ("num_ctx", "max_output_tokens"):
+        for key in ("num_ctx", "max_output_tokens", "max_iterations"):
             val = new_data.get(key)
             if isinstance(val, str) and val.strip():
                 try:

{ayder_cli-2.5.0 → ayder_cli-2.5.2}/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
                                 )