cleveragents/cleveragents-core

Fork 3

Proposal: update specification — TUI shell safety blocking behavior and persona schema fields #4954

New issue

Open

opened 2026-04-08 23:39:58 +00:00 by freemo · 2 comments

freemo commented

2026-04-08 23:39:58 +00:00

Owner

Specification Update Proposal

Triggered by: Proactive spec scan (cycle 1) comparing src/cleveragents/tui/ against spec section "TUI"

What Changed in the Implementation

The TUI shell safety subsystem and persona schema were implemented with richer behavior than the specification describes. This was discovered during the initial proactive scan comparing src/cleveragents/tui/shell_safety/ and src/cleveragents/tui/persona/ against the spec.

No specific merged PR triggered this — these are pre-existing implementation-vs-spec gaps discovered during the first proactive scan.

Spec Sections Needing Updates

1. Shell Danger Detection — Blocking Behavior (Section: "Shell Danger Detection")

Current spec text (line ~30062):

"Danger detection is controlled by the shell.warn_dangerous setting (default: true). The detection is advisory only — it never prevents command execution. The warning text reads: ⚠ Potentially destructive command detected."

What the implementation actually does (src/cleveragents/tui/input/shell_exec.py):

if looks_dangerous(command):
    confirmed = False
    if confirm_dangerous is not None:
        confirmed = confirm_dangerous(command)
    if not confirmed:
        return ShellResult(command=command, exit_code=1, stdout="", stderr="blocked dangerous shell command")

The implementation blocks dangerous commands by default (returning exit_code=1) unless a confirm_dangerous callback is provided and returns True. This is a better design than purely advisory — it prevents accidental execution of obviously destructive commands.

Proposed spec text:

"Danger detection is controlled by the shell.warn_dangerous setting (default: true). When a dangerous pattern is detected, the command is blocked by default — it returns a non-zero exit code with the message blocked dangerous shell command. A confirm_dangerous callback can be provided to allow the user to explicitly confirm execution. The warning text reads: ⚠ Potentially destructive command detected."

2. Shell Danger Levels — CRITICAL Level Missing (Section: "Shell Danger Detection" table)

Current spec table:

Pattern	Risk Level	Example
`rm -rf` / `rm -r`	High	`rm -rf /`
`chmod 777`	Medium	`chmod 777 /var/www`
`> /dev/sda` / `dd if=`	High	`dd if=/dev/zero of=/dev/sda`
`:(){ :\|:& };:` (fork bomb)	High	Fork bomb patterns
`mkfs` / `fdisk` / `parted`	High	Disk formatting tools
`kill -9` / `killall`	Medium	Process termination
`sudo` / `su`	Low	Privilege escalation (warning only)

What the implementation has (src/cleveragents/tui/shell_safety/danger_level.py, pattern_registry.py):

4 levels: CRITICAL (4), HIGH (3), MEDIUM (2), LOW (1)
rm -rf / and rm -rf with wildcards → CRITICAL (not just High)
Fork bomb → CRITICAL (not just High)
dd if=, mkfs, shred --remove → HIGH
chmod 777, sudo rm, wget|sh, curl|sh → MEDIUM
git push --force, chmod -R with permissive modes → LOW
Additional patterns: shred_device, git_push_force, chmod_recursive_permissive, curl_pipe_bash, wget_pipe_bash

Proposed spec update: Add CRITICAL level to the table and update the pattern list to match the implementation.

3. Persona Schema — Additional Fields (Section: "Persona System")

Current spec lists persona fields as:

Actor reference
Base arguments
Scoped projects
Scoped plans
Argument presets
Display metadata — short name, accent color, description

What the implementation has (src/cleveragents/tui/persona/schema.py):

class Persona(BaseModel):
    name: str
    description: str = ""
    icon: str = ""          # ← not in spec
    actor: str
    color: str | None = None
    base_arguments: dict[str, Any] = {}
    scoped_projects: list[str] = []
    scoped_plans: list[str] = []
    argument_presets: list[PersonaPreset] = []
    cycle_order: int = 0    # ← not in spec
    greeting: str = ""      # ← not in spec

Additional fields not in spec:

icon — emoji/icon character for persona display
cycle_order — explicit ordering in the tab-cycle list (0 = unordered)
greeting — custom greeting message shown when persona is activated

Proposed spec update: Add these fields to the persona description.

4. Persona Registry — State Persistence and File Locking (Section: "Persona System")

Current spec says only: "Personas are stored as YAML files in ~/.config/cleveragents/personas/"

What the implementation has (src/cleveragents/tui/persona/registry.py):

State file at ~/.config/cleveragents/tui-state.yaml (tracks last_persona)
File locking via fcntl.flock for concurrent access safety
Atomic writes via temp file + rename
CLEVERAGENTS_CONFIG_DIR env var override for config directory

Proposed spec update: Document the tui-state.yaml state file, the CLEVERAGENTS_CONFIG_DIR env var, and the atomic write/locking behavior.

5. CLEVERAGENTS_DISABLE_SHELL_MODE Environment Variable

Current spec: Not mentioned.

What the implementation has (src/cleveragents/tui/input/shell_exec.py):

if os.environ.get("CLEVERAGENTS_DISABLE_SHELL_MODE", "").strip() in {"1", "true"}:
    return ShellResult(command=command, exit_code=2, stdout="", stderr="shell mode is disabled")

Proposed spec update: Document CLEVERAGENTS_DISABLE_SHELL_MODE in the environment variables / configuration section.

Rationale

All of these are cases where the implementation is better than the spec:

Blocking dangerous commands (rather than just warning) is a safer default
The CRITICAL danger level correctly distinguishes system-destroying commands from merely risky ones
The additional persona fields (icon, cycle_order, greeting) enable richer UX
File locking and atomic writes prevent data corruption in concurrent scenarios
The env var provides an escape hatch for restricted environments

None of these represent incorrect deviations — they are genuine improvements discovered during implementation.

Scope

Spec sections affected:

## TUI → ### Reference and Command System → #### Shell Danger Detection
## TUI → ### Persona System
Environment variables / configuration reference section (if it exists)

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-updater

## Specification Update Proposal **Triggered by:** Proactive spec scan (cycle 1) comparing `src/cleveragents/tui/` against spec section "TUI" --- ## What Changed in the Implementation The TUI shell safety subsystem and persona schema were implemented with richer behavior than the specification describes. This was discovered during the initial proactive scan comparing `src/cleveragents/tui/shell_safety/` and `src/cleveragents/tui/persona/` against the spec. No specific merged PR triggered this — these are pre-existing implementation-vs-spec gaps discovered during the first proactive scan. --- ## Spec Sections Needing Updates ### 1. Shell Danger Detection — Blocking Behavior (Section: "Shell Danger Detection") **Current spec text (line ~30062):** > "Danger detection is controlled by the `shell.warn_dangerous` setting (default: `true`). The detection is advisory only — it **never prevents command execution**. The warning text reads: `⚠ Potentially destructive command detected`." **What the implementation actually does** (`src/cleveragents/tui/input/shell_exec.py`): ```python if looks_dangerous(command): confirmed = False if confirm_dangerous is not None: confirmed = confirm_dangerous(command) if not confirmed: return ShellResult(command=command, exit_code=1, stdout="", stderr="blocked dangerous shell command") ``` The implementation **blocks** dangerous commands by default (returning exit_code=1) unless a `confirm_dangerous` callback is provided and returns `True`. This is a better design than purely advisory — it prevents accidental execution of obviously destructive commands. **Proposed spec text:** > "Danger detection is controlled by the `shell.warn_dangerous` setting (default: `true`). When a dangerous pattern is detected, the command is **blocked by default** — it returns a non-zero exit code with the message `blocked dangerous shell command`. A `confirm_dangerous` callback can be provided to allow the user to explicitly confirm execution. The warning text reads: `⚠ Potentially destructive command detected`." --- ### 2. Shell Danger Levels — CRITICAL Level Missing (Section: "Shell Danger Detection" table) **Current spec table:** | Pattern | Risk Level | Example | |---------|-----------|---------| | `rm -rf` / `rm -r` | High | `rm -rf /` | | `chmod 777` | Medium | `chmod 777 /var/www` | | `> /dev/sda` / `dd if=` | High | `dd if=/dev/zero of=/dev/sda` | | `:(){ :\|:& };:` (fork bomb) | High | Fork bomb patterns | | `mkfs` / `fdisk` / `parted` | High | Disk formatting tools | | `kill -9` / `killall` | Medium | Process termination | | `sudo` / `su` | Low | Privilege escalation (warning only) | **What the implementation has** (`src/cleveragents/tui/shell_safety/danger_level.py`, `pattern_registry.py`): - 4 levels: **CRITICAL** (4), HIGH (3), MEDIUM (2), LOW (1) - `rm -rf /` and `rm -rf` with wildcards → **CRITICAL** (not just High) - Fork bomb → **CRITICAL** (not just High) - `dd if=`, `mkfs`, `shred --remove` → HIGH - `chmod 777`, `sudo rm`, `wget|sh`, `curl|sh` → MEDIUM - `git push --force`, `chmod -R` with permissive modes → LOW - Additional patterns: `shred_device`, `git_push_force`, `chmod_recursive_permissive`, `curl_pipe_bash`, `wget_pipe_bash` **Proposed spec update:** Add CRITICAL level to the table and update the pattern list to match the implementation. --- ### 3. Persona Schema — Additional Fields (Section: "Persona System") **Current spec** lists persona fields as: 1. Actor reference 2. Base arguments 3. Scoped projects 4. Scoped plans 5. Argument presets 6. Display metadata — short name, accent color, description **What the implementation has** (`src/cleveragents/tui/persona/schema.py`): ```python class Persona(BaseModel): name: str description: str = "" icon: str = "" # ← not in spec actor: str color: str | None = None base_arguments: dict[str, Any] = {} scoped_projects: list[str] = [] scoped_plans: list[str] = [] argument_presets: list[PersonaPreset] = [] cycle_order: int = 0 # ← not in spec greeting: str = "" # ← not in spec ``` Additional fields not in spec: - `icon` — emoji/icon character for persona display - `cycle_order` — explicit ordering in the tab-cycle list (0 = unordered) - `greeting` — custom greeting message shown when persona is activated **Proposed spec update:** Add these fields to the persona description. --- ### 4. Persona Registry — State Persistence and File Locking (Section: "Persona System") **Current spec** says only: "Personas are stored as YAML files in `~/.config/cleveragents/personas/`" **What the implementation has** (`src/cleveragents/tui/persona/registry.py`): - State file at `~/.config/cleveragents/tui-state.yaml` (tracks `last_persona`) - File locking via `fcntl.flock` for concurrent access safety - Atomic writes via temp file + rename - `CLEVERAGENTS_CONFIG_DIR` env var override for config directory **Proposed spec update:** Document the `tui-state.yaml` state file, the `CLEVERAGENTS_CONFIG_DIR` env var, and the atomic write/locking behavior. --- ### 5. CLEVERAGENTS_DISABLE_SHELL_MODE Environment Variable **Current spec:** Not mentioned. **What the implementation has** (`src/cleveragents/tui/input/shell_exec.py`): ```python if os.environ.get("CLEVERAGENTS_DISABLE_SHELL_MODE", "").strip() in {"1", "true"}: return ShellResult(command=command, exit_code=2, stdout="", stderr="shell mode is disabled") ``` **Proposed spec update:** Document `CLEVERAGENTS_DISABLE_SHELL_MODE` in the environment variables / configuration section. --- ## Rationale All of these are cases where the **implementation is better than the spec**: - Blocking dangerous commands (rather than just warning) is a safer default - The CRITICAL danger level correctly distinguishes system-destroying commands from merely risky ones - The additional persona fields (`icon`, `cycle_order`, `greeting`) enable richer UX - File locking and atomic writes prevent data corruption in concurrent scenarios - The env var provides an escape hatch for restricted environments None of these represent incorrect deviations — they are genuine improvements discovered during implementation. --- ## Scope Spec sections affected: - `## TUI` → `### Reference and Command System` → `#### Shell Danger Detection` - `## TUI` → `### Persona System` - Environment variables / configuration reference section (if it exists) --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

freemo added the

labels

2026-04-08 23:40:02 +00:00

freemo referenced this issue

2026-04-08 23:40:14 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4940

freemo added the

Needs Feedback

label

2026-04-08 23:42:09 +00:00

freemo referenced this issue

2026-04-08 23:42:39 +00:00

Proposal: update specification — TUI preset cycling key binding (ctrl+t vs ctrl+tab) and spec size restructure #4978

freemo commented

2026-04-08 23:43:02 +00:00

Author

Owner

This issue has the "Needs Feedback" label and is a proposal awaiting human review. I will not modify its state — a human must approve or reject it.

Summary of the proposal:
The spec-updater has identified that the TUI shell safety subsystem and persona schema were implemented with richer behavior than the specification describes. This is a proactive spec scan finding — the implementation is ahead of the spec and the spec needs to be updated to match.

Note: This is a spec update (implementation is correct, spec needs to catch up), unlike the other proposals which are implementation fixes.

To approve: Remove the "Needs Feedback" label and add "State/Verified", or comment with explicit approval. The spec-updater will then update the specification to match the implementation.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

This issue has the "Needs Feedback" label and is a proposal awaiting human review. I will not modify its state — a human must approve or reject it. **Summary of the proposal:** The spec-updater has identified that the TUI shell safety subsystem and persona schema were implemented with richer behavior than the specification describes. This is a proactive spec scan finding — the implementation is ahead of the spec and the spec needs to be updated to match. **Note:** This is a spec update (implementation is correct, spec needs to catch up), unlike the other proposals which are implementation fixes. **To approve:** Remove the "Needs Feedback" label and add "State/Verified", or comment with explicit approval. The spec-updater will then update the specification to match the implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison

HAL9000 commented

2026-04-09 00:20:40 +00:00

Owner

This is a proposal awaiting human review (needs feedback label). I will not modify its state — a human must approve or reject it.

Summary of proposal: Update spec to reflect 5 implementation improvements in the TUI subsystem:

Shell danger detection blocks commands (not just warns) — better safety default
Add CRITICAL danger level to the pattern table (fork bombs, rm -rf / with wildcards)
Add icon, cycle_order, greeting fields to Persona schema
Document tui-state.yaml state file, CLEVERAGENTS_CONFIG_DIR env var, and atomic write/locking behavior
Document CLEVERAGENTS_DISABLE_SHELL_MODE environment variable

All changes reflect cases where the implementation is better than the spec.

For human review: Please comment with approval or rejection, or remove the Needs Feedback label to proceed with implementation.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

This is a proposal awaiting human review (`needs feedback` label). I will not modify its state — a human must approve or reject it. **Summary of proposal:** Update spec to reflect 5 implementation improvements in the TUI subsystem: 1. Shell danger detection **blocks** commands (not just warns) — better safety default 2. Add CRITICAL danger level to the pattern table (fork bombs, `rm -rf /` with wildcards) 3. Add `icon`, `cycle_order`, `greeting` fields to Persona schema 4. Document `tui-state.yaml` state file, `CLEVERAGENTS_CONFIG_DIR` env var, and atomic write/locking behavior 5. Document `CLEVERAGENTS_DISABLE_SHELL_MODE` environment variable All changes reflect cases where the implementation is better than the spec. **For human review:** Please comment with approval or rejection, or remove the `Needs Feedback` label to proceed with implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison

HAL9000 referenced this issue

2026-04-09 00:59:59 +00:00

[AUTO-LIAISON] Human Liaison Status (Cycle 1) #4983

HAL9000 referenced this issue

2026-04-09 01:23:43 +00:00

[AUTO-LIAISON] Human Liaison Status (Cycle 10) #5131