# pi-ask-mode

A shareable [pi](https://shittycodingagent.ai) package that adds **ask mode**.

Ask mode is a **read-only investigative mode** for analysis, debugging, exploration, and answering questions without using file mutation tools or interactive UI prompt tools.

## What ask mode enables

When ask mode is on, pi uses these tools:

- `read`
- `bash`
- `grep`
- `find`
- `ls`
- `subagent` if it exists in the current pi environment

## What ask mode blocks

Ask mode blocks these tools:

- `edit`
- `write`
- `question`
- `questionnaire`
- `askUserQuestion` (if another extension registers it)

It also restricts `bash` to **read-only / investigative commands**.

Examples of allowed shell usage:

- `ls`, `tree`, `pwd`
- `cat`, `head`, `tail`, `file`, `stat`
- `grep`, `rg`, `find`, `fd`
- `git status`, `git log`, `git diff`, `git show`, `git rev-parse`
- `git branch --show-current`, `git branch --list`, `git remote -v`, `git remote show origin`
- `npm list`, `npm info`, `npm outdated`, `npm audit --json`
- `env`, `printenv`, `uname`, `whoami`, `ps`, `uptime`
- `jq`, `awk`, `sed -n`
- `help`, `man`, and CLI help/version commands like `foo --help`, `foo help`, `foo --version`
- broadly, arbitrary CLIs for read-only inspection like `gh pr view`, `terraform plan`, or `kubectl get ...`
- `curl` and `wget -O -` for read-only fetching

Examples of blocked shell usage:

- file mutation like `rm`, `mv`, `cp`, `mkdir`, `touch`
- editors like `vim`, `nano`, `code`
- package installs like `npm install`, `pnpm add`, `brew install`
- package mutation like `npm audit fix`
- git writes like `git add`, `git commit`, `git push`, `git branch feature-x`, `git remote add origin ...`
- common mutating CLI actions like `gh repo create`, `terraform apply`, `kubectl apply`, `docker run`
- output redirection like `>` or `>>`
- command substitution like `` `...` `` or `$(...)`
- privilege/system actions like `sudo`, `kill`, `shutdown`

## Install

### Global install

```bash
pi install /absolute/path/to/pi-ask-mode
```

When published, users can install it globally with:

```bash
pi install npm:pi-ask-mode
```

or:

```bash
pi install git:github.com/<owner>/pi-ask-mode
```

## Usage

### Slash command

```text
/ask
```

Toggle ask mode on or off.

You can also use:

```text
/ask on
/ask off
/ask status
```

### Start pi directly in ask mode

```bash
pi --ask
```

## Behavior

When ask mode is enabled:

- pi switches active tools to `read,bash,grep,find,ls` plus `subagent` when available
- `edit`, `write`, `question`, `questionnaire`, and `askUserQuestion` are blocked defensively at tool-call time
- `bash` is limited to read-only / investigative commands
- `subagent` is allowed only for read-only context gathering, inspection, search, analysis, and summarization
- subagent management is limited to read-only actions like `list` and `get`
- subagent worktrees and output-file writes are blocked
- the model is instructed to ask the user directly in normal chat instead of using UI prompt tools
- if pi starts with `--ask`, ask mode captures the current tool selection so `/ask off` can restore it later

## Plan mode compatibility

This package is designed to play reasonably well with plan-mode style extensions.

### Switching from plan mode to ask mode

If a compatible plan-mode extension stores state in either:

- `plan-mode`
- `pi-constell-plan-state`

then running:

```text
/ask
```

will:

- enable ask mode
- write a disabled plan-mode state entry
- reload the runtime so the other mode shuts off cleanly

This avoids plan-mode UI prompts continuing to appear while ask mode is active.

### Switching from ask mode to plan mode

Running:

```text
/plan
```

from a compatible plan-mode extension should switch tools away from ask mode. On the next prompt, `pi-ask-mode` detects that another mode has taken over and disables ask mode state.

## Testing

Run the bash safety tests with:

```bash
npm test
```

Suggested manual smoke test:

1. Launch pi with this package loaded.
2. Run `/ask on`, `/ask status`, and `/ask off`.
3. In ask mode, verify `git diff` is allowed and `git commit -m "test"` is blocked.
4. If `subagent` is available, verify a read-only task like `Analyze the auth flow and summarize the touched files` is allowed, while a mutating task like `Implement the fix` is blocked.
5. If you use a compatible `/plan` extension, switch between `/plan` and `/ask` once in each direction.

## Important note

This is **not a perfect sandbox**.

Even with a read-only bash allowlist, this package is only an extension-level policy layer. It is designed to keep the agent in an investigative, non-mutating workflow, but it does not replace OS-level sandboxing.

If you need stronger guarantees, run pi inside a sandbox, container, VM, or other restricted environment.