ripperdoc 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

ripperdoc/core/query_utils.py

@@ -7,7 +7,7 @@ import re
 from typing import Any, Dict, List, Mapping, Optional, Union
 from uuid import uuid4
 
-from json_repair import repair_json
+from json_repair import repair_json  # type: ignore[import-not-found]
 from pydantic import ValidationError
 
 from ripperdoc.core.config import ModelProfile, ProviderType, get_global_config
@@ -66,16 +66,43 @@ def anthropic_usage_tokens(usage: Optional[Mapping[str, Any] | object]) -> Dict[
 def openai_usage_tokens(usage: Optional[Mapping[str, Any] | object]) -> Dict[str, int]:
     """Extract token counts from an OpenAI-compatible response usage payload."""
     prompt_details = None
+    input_details = None
+    output_details = None
     if isinstance(usage, dict):
         prompt_details = usage.get("prompt_tokens_details")
+        input_details = usage.get("input_tokens_details")
+        output_details = usage.get("output_tokens_details")
     else:
         prompt_details = getattr(usage, "prompt_tokens_details", None)
-
-    cache_read_tokens = _get_usage_field(prompt_details, "cached_tokens") if prompt_details else 0
+        input_details = getattr(usage, "input_tokens_details", None)
+        output_details = getattr(usage, "output_tokens_details", None)
+
+    cache_read_tokens = 0
+    if prompt_details:
+        cache_read_tokens = _get_usage_field(prompt_details, "cached_tokens")
+    if not cache_read_tokens and input_details:
+        cache_read_tokens = _get_usage_field(input_details, "cached_tokens")
+
+    input_tokens = _get_usage_field(usage, "prompt_tokens")
+    if not input_tokens:
+        input_tokens = _get_usage_field(usage, "input_tokens")
+
+    output_tokens = _get_usage_field(usage, "completion_tokens")
+    if not output_tokens:
+        output_tokens = _get_usage_field(usage, "output_tokens")
+
+    reasoning_tokens = _get_usage_field(output_details, "reasoning_tokens") if output_details else 0
+    if reasoning_tokens:
+        if output_tokens <= 0:
+            output_tokens = reasoning_tokens
+        elif output_tokens < reasoning_tokens:
+            output_tokens = output_tokens + reasoning_tokens
+        else:
+            output_tokens = max(output_tokens, reasoning_tokens)
 
     return {
-        "input_tokens": _get_usage_field(usage, "prompt_tokens"),
-        "output_tokens": _get_usage_field(usage, "completion_tokens"),
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
         "cache_read_input_tokens": cache_read_tokens,
         "cache_creation_input_tokens": 0,
     }
@@ -219,10 +246,10 @@ def _tool_prompt_for_text_mode(tools: List[Tool[Any, Any]]) -> str:
                 if hasattr(finfo, "is_required"):
                     try:
                         is_req = bool(finfo.is_required())
-                    except Exception:
+                    except (TypeError, AttributeError):
                         is_req = False
                 required_fields.append(f"{fname}{' (required)' if is_req else ''}")
-        except Exception:
+        except (AttributeError, TypeError):
             required_fields = []
 
         required_str = ", ".join(required_fields) if required_fields else "see input schema"
@@ -487,6 +514,23 @@ def content_blocks_from_anthropic_response(response: Any, tool_mode: str) -> Lis
         btype = getattr(block, "type", None)
         if btype == "text":
             blocks.append({"type": "text", "text": getattr(block, "text", "")})
+        elif btype == "thinking":
+            blocks.append(
+                {
+                    "type": "thinking",
+                    "thinking": getattr(block, "thinking", None) or "",
+                    "signature": getattr(block, "signature", None),
+                }
+            )
+        elif btype == "redacted_thinking":
+            # Preserve encrypted payload for replay even if we don't display it.
+            blocks.append(
+                {
+                    "type": "redacted_thinking",
+                    "data": getattr(block, "data", None),
+                    "signature": getattr(block, "signature", None),
+                }
+            )
         elif btype == "tool_use":
             raw_input = getattr(block, "input", {}) or {}
             blocks.append(

ripperdoc/core/skills.py

@@ -0,0 +1,295 @@
+"""Agent Skill loading helpers for Ripperdoc.
+
+Skills are small capability bundles defined by SKILL.md files that live under
+`~/.ripperdoc/skills` or `.ripperdoc/skills` in a project. Only the skill
+metadata (name + description) should be added to the system prompt up front;
+the full content is loaded on demand via the Skill tool. Optional frontmatter
+fields include:
+- allowed-tools: Comma-separated list of tools that are allowed/preferred.
+- model: Model pointer hint for this skill.
+- max-thinking-tokens: Reasoning budget hint for this skill.
+- disable-model-invocation: If true, block the Skill tool from loading this
+  skill.
+- type: Skill kind (defaults to "prompt").
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+import yaml
+
+from ripperdoc.utils.coerce import parse_boolish, parse_optional_int
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+SKILL_DIR_NAME = "skills"
+SKILL_FILE_NAME = "SKILL.md"
+_SKILL_NAME_RE = re.compile(r"^[a-z0-9-]{1,64}$")
+
+
+class SkillLocation(str, Enum):
+    """Where a skill definition is sourced from."""
+
+    USER = "user"
+    PROJECT = "project"
+    OTHER = "other"
+
+
+@dataclass
+class SkillDefinition:
+    """Parsed representation of a skill."""
+
+    name: str
+    description: str
+    content: str
+    path: Path
+    base_dir: Path
+    location: SkillLocation
+    allowed_tools: List[str]
+    model: Optional[str] = None
+    max_thinking_tokens: Optional[int] = None
+    skill_type: str = "prompt"
+    disable_model_invocation: bool = False
+
+
+@dataclass
+class SkillLoadError:
+    """Error encountered while loading a skill file."""
+
+    path: Path
+    reason: str
+
+
+@dataclass
+class SkillLoadResult:
+    """Aggregated result of loading skills."""
+
+    skills: List[SkillDefinition]
+    errors: List[SkillLoadError]
+
+
+def _split_frontmatter(raw_text: str) -> Tuple[Dict[str, Any], str]:
+    """Extract YAML frontmatter and body content from a markdown file."""
+    lines = raw_text.splitlines()
+    if len(lines) >= 3 and lines[0].strip() == "---":
+        for idx in range(1, len(lines)):
+            if lines[idx].strip() == "---":
+                frontmatter_text = "\n".join(lines[1:idx])
+                body = "\n".join(lines[idx + 1 :])
+                try:
+                    frontmatter = yaml.safe_load(frontmatter_text) or {}
+                except (yaml.YAMLError, ValueError, TypeError) as exc:  # pragma: no cover - defensive
+                    logger.warning(
+                        "[skills] Invalid frontmatter in SKILL.md: %s: %s",
+                        type(exc).__name__, exc,
+                    )
+                    return {"__error__": f"Invalid frontmatter: {exc}"}, body
+                return frontmatter, body
+    return {}, raw_text
+
+
+def _normalize_allowed_tools(value: object) -> List[str]:
+    """Normalize allowed-tools values to a clean list of tool names."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [item.strip() for item in value.split(",") if item.strip()]
+    if isinstance(value, Iterable):
+        tools: List[str] = []
+        for item in value:
+            if isinstance(item, str) and item.strip():
+                tools.append(item.strip())
+        return tools
+    return []
+
+
+def _load_skill_file(
+    path: Path, location: SkillLocation
+) -> Tuple[Optional[SkillDefinition], Optional[SkillLoadError]]:
+    """Parse a single SKILL.md file."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, IOError, UnicodeDecodeError) as exc:
+        logger.warning(
+            "[skills] Failed to read skill file: %s: %s",
+            type(exc).__name__, exc,
+            extra={"path": str(path)},
+        )
+        return None, SkillLoadError(path=path, reason=f"Failed to read file: {exc}")
+
+    frontmatter, body = _split_frontmatter(text)
+    if "__error__" in frontmatter:
+        return None, SkillLoadError(path=path, reason=str(frontmatter["__error__"]))
+
+    raw_name = frontmatter.get("name")
+    raw_description = frontmatter.get("description")
+    if not isinstance(raw_name, str) or not raw_name.strip():
+        return None, SkillLoadError(path=path, reason='Missing required "name" field')
+    if not _SKILL_NAME_RE.match(raw_name.strip()):
+        return None, SkillLoadError(
+            path=path,
+            reason='Invalid "name" format. Use lowercase letters, numbers, and hyphens only (max 64 chars).',
+        )
+    if not isinstance(raw_description, str) or not raw_description.strip():
+        return None, SkillLoadError(path=path, reason='Missing required "description" field')
+
+    allowed_tools = _normalize_allowed_tools(
+        frontmatter.get("allowed-tools") or frontmatter.get("allowed_tools")
+    )
+    model_value = frontmatter.get("model")
+    model = model_value if isinstance(model_value, str) and model_value.strip() else None
+    max_thinking_tokens = parse_optional_int(
+        frontmatter.get("max-thinking-tokens") or frontmatter.get("max_thinking_tokens")
+    )
+    raw_type = (
+        frontmatter.get("type")
+        or frontmatter.get("skill-type")
+        or frontmatter.get("skill_type")
+        or "prompt"
+    )
+    skill_type = str(raw_type).strip().lower() if isinstance(raw_type, str) else "prompt"
+    disable_model_invocation = parse_boolish(
+        frontmatter.get("disable-model-invocation") or frontmatter.get("disable_model_invocation")
+    )
+
+    skill = SkillDefinition(
+        name=raw_name.strip(),
+        description=raw_description.strip(),
+        content=body.strip(),
+        path=path,
+        base_dir=path.parent,
+        location=location,
+        allowed_tools=allowed_tools,
+        model=model,
+        max_thinking_tokens=max_thinking_tokens,
+        skill_type=skill_type or "prompt",
+        disable_model_invocation=disable_model_invocation,
+    )
+    return skill, None
+
+
+def _load_skill_dir(
+    path: Path, location: SkillLocation
+) -> Tuple[List[SkillDefinition], List[SkillLoadError]]:
+    """Load skills from a directory that either contains SKILL.md or subdirectories."""
+    skills: List[SkillDefinition] = []
+    errors: List[SkillLoadError] = []
+    if not path.exists() or not path.is_dir():
+        return skills, errors
+
+    single_skill = path / SKILL_FILE_NAME
+    if single_skill.exists():
+        skill, error = _load_skill_file(single_skill, location)
+        if skill:
+            skills.append(skill)
+        elif error:
+            errors.append(error)
+        return skills, errors
+
+    for entry in sorted(path.iterdir()):
+        try:
+            if not entry.is_dir() and not entry.is_symlink():
+                continue
+        except OSError:
+            continue
+
+        candidate = entry / SKILL_FILE_NAME
+        if not candidate.exists():
+            continue
+        skill, error = _load_skill_file(candidate, location)
+        if skill:
+            skills.append(skill)
+        elif error:
+            errors.append(error)
+    return skills, errors
+
+
+def skill_directories(
+    project_path: Optional[Path] = None, home: Optional[Path] = None
+) -> List[Tuple[Path, SkillLocation]]:
+    """Return the standard skill directories for user and project scopes."""
+    home_dir = (home or Path.home()).expanduser()
+    project_dir = (project_path or Path.cwd()).resolve()
+    return [
+        (home_dir / ".ripperdoc" / SKILL_DIR_NAME, SkillLocation.USER),
+        (project_dir / ".ripperdoc" / SKILL_DIR_NAME, SkillLocation.PROJECT),
+    ]
+
+
+def load_all_skills(
+    project_path: Optional[Path] = None, home: Optional[Path] = None
+) -> SkillLoadResult:
+    """Load skills from user and project directories.
+
+    Project skills override user skills with the same name.
+    """
+    skills_by_name: Dict[str, SkillDefinition] = {}
+    errors: List[SkillLoadError] = []
+
+    # Load user first so project overrides take precedence.
+    for directory, location in skill_directories(project_path=project_path, home=home):
+        loaded, dir_errors = _load_skill_dir(directory, location)
+        errors.extend(dir_errors)
+        for skill in loaded:
+            if skill.name in skills_by_name:
+                logger.debug(
+                    "[skills] Overriding skill",
+                    extra={
+                        "skill_name": skill.name,
+                        "previous_location": str(skills_by_name[skill.name].location),
+                        "new_location": str(location),
+                    },
+                )
+            skills_by_name[skill.name] = skill
+    return SkillLoadResult(skills=list(skills_by_name.values()), errors=errors)
+
+
+def find_skill(
+    skill_name: str, project_path: Optional[Path] = None, home: Optional[Path] = None
+) -> Optional[SkillDefinition]:
+    """Find a skill by name (case-sensitive match)."""
+    normalized = skill_name.strip().lstrip("/")
+    if not normalized:
+        return None
+    result = load_all_skills(project_path=project_path, home=home)
+    return next((skill for skill in result.skills if skill.name == normalized), None)
+
+
+def build_skill_summary(skills: Sequence[SkillDefinition]) -> str:
+    """Render a concise instruction block listing available skills."""
+    if not skills:
+        return (
+            "# Skills\n"
+            "No skills detected. Add SKILL.md under ~/.ripperdoc/skills or ./.ripperdoc/skills "
+            "to extend capabilities, then load them with the Skill tool when relevant."
+        )
+    lines = [
+        "# Skills",
+        "Skills extend your capabilities with reusable instructions stored in SKILL.md files.",
+        'Call the Skill tool with {"skill": "<name>"} to load a skill when it matches the user request.',
+        "Available skills:",
+    ]
+    for skill in skills:
+        location = f" ({skill.location.value})" if skill.location else ""
+        lines.append(f"- {skill.name}{location}: {skill.description}")
+    return "\n".join(lines)
+
+
+__all__ = [
+    "SkillDefinition",
+    "SkillLoadError",
+    "SkillLoadResult",
+    "SkillLocation",
+    "SKILL_DIR_NAME",
+    "SKILL_FILE_NAME",
+    "load_all_skills",
+    "find_skill",
+    "build_skill_summary",
+    "skill_directories",
+]

ripperdoc/core/system_prompt.py

@@ -8,7 +8,19 @@ from pathlib import Path
 from textwrap import dedent
 from typing import Any, Dict, Iterable, List, Optional
 
-from ripperdoc.core.agents import clear_agent_cache, load_agent_definitions, summarize_agent
+from ripperdoc.core.agents import (
+    ASK_USER_QUESTION_TOOL_NAME,
+    BASH_TOOL_NAME,
+    FILE_EDIT_TOOL_NAME,
+    FILE_WRITE_TOOL_NAME,
+    TASK_TOOL_NAME,
+    TODO_WRITE_TOOL_NAME,
+    TOOL_SEARCH_TOOL_NAME,
+    VIEW_TOOL_NAME,
+    clear_agent_cache,
+    load_agent_definitions,
+    summarize_agent,
+)
 from ripperdoc.core.tool import Tool
 from ripperdoc.utils.log import get_logger
 
@@ -20,7 +32,7 @@ DEFENSIVE_SECURITY_GUIDELINE = (
     "IMPORTANT: Assist with defensive security tasks only. Refuse to create, modify, or improve code that may be used maliciously. "
     "Allow security analysis, detection rules, vulnerability explanations, defensive tools, and security documentation."
 )
-FEEDBACK_URL = "https://github.com/jstzwj/Ripperdoc/issues"
+FEEDBACK_URL = "https://github.com/quantmew/Ripperdoc/issues"
 
 
 def _detect_git_repo(cwd: Path) -> bool:
@@ -34,8 +46,12 @@ def _detect_git_repo(cwd: Path) -> bool:
             check=False,
         )
         return result.returncode == 0 and result.stdout.strip().lower() == "true"
-    except Exception:
-        logger.exception("[system_prompt] Failed to detect git repository", extra={"cwd": str(cwd)})
+    except (OSError, subprocess.SubprocessError) as exc:
+        logger.warning(
+            "[system_prompt] Failed to detect git repository: %s: %s",
+            type(exc).__name__, exc,
+            extra={"cwd": str(cwd)},
+        )
         return False
 
 
@@ -174,10 +190,18 @@ def build_system_prompt(
 ) -> str:
     _ = user_prompt, context
     tool_names = {tool.name for tool in tools}
-    todo_tool_name = "TodoWrite"
+    todo_tool_name = TODO_WRITE_TOOL_NAME
     todo_available = todo_tool_name in tool_names
-    task_available = "Task" in tool_names
-    shell_tool_name = next((tool.name for tool in tools if tool.name.lower() == "bash"), "Bash")
+    task_available = TASK_TOOL_NAME in tool_names
+    ask_tool_name = ASK_USER_QUESTION_TOOL_NAME
+    ask_available = ask_tool_name in tool_names
+    view_tool_name = VIEW_TOOL_NAME
+    file_edit_tool_name = FILE_EDIT_TOOL_NAME
+    file_write_tool_name = FILE_WRITE_TOOL_NAME
+    shell_tool_name = next(
+        (tool.name for tool in tools if tool.name.lower() == BASH_TOOL_NAME.lower()),
+        BASH_TOOL_NAME,
+    )
 
     main_prompt = dedent(
         f"""\
@@ -190,61 +214,25 @@ def build_system_prompt(
         - /help: Get help with using {APP_NAME}
         - To give feedback, users should report the issue at {FEEDBACK_URL}
 
-        # Tone and style
-        You should be concise, direct, and to the point.
-        You MUST answer concisely with fewer than 4 lines (not including tool use or code generation), unless user asks for detail.
-        IMPORTANT: You should minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand, avoiding tangential information unless absolutely critical for completing the request. If you can answer in 1-3 sentences or a short paragraph, please do.
-        IMPORTANT: You should NOT answer with unnecessary preamble or postamble (such as explaining your code or summarizing your action), unless the user asks you to.
-        Do not add additional code explanation summary unless requested by the user. After working on a file, just stop, rather than providing an explanation of what you did.
-        Answer the user's question directly, without elaboration, explanation, or details. One word answers are best. Avoid introductions, conclusions, and explanations. You MUST avoid text before/after your response, such as "The answer is <answer>.", "Here is the content of the file..." or "Based on the information provided, the answer is..." or "Here is what I will do next...". Here are some examples to demonstrate appropriate verbosity:
-        <example>
-        user: 2 + 2
-        assistant: 4
-        </example>
-
-        <example>
-        user: what is 2+2?
-        assistant: 4
-        </example>
+        # Looking up your own documentation
+        When the user asks what {APP_NAME} can do, how to use it (hooks, slash commands, MCP, SDKs), or requests SDK code samples, use the {TASK_TOOL_NAME} tool with a documentation-focused subagent (for example, subagent_type="docs") if available to consult official docs before answering.
 
-        <example>
-        user: is 11 a prime number?
-        assistant: Yes
-        </example>
-
-        <example>
-        user: what command should I run to list files in the current directory?
-        assistant: ls
-        </example>
-
-        <example>
-        user: what command should I run to watch files in the current directory?
-        assistant: [use the ls tool to list the files in the current directory, then read docs/commands in the relevant file to find out how to watch files]
-        npm run dev
-        </example>
-
-        <example>
-        user: How many golf balls fit inside a jetta?
-        assistant: 150000
-        </example>
-
-        <example>
-        user: what files are in the directory src/?
-        assistant: [runs ls and sees foo.c, bar.c, baz.c]
-        user: which file contains the implementation of foo?
-        assistant: src/foo.c
-        </example>
-
-        <example>
-        user: write tests for new feature
-        assistant: [uses grep and glob search tools to find where similar tests are defined, uses concurrent read file tool use blocks in one tool call to read relevant files at the same time, uses edit file tool to write new tests]
-        </example>
+        # Tone and style
+        - Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+        - Your output will be displayed on a command line interface. Your responses should be short and concise. You can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+        - Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like {BASH_TOOL_NAME} or code comments as means to communicate with the user during the session.
+        - NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.
+
+        # Professional objectivity
+        Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if you honestly apply the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs. Avoid using over-the-top validation or excessive praise when responding to users such as "You're absolutely right" or similar phrases.
+
+        # Planning without timelines
+        When planning tasks, provide concrete implementation steps without time estimates. Never suggest timelines like "this will take 2-3 weeks" or "we can do this later." Focus on what needs to be done, not when. Break work into actionable steps and let users decide scheduling.
+      
+        # Explain Your Code: Bash Command Transparency
         When you run a non-trivial bash command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing (this is especially important when you are running a command that will make changes to the user's system).
         Remember that your output will be displayed on a command line interface. Your responses can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
-        Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like {shell_tool_name} or code comments as means to communicate with the user during the session.
         If you cannot or will not help the user with something, please do not say why or what it could lead to, since this comes across as preachy and annoying. Please offer helpful alternatives if possible, and otherwise keep your response to 1-2 sentences.
-        Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
-        IMPORTANT: Keep your responses short, since they will be displayed on a command line interface.  
 
         # Proactiveness
         You are allowed to be proactive, but only when the user asks you to do something. You should strive to strike a balance between:
@@ -260,7 +248,7 @@ def build_system_prompt(
         - Always follow security best practices. Never introduce code that exposes or logs secrets and keys. Never commit secrets or keys to the repository.
 
         # Code style
-        - IMPORTANT: DO NOT ADD ***ANY*** COMMENTS unless asked"""
+        - Only add comments when the logic is not self-evident and within code you changed. Do not add docstrings, comments, or type annotations to code you did not modify."""
     ).strip()
 
     if mcp_instructions:
@@ -318,6 +306,15 @@ def build_system_prompt(
             </example>"""
         ).strip()
 
+    ask_questions_section = ""
+    if ask_available:
+        ask_questions_section = dedent(
+            f"""\
+            # Asking questions as you work
+
+            You have access to the {ask_tool_name} tool to ask the user questions when you need clarification, want to validate assumptions, or need to make a decision you're unsure about. When presenting options or plans, do not include time estimates—focus on what each option involves."""
+        ).strip()
+
     hooks_section = dedent(
         """\
         Users may configure 'hooks', shell commands that execute in response to events like tool calls, in settings. Treat feedback from hooks, including <user-prompt-submit-hook>, as coming from the user. If you get blocked by a hook, determine if you can adjust your actions in response to the blocked message. If not, ask the user to check their hooks configuration."""
@@ -329,15 +326,26 @@ def build_system_prompt(
     ]
     if todo_available:
         doing_tasks_lines.append(f"- Use the {todo_tool_name} tool to plan the task if required")
+    if ask_available:
+        doing_tasks_lines.append(
+            f"- Use the {ask_tool_name} tool to ask questions, clarify, and gather information as needed."
+        )
     doing_tasks_lines.extend(
         [
+            "- NEVER propose changes to code you haven't read. If a user asks about or wants you to modify a file, read it first.",
             "- Use the available search tools to understand the codebase and the user's query. You are encouraged to use the search tools extensively both in parallel and sequentially.",
-            "- Implement the solution using all tools available to you",
+            "- When exploring the codebase beyond a needle query, prefer using the Task tool with an exploration subagent if available instead of running raw search commands directly.",
+            "- Implement the solution using all tools available to you.",
+            "- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities. If you notice that you wrote insecure code, immediately fix it.",
+            "- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.",
+            "  - Don't add features, refactor code, or make improvements beyond what was asked. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.",
+            "  - Don't add error handling, fallbacks, or validation for scenarios that can't happen. Validate only at system boundaries (user input, external APIs).",
+            "  - Don't create helpers, utilities, or abstractions for one-time operations. Avoid feature flags or backwards-compatibility shims when a direct change is sufficient. If something is unused, delete it completely.",
             "- Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the README or search codebase to determine the testing approach.",
             f"- VERY IMPORTANT: When you have completed a task, you MUST run the lint and typecheck commands (eg. npm run lint, npm run typecheck, ruff, etc.) with {shell_tool_name} if they were provided to you to ensure your code is correct. If you are unable to find the correct command, ask the user for the command to run and if they supply it, proactively suggest writing it to AGENTS.md so that you will know to run it next time.",
             "NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.",
-            "",
             "- Tool results and user messages may include <system-reminder> tags. <system-reminder> tags contain useful information and reminders. They are NOT part of the user's provided input or the tool result.",
+            "- The conversation has unlimited context through automatic summarization. Complete tasks fully; do not stop mid-task or claim context limits.",
         ]
     )
     doing_tasks_section = "\n".join(doing_tasks_lines)
@@ -345,7 +353,8 @@ def build_system_prompt(
     tool_usage_lines = [
         "# Tool usage policy",
         '- You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested, batch your tool calls together for optimal performance. When making multiple bash tool calls, you MUST send a single message with multiple tools calls to run the calls in parallel. For example, if you need to run "git status" and "git diff", send a single message with two tool calls to run the calls in parallel.',
-        "",
+        "- If the user asks to run tools in parallel and there are no dependencies, include multiple tool calls in a single message; sequence dependent calls instead of guessing values.",
+        f"- Use specialized tools instead of bash when possible: use {view_tool_name} for reading files, {file_edit_tool_name} for editing, and {file_write_tool_name} for creating files. Do not use bash echo or other command-line tools to communicate with the user; reply in text.",
         "You MUST answer concisely with fewer than 4 lines of text (not including tool use or code generation), unless user asks for detail.",
     ]
     if task_available:
@@ -353,7 +362,7 @@ def build_system_prompt(
             1,
             "- Use the Task tool with configured subagents when the task matches an agent's description. Always set subagent_type.",
         )
-    if "ToolSearch" in tool_names:
+    if TOOL_SEARCH_TOOL_NAME in tool_names:
         tool_usage_lines.insert(
             1,
             "- Use the ToolSearch tool to discover and activate deferred or MCP tools. Keep searches focused and load only 3-5 relevant tools.",
@@ -381,8 +390,11 @@ def build_system_prompt(
 
                     Provide detailed prompts so the agent can work autonomously and return a concise report."""
                 ).strip()
-        except Exception as exc:
-            logger.exception("Failed to load agent definitions", extra={"error": str(exc)})
+        except (OSError, ValueError, RuntimeError) as exc:
+            logger.warning(
+                "Failed to load agent definitions: %s: %s",
+                type(exc).__name__, exc,
+            )
             agent_section = (
                 "# Subagents\nTask tool available, but agent definitions could not be loaded."
             )
@@ -402,14 +414,14 @@ def build_system_prompt(
     sections: List[str] = [
         main_prompt,
         task_management_section,
+        ask_questions_section,
         hooks_section,
         doing_tasks_section,
         tool_usage_section,
         agent_section,
         build_environment_prompt(),
-        DEFENSIVE_SECURITY_GUIDELINE,
         always_use_todo,
-        build_commit_workflow_prompt(shell_tool_name, todo_tool_name, "Task"),
+        build_commit_workflow_prompt(shell_tool_name, todo_tool_name, TASK_TOOL_NAME),
         code_references,
     ]