fix(bash): surface clearer install workflow guidance

Author: tjb-tech

src/openharness/permissions/checker.py

@@ -141,14 +141,18 @@ def evaluate(
             )
 
         # Default mode: require confirmation for mutating tools
+        bash_hint = _bash_permission_hint(command)
+        reason = (
+            "Mutating tools require user confirmation in default mode. "
+            "Approve the prompt when asked, or run /permissions full_auto "
+            "if you want to allow them for this session."
+        )
+        if bash_hint:
+            reason = f"{reason} {bash_hint}"
         return PermissionDecision(
             allowed=False,
             requires_confirmation=True,
-            reason=(
-                "Mutating tools require user confirmation in default mode. "
-                "Approve the prompt when asked, or run /permissions full_auto "
-                "if you want to allow them for this session."
-            ),
+            reason=reason,
         )
 
 
@@ -163,3 +167,34 @@ def _policy_match_paths(file_path: str) -> tuple[str, ...]:
     if not normalized:
         return (file_path,)
     return (normalized, normalized + "/")
+
+
+def _bash_permission_hint(command: str | None) -> str:
+    if not command:
+        return ""
+    lowered = command.lower()
+    install_markers = (
+        "npm install",
+        "pnpm install",
+        "yarn install",
+        "bun install",
+        "pip install",
+        "uv pip install",
+        "poetry install",
+        "cargo install",
+        "create-next-app",
+        "npm create ",
+        "pnpm create ",
+        "yarn create ",
+        "bun create ",
+        "npx create-",
+        "npm init ",
+        "pnpm init ",
+        "yarn init ",
+    )
+    if any(marker in lowered for marker in install_markers):
+        return (
+            "Package installation and scaffolding commands change the workspace, "
+            "so they will not run automatically in default mode."
+        )
+    return ""

src/openharness/tools/bash_tool.py

@@ -30,6 +30,13 @@ class BashTool(BaseTool):
 
     async def execute(self, arguments: BashToolInput, context: ToolExecutionContext) -> ToolResult:
         cwd = Path(arguments.cwd).expanduser() if arguments.cwd else context.cwd
+        preflight_error = _preflight_interactive_command(arguments.command)
+        if preflight_error is not None:
+            return ToolResult(
+                output=preflight_error,
+                is_error=True,
+                metadata={"interactive_required": True},
+            )
         process: asyncio.subprocess.Process | None = None
         try:
             process = await create_shell_subprocess(
@@ -134,6 +141,18 @@ def _format_timeout_output(output_buffer: bytearray, *, command: str, timeout_se
     return "\n".join(parts)
 
 
+def _preflight_interactive_command(command: str) -> str | None:
+    lowered_command = command.lower()
+    if not _looks_like_interactive_scaffold(lowered_command):
+        return None
+    return (
+        "This command appears to require interactive input before it can continue. "
+        "The bash tool is non-interactive, so it cannot answer installer/scaffold prompts live. "
+        "Prefer non-interactive flags (for example --yes, -y, --skip-install, --defaults, --non-interactive), "
+        "or run the scaffolding step once in an external terminal before asking the agent to continue."
+    )
+
+
 def _interactive_command_hint(*, command: str, output: str) -> str | None:
     lowered_command = command.lower()
     if _looks_like_interactive_scaffold(lowered_command) or _looks_like_prompt(output):

tests/test_permissions/test_checker.py

@@ -24,6 +24,18 @@ def test_default_mode_requires_confirmation_for_mutation():
     assert "/permissions full_auto" in decision.reason
 
 
+def test_default_mode_gives_package_install_hint_for_bash():
+    checker = PermissionChecker(PermissionSettings(mode=PermissionMode.DEFAULT))
+    decision = checker.evaluate(
+        "bash",
+        is_read_only=False,
+        command="npm init -y && npm install next react react-dom",
+    )
+    assert decision.allowed is False
+    assert decision.requires_confirmation is True
+    assert "Package installation and scaffolding commands change the workspace" in decision.reason
+
+
 def test_plan_mode_blocks_mutating_tools():
     checker = PermissionChecker(PermissionSettings(mode=PermissionMode.PLAN))
     decision = checker.evaluate("bash", is_read_only=False)

tests/test_tools/test_bash_tool.py

@@ -66,7 +66,7 @@ def kill(self):
 
 
 @pytest.mark.asyncio
-async def test_bash_tool_timeout_returns_partial_output_and_interactive_hint(monkeypatch, tmp_path: Path):
+async def test_bash_tool_preflight_short_circuits_interactive_scaffold_even_with_timeout_fixture(monkeypatch, tmp_path: Path):
     process = _FakeProcess(
         stdout=_FakeStdout(
             [
@@ -91,9 +91,24 @@ async def fake_create_shell_subprocess(*args, **kwargs):
     )
 
     assert result.is_error is True
-    assert "Command timed out after 1 seconds." in result.output
-    assert "This command appears to require interactive input." in result.output
-    assert result.metadata["timed_out"] is True
+    assert "This command appears to require interactive input before it can continue." in result.output
+    assert result.metadata["interactive_required"] is True
+
+
+@pytest.mark.asyncio
+async def test_bash_tool_preflights_interactive_scaffold_commands(tmp_path: Path):
+    result = await BashTool().execute(
+        BashToolInput(
+            command='npx create-next-app@latest coolblog --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"',
+            timeout_seconds=1,
+        ),
+        ToolExecutionContext(cwd=tmp_path),
+    )
+
+    assert result.is_error is True
+    assert result.metadata["interactive_required"] is True
+    assert "cannot answer installer/scaffold prompts live" in result.output
+    assert "non-interactive flags" in result.output
 
 
 @pytest.mark.asyncio