# hallucinate

`hallucinate` watches shell failures, suggests safer fixes for bad flags, and roasts the command that failed.

There are three modes:

1. `watch`
   Observes a workspace-local JSONL stream at `.hallucinate/stream.jsonl`.
2. `exec` / `bash`
   Wraps command execution, logs the failure, and appends mocking/helpful feedback to the stderr the agent actually sees.
3. `agent-bash` via `BASH_ENV`
   Lets non-interactive `bash` processes inherit the hook. This can log failures and append hallucinate feedback when the agent process inherited the environment.

## Install

```powershell
Set-Location E:\hallucinate
C:\Users\HP1\AppData\Local\Programs\Python\Python312\python.exe -m pip install -e .
```

## Fastest Human Workflow

Watcher terminal:

```powershell
Set-Location E:\your-workspace
hallucinate
```

Hooked shell terminal:

```powershell
Set-Location E:\your-workspace
hallucinate shell
```

That opens a PowerShell session already configured for the current workspace.

## Reliable Agent Workflow

If you want the agent to see hallucinate's feedback in the actual command output, wrap the command:

```powershell
Set-Location E:\your-workspace
hallucinate exec --actor agent bash -lc "fakecommand; ls /bad/path; git merge nonexistentbranch"
```

Or call the dedicated bash wrapper:

```powershell
Set-Location E:\your-workspace
hallucinate bash --actor agent -lc "fakecommand; ls /bad/path"
```

This is the reliable path for agents because `hallucinate` owns execution and can decorate stderr directly.

## Raw Agent Bash Workflow

If an agent launches plain `bash` processes and inherits your environment, use:

```powershell
Set-Location E:\your-workspace
Invoke-Expression (& hallucinate activate --shell agent-bash --actor agent)
```

This exports `BASH_ENV`, `PATH`, workspace metadata, and a local bash shim.

What this can do:

- log non-interactive bash failures
- append hallucinate feedback to failing bash stderr
- intercept `bash` if the agent resolves it from `PATH`

What this cannot do:

- intercept a bash process launched by an agent that did not inherit these environment variables
- override an agent that uses an execution layer completely outside your current process tree

## PATH Bash Shim

`hallucinate shell` and `hallucinate activate ...` now create a workspace-local shim at:

```text
.hallucinate/bin/bash
```

and prepend that directory to `PATH`.

If an agent resolves `bash` from `PATH`, it will hit the shim, which forwards to:

```text
hallucinate bash ...
```

Important limit:

- This only helps when the agent resolves `bash` through `PATH`.
- If the agent hardcodes an absolute bash binary such as `/usr/bin/bash`, a PATH shim cannot intercept it.
- Absolute-path bash can still be influenced by `BASH_ENV`, but only if the agent inherited that variable from the activated environment.

## Commands

```text
hallucinate
hallucinate shell --actor human|agent
hallucinate exec --actor human|agent <command ...>
hallucinate bash --actor human|agent <bash args ...>
hallucinate activate --shell powershell|bash|agent-bash
```

## What Gets Logged

Each event includes:

- timestamp
- actor (`human` or `agent`)
- cwd
- workspace root
- exit code
- command
- stderr

## Product Boundary

`watch` is observational.

`exec` and `bash` are intercepting wrappers.

If the goal is "show mocking/helpful feedback directly to the agent", use `exec` or `bash` when you can.

Use `agent-bash` only when the agent insists on launching raw `bash` but still inherits your environment.
