feat(shell): Add shell run summary policy and mute flag

.changelog/014.yaml

@@ -0,0 +1,42 @@
+name: ShellRunSummary
+ts: 2026-05-15 13:24:34.831384+00:00
+type: make_public
+details: created in settings.py
+full_path: settings.ShellRunSummary
+group: __ROOT__
+---
+name: AskShellSettings
+ts: 2026-05-15 13:24:35.322058+00:00
+type: additional_change
+auto_generated: true
+change_kind: optional_field_added
+details: 'added optional field ''shell_run_summary'' (default: <ShellRunSummary.ALL: ''all''>)'
+field_name: shell_run_summary
+group: __ROOT__
+---
+name: ShellConfig
+ts: 2026-05-15 13:24:35.322069+00:00
+type: additional_change
+auto_generated: true
+change_kind: optional_field_added
+details: 'added optional field ''mute_shell_summary'' (default: False)'
+field_name: mute_shell_summary
+group: shell
+---
+name: run
+ts: 2026-05-15 13:24:35.322077+00:00
+type: additional_change
+auto_generated: true
+change_kind: optional_param_added
+details: 'added optional param ''mute_shell_summary'' (default: None)'
+field_name: mute_shell_summary
+group: shell
+---
+name: run_and_wait
+ts: 2026-05-15 13:24:35.322079+00:00
+type: additional_change
+auto_generated: true
+change_kind: optional_param_added
+details: 'added optional param ''mute_shell_summary'' (default: None)'
+field_name: mute_shell_summary
+group: shell

.groups.yaml

@@ -5,6 +5,7 @@ groups:
   - settings
   owned_refs:
   - settings.AskShellSettings
+  - settings.ShellRunSummary
 - name: ask
   owned_modules:
   - _internal.interactive

ask_shell/__init__.py

@@ -5,6 +5,7 @@
 from ask_shell import shell_events
 from ask_shell import ask
 from ask_shell.settings import AskShellSettings
+from ask_shell.settings import ShellRunSummary
 
 VERSION = "0.6.0"
 __all__ = [
@@ -13,4 +14,5 @@
     "shell_events",
     "ask",
     "AskShellSettings",
+    "ShellRunSummary",
 ]

ask_shell/_internal/_run.py

@@ -484,6 +484,7 @@ def run(
     start_timeout: float | None = None,
     terminal_width: int | None = None,
     skip_interactive_check: bool | None = None,
+    mute_shell_summary: bool | None = None,
 ) -> ShellRun:
     config = _as_config(
         config,
@@ -510,6 +511,7 @@ def run(
         skip_os_env=skip_os_env,
         terminal_width=terminal_width,
         skip_interactive_check=skip_interactive_check,
+        mute_shell_summary=mute_shell_summary,
     )
     assert not config.user_input, (
         "run() does not support user_input (only 1 should be active at a time), use run_and_wait() instead"
@@ -549,6 +551,7 @@ def run_and_wait(
     user_input: bool | None = None,
     terminal_width: int | None = None,
     skip_interactive_check: bool | None = None,
+    mute_shell_summary: bool | None = None,
 ) -> ShellRun:
     config = _as_config(
         script,
@@ -576,6 +579,7 @@ def run_and_wait(
         terminal_width=terminal_width,
         skip_interactive_check=skip_interactive_check,
         skip_progress_output=skip_progress_output,
+        mute_shell_summary=mute_shell_summary,
     )
     run = ShellRun(config)
     future = _pool.submit(_execute_run, run)

ask_shell/_internal/models.py

@@ -172,6 +172,9 @@ class ShellConfig(Entity):
         default=False,
         description="Skip transitive std out/err output, useful for large outputs that are not needed in the logs when running parallel scripts",
     )
+    mute_shell_summary: bool = Field(
+        default=False, description="Skip shell summary logging useful when you want to ✅ or ❌ in the logs"
+    )
     terminal_width: int | None = 999
 
     # advanced settings

ask_shell/_internal/rich_progress.py

@@ -47,10 +47,16 @@ def log_task_done(
     error: BaseException | None = None,
     description_override: str | None = None,
     extra_parts: list[str] | None = None,
+    soft_failure: bool = False,
 ):
     exit_comji = "❌" if force_error or error is not None else "✅"
     description = description_override or task.description
-    log_call = logger.info if exit_comji == "✅" else logger.error
+    if exit_comji == "✅":
+        log_call = logger.info
+    elif soft_failure:
+        log_call = logger.warning
+    else:
+        log_call = logger.error
     message_parts = [f"{exit_comji} {description}"]
     if rich_task := task._rich_task:
         if finish_time := rich_task.finished_time:

ask_shell/_internal/rich_run_state.py

@@ -21,6 +21,7 @@
     ShellRunEventT,
 )
 from ask_shell._internal.rich_progress import ProgressManager, log_task_done, new_task
+from ask_shell.settings import ShellRunSummary
 
 
 def _deque_default() -> deque[str]:
@@ -144,11 +145,16 @@ def remove_run(self, run: ShellRun, error: BaseException | None = None) -> None:
             task.update(stderr=run_info.stderr_str)
         task.__exit__(None, None, None)
         run = run_info.run
+        if run.config.mute_shell_summary:
+            return
+        if run.config.settings.shell_run_summary == ShellRunSummary.ERRORS_ONLY and run.clean_complete:
+            return
         log_task_done(
             task,
             force_error=not run.clean_complete,
             description_override=f"'{run.config.shell_input}'",
             extra_parts=[
                 "" if run.current_attempt == 1 else f"attempt {run.current_attempt}",
             ],
+            soft_failure=run.config.allow_non_zero_exit and not run.clean_complete,
         )

ask_shell/_internal/rich_run_state_test.py

@@ -1,14 +1,18 @@
-import logging
+from unittest.mock import Mock, patch
+
+import pytest
 
 from ask_shell._internal.events import ShellRunAfter, ShellRunStdOutput
 from ask_shell._internal.models import (
     ShellConfig,
     ShellRun,
 )
 from ask_shell._internal.rich_live import get_live
+from ask_shell._internal.rich_progress import log_task_done
 from ask_shell._internal.rich_run_state import _RunState
+from ask_shell.settings import ShellRunSummary
 
-logger = logging.getLogger(__name__)
+_module = _RunState.__module__
 
 
 def test_run_with_output_is_logged_to_console(settings, capture_console, caplog):
@@ -79,3 +83,66 @@ def test_skip_progress_output(settings, capture_console):
     state.remove_run(run, error=Exception("Test error"))
     output = capture_console.end_capture()
     assert "..." in output  # Output is skipped
+
+
+@pytest.mark.parametrize(
+    ("summary", "exit_code", "expect_log"),
+    [
+        (ShellRunSummary.ERRORS_ONLY, 0, False),
+        (ShellRunSummary.ERRORS_ONLY, 1, True),
+        (ShellRunSummary.ALL, 0, True),
+    ],
+)
+@patch(f"{_module}.{log_task_done.__name__}")
+def test_remove_run_respects_shell_run_summary(mock_log_done, settings, summary, exit_code, expect_log):
+    cfg = ShellConfig(
+        shell_input='echo "x"',
+        settings=settings.model_copy(update={"shell_run_summary": summary}),
+    )
+    run = ShellRun(config=cfg)
+    proc = Mock(spec=["returncode"])
+    proc.returncode = exit_code
+    run.p_open = proc
+    state = _RunState()
+    state.add_run(run)
+    state.remove_run(run, error=None)
+    if expect_log:
+        mock_log_done.assert_called_once()
+    else:
+        mock_log_done.assert_not_called()
+
+
+@patch(f"{_module}.{log_task_done.__name__}")
+def test_remove_run_mute_shell_summary_skips_log(mock_log_done, settings):
+    cfg = ShellConfig(
+        shell_input='echo "x"',
+        settings=settings,
+        mute_shell_summary=True,
+    )
+    run = ShellRun(config=cfg)
+    proc = Mock(spec=["returncode"])
+    proc.returncode = 1
+    run.p_open = proc
+    state = _RunState()
+    state.add_run(run)
+    state.remove_run(run, error=None)
+    mock_log_done.assert_not_called()
+
+
+@patch(f"{_module}.{log_task_done.__name__}")
+def test_remove_run_allow_non_zero_exit_uses_soft_failure(mock_log_done, settings):
+    cfg = ShellConfig(
+        shell_input='echo "x"',
+        settings=settings,
+        allow_non_zero_exit=True,
+    )
+    run = ShellRun(config=cfg)
+    proc = Mock(spec=["returncode"])
+    proc.returncode = 1
+    run.p_open = proc
+    state = _RunState()
+    state.add_run(run)
+    state.remove_run(run, error=None)
+    mock_log_done.assert_called_once()
+    _, kwargs = mock_log_done.call_args
+    assert kwargs["soft_failure"]

ask_shell/conftest.py

@@ -79,7 +79,7 @@ def capture_console() -> Console:  # type: ignore
 
 
 def create_run_mocked_config(user_input: bool = False) -> ShellRun:
-    """avoid ShellConfig validation erro"""
+    mock_settings = AskShellSettings.for_testing(global_callback_strings=[], remove_os_secrets=False)
     return ShellRun(
         config=Mock(
             spec=ShellConfig,
@@ -88,5 +88,8 @@ def create_run_mocked_config(user_input: bool = False) -> ShellRun:
             print_prefix="Mocked Run",
             shell_input="echo 'Mocked Run Output'",
             skip_progress_output=False,
+            mute_shell_summary=False,
+            allow_non_zero_exit=False,
+            settings=mock_settings,
         )
     )

ask_shell/settings.py

@@ -1,6 +1,7 @@
 import logging
 import os
 from datetime import datetime, timedelta
+from enum import StrEnum
 from functools import cached_property, lru_cache
 from pathlib import Path
 from pydoc import locate
@@ -90,6 +91,11 @@ def as_upper(v: str) -> str:
 ]
 
 
+class ShellRunSummary(StrEnum):
+    ALL = "all"
+    ERRORS_ONLY = "errors_only"
+
+
 class AskShellSettings(StaticSettings):
     model_config = ConfigDict(populate_by_name=True)  # type: ignore
     log_level: LogLevelIgnoredCase = "UNSET"
@@ -136,6 +142,11 @@ class AskShellSettings(StaticSettings):
         description="Runs once If `run_logs_dir` is not set. Can be 'yesterday' or a date string like '2023-01-01'. Will clean all logs up until the specified date but not that date itself.",
         alias=f"{ENV_PREFIX}RUN_LOGS_CLEAN",
     )
+    ENV_NAME_SHELL_RUN_SUMMARY: ClassVar[str] = f"{ENV_PREFIX}SHELL_RUN_SUMMARY"
+    shell_run_summary: ShellRunSummary = Field(
+        default=ShellRunSummary.ALL,
+        alias=ENV_NAME_SHELL_RUN_SUMMARY,
+    )
 
     @model_validator(mode="after")
     def ensure_vars_set(self) -> Self:

docs/_root/askshellsettings.md

@@ -2,7 +2,7 @@
 
 <!-- === DO_NOT_EDIT: pkg-ext askshellsettings_def === -->
 ## class: AskShellSettings
-- [source](../../ask_shell/settings.py#L93)
+- [source](../../ask_shell/settings.py#L99)
 > **Since:** 0.3.0
 
 ```python
@@ -19,6 +19,7 @@ class AskShellSettings(StaticSettings):
     remove_os_secrets: bool = ...
     run_logs_dir: Path | None = None
     run_logs_clean: str = 'yesterday'
+    shell_run_summary: ShellRunSummary = <ShellRunSummary.ALL: 'all'>
 ```
 <!-- === OK_EDIT: pkg-ext askshellsettings_def === -->
 
@@ -69,6 +70,7 @@ class AskShellSettings(StaticSettings):
 
 | Version | Change |
 |---------|--------|
+| unreleased | added optional field 'shell_run_summary' (default: <ShellRunSummary.ALL: 'all'>) |
 | 0.6.0 | field 'thread_count' default: 50 -> 100 |
 | 0.3.2 | field 'run_logs_dir' default added: None |
 | 0.3.2 | field 'STATIC_DIR' default added: None |

docs/_root/index.md

@@ -5,4 +5,26 @@
 
 <!-- === DO_NOT_EDIT: pkg-ext symbols === -->
 - [AskShellSettings](./askshellsettings.md)
-<!-- === OK_EDIT: pkg-ext symbols === -->
+- [`ShellRunSummary`](#shellrunsummary_def)
+<!-- === OK_EDIT: pkg-ext symbols === -->
+<!-- === DO_NOT_EDIT: pkg-ext symbol_details_header === -->
+## Symbol Details
+<!-- === OK_EDIT: pkg-ext symbol_details_header === -->
+<!-- === DO_NOT_EDIT: pkg-ext shellrunsummary_def === -->
+<a id="shellrunsummary_def"></a>
+
+### class: `ShellRunSummary`
+- [source](../../ask_shell/settings.py#L94)
+> **Since:** unreleased
+
+```python
+class ShellRunSummary(StrEnum):
+    ...
+```
+
+### Changes
+
+| Version | Change |
+|---------|--------|
+| unreleased | Made public |
+<!-- === OK_EDIT: pkg-ext shellrunsummary_def === -->

docs/console/index.md

@@ -130,7 +130,7 @@ def log_to_live(*objects, sep: str = ' ', end: str = '\n', style: str | Style |
 <a id="new_task_def"></a>
 
 ### class: `new_task`
-- [source](../../ask_shell/_internal/rich_progress.py#L162)
+- [source](../../ask_shell/_internal/rich_progress.py#L168)
 > **Since:** 0.3.0
 
 ```python

docs/shell/index.md

@@ -27,7 +27,7 @@
 <a id="shellrun_def"></a>
 
 ### class: `ShellRun`
-- [source](../../ask_shell/_internal/models.py#L272)
+- [source](../../ask_shell/_internal/models.py#L275)
 > **Since:** 0.3.0
 
 ```python
@@ -120,7 +120,7 @@ def kill_all_runs(immediate: bool = False, reason: str = '', abort_timeout: floa
 <a id="run_error_def"></a>
 
 ### function: `run_error`
-- [source](../../ask_shell/_internal/_run.py#L589)
+- [source](../../ask_shell/_internal/_run.py#L593)
 > **Since:** 0.3.0
 
 ```python
@@ -156,7 +156,7 @@ def stop_runs_and_pool(reason: str = 'atexit', immediate: bool = False):
 <a id="wait_on_ok_errors_def"></a>
 
 ### function: `wait_on_ok_errors`
-- [source](../../ask_shell/_internal/_run.py#L596)
+- [source](../../ask_shell/_internal/_run.py#L600)
 > **Since:** 0.3.0
 
 ```python
@@ -174,7 +174,7 @@ def wait_on_ok_errors(*runs, timeout: float | None = None, skip_kill_timeouts: b
 <a id="abortretryerror_def"></a>
 
 ### exception: `AbortRetryError`
-- [source](../../ask_shell/_internal/models.py#L523)
+- [source](../../ask_shell/_internal/models.py#L526)
 - [Example: Stop retrying with a custom error by raising AbortRetryError from should_retry](../examples/shell/AbortRetryError.md)
 > **Since:** 0.5.0