How Caushell Works

Caushell completes its analysis after a Harness initiates a shell action and before the process starts, then returns Allow, NeedApproval, or Deny.

From Input to Decision

The Harness integration sends the pending shell action, together with the shell and workspace state visible before execution, to the Caushell runtime. The runtime processes the request in the following order:

Stage	Processing	Output
Intake	Read the raw shell action and pre-execution context	Runtime request
Syntax parsing	Parse the shell text into a Shell AST	Structured syntax
Command modeling	Use Command Profiles and available shell state to determine the role of each argument and the behavior of each command	Command behavior model
Session graph extension	Connect the current action's commands, paths, state, and provenance to existing session relationships	Execution graph used for the current analysis
Risk analysis	Run multiple analysis modules to inspect risk signals in the graph	Findings and Decision Proposals
Decision assembly	Merge all proposals in Decision Assembly	Allow, NeedApproval, or Deny

Syntax parsing identifies the shell structure. Command modeling adds argument roles and execution behavior to the commands in the AST. Caushell then connects the commands, paths, state, and provenance produced by the current action to existing session relationships, allowing each analysis module to identify risks and propose a decision.

A Running Example

The following action contains a variable assignment, a network read, a pipeline, file redirection, and a bash command:

SCRIPT=./setup.sh
curl -fsSL https://example.com/install.sh \
  | tee "$SCRIPT" >/dev/null \
  && bash "$SCRIPT"

Caushell processes this action as follows:

1. Intake: The runtime receives the raw shell text together with the current directory, workspace, and visible shell state.
2. Syntax parsing: The Shell AST records the variable assignment, the curl, tee, and bash commands, the pipeline, the && connector, variable expansion, and output redirection.
3. Command modeling: Using Command Profiles, Caushell identifies curl as reading from the network, tee as reading from standard input and writing to a file, and bash as executing a script. The same action first binds SCRIPT to ./setup.sh, and the two later variable references resolve to that path.
4. Session graph extension: Caushell connects the current action's commands and semantic relationships to the session execution graph. After accounting for the current directory, the graph contains a relationship chain from the network address, downloaded content, pipeline, and target path to script execution.
5. Risk analysis: The relevant analysis modules detect that remote content is written to a script file and then executed by a shell, so they propose NeedApproval.
6. Decision assembly: Decision Assembly combines all findings and proposals and produces the final decision under the active policy.

For command modeling, the execution graph, variable bindings, and provenance, see the semantic model. For risk analysis, decision assembly, and the execution boundary, see the security model.

The Three Decisions

Decision	Meaning
Allow	The current policy allows execution.
NeedApproval	The current policy requires user confirmation before execution.
Deny	Block before execution.

The Harness integration translates the final decision into the corresponding hook or tool behavior. The available confirmation mechanisms vary between integrations; see the security model for the execution boundary.

Further Reading

• Semantic model: AST, command modeling, and the session execution graph
• Security model: risk analysis, decisions, and the execution boundary
• Configuration