shell

type BashTool ¶

type BashTool struct {
	// contains filtered or unexported fields
}

BashTool runs `/bin/sh -c <command>` with cmd.Dir set to the workdir captured at construction. One BashTool instance per agent — the toolset factory in internal/toolset/builtins.go calls NewBash(s.Workdir()) so each agent (including subagents spawned with isolation: "worktree") gets a tool that runs in its own directory. The bash process is fresh per call — shell env state does NOT persist between invocations.

When run_in_background=true and a BgTaskHost is installed on the agent's ToolState, Execute returns immediately with a task id and the command runs in a detached goroutine. Completion routes back to the agent's signal pump for idle-wake + drain-at-iter-start delivery (see Phase 16 design).

func NewBash(workdir string) *BashTool

func NewBashWithHost(workdir string, host BgTaskHost) *BashTool

func (t *BashTool) Description() string

func (t *BashTool) Execute(ctx context.Context, logger *slog.Logger, input json.RawMessage) (tools.Result, error)

func (t *BashTool) Name() string

func (t *BashTool) Schema() json.RawMessage

type BgTask ¶

type BgTask struct {
	BgTaskSnapshot
	// Cancel terminates the underlying process. nil for tasks that have
	// already exited.
	Cancel context.CancelFunc
}

BgTask is the live record the store mutates. Cancel is the func that kills the underlying process (set by Bash before it spawns the goroutine); calling it from task_stop transitions the snapshot to BgKilled when the process exits.

type BgTaskHost ¶

type BgTaskHost interface {
	// BgTaskStore returns the agent's background-task catalog. Never nil
	// for the host that the agent installs.
	BgTaskStore() *BgTaskStore
	// RootCtx returns the agent-lifetime context. Bg goroutines bind to
	// this rather than the per-call ctx so they survive the LLM call
	// that spawned them.
	RootCtx() context.Context
	// AgentID returns the spawning agent's id; copied into the snapshot
	// so the TUI can label rows by owner.
	AgentID() string
	// NotifyBgResult fires the agent's signal pump with this terminal
	// snapshot. Non-blocking; drops the signal if the chan buffer is
	// full (drain on next iter is the fallback).
	NotifyBgResult(snap BgTaskSnapshot)
}

BgTaskHost is the narrow surface every bg-tasks-aware tool (Bash with run_in_background, task_list, task_output, task_stop) reads. The host is implemented by *toolset.ToolState; the tool type-asserts on it at the start of Execute, same pattern the SKILL tool uses for its registry.

type BgTaskSnapshot ¶

type BgTaskSnapshot struct {
	ID          string
	Command     string
	Description string
	Status      BgTaskStatus
	ExitCode    int
	Output      string
	StartedAt   time.Time
	CompletedAt time.Time
	// AgentID is the agent that spawned this task — used by the TUI to
	// prefix subagent rows with their owner.
	AgentID string
}

BgTaskSnapshot is the public shape of one background task. The store hands out snapshots by value so observers don't race the goroutine holding the live struct.

type BgTaskStatus ¶

type BgTaskStatus string

BgTaskStatus is the lifecycle state of one detached Bash command.

Transitions:

BgRunning → BgCompleted   (process exited with code 0)
BgRunning → BgFailed      (process exited with non-zero code)
BgRunning → BgKilled      (task_stop or root ctx cancelled)

Terminal states are drained out of the store via DrainCompleted; their snapshots survive in the loop's iteration history as <system-reminder> blocks but are removed from the live store the moment they're folded in.

const (
	BgRunning   BgTaskStatus = "running"
	BgCompleted BgTaskStatus = "completed"
	BgFailed    BgTaskStatus = "failed"
	BgKilled    BgTaskStatus = "killed"
)

type BgTaskStore ¶

type BgTaskStore struct {
	*observable.Observable
	// contains filtered or unexported fields
}

BgTaskStore is the agent-owned catalog of background tasks. Embedded Observable fans every Change to subscribers (the TUI strip + the agent's KindStoreUpdate bridge). The store is safe for concurrent use — every mutator takes mu.

Lifecycle:

• Bash creates a snapshot via Add when spawning a bg task.
• The bg goroutine calls Complete / Fail when the process exits.
• task_stop calls Stop to flip Cancel and let the goroutine close out.
• The agent loop calls DrainCompleted at iter start to pull terminal entries into the conversation; drained entries are removed.

func NewBgTaskStore() *BgTaskStore

func (s *BgTaskStore) Add(snap BgTaskSnapshot, cancel context.CancelFunc)

func (s *BgTaskStore) Complete(id string, status BgTaskStatus, exitCode int, output string)

func (s *BgTaskStore) Domain() string

func (s *BgTaskStore) DrainCompleted() []BgTaskSnapshot

func (s *BgTaskStore) Get(id string) (BgTaskSnapshot, bool)

func (s *BgTaskStore) HasPending() bool

func (s *BgTaskStore) Snapshot() []BgTaskSnapshot

func (s *BgTaskStore) Stop(id string) (BgTaskSnapshot, bool)

type Classification ¶

type Classification struct {
	Risk       Risk
	IsCommonFS bool
	Matched    string
	Reason     string
}

Classification is the structured result of Classify.

Matched is the rule entry that triggered the verdict — for ReadOnly it's the binary name; for Dangerous it's the prefix that matched. Surfaced in the approval UI so the user knows *why* a prompt is showing.

IsCommonFS is an orthogonal flag (NOT a Risk level) set when the binary is one of {mkdir, touch, mv, cp, rmdir, ln, chmod, chown}. The gate uses it to auto-allow these in accept_edits mode while leaving them as regular RiskMutate calls in default mode (which still asks).

func Classify(command string) Classification

type GrepTool ¶

type GrepTool struct{}

func NewGrep() *GrepTool

func (t *GrepTool) Description() string

func (t *GrepTool) Execute(ctx context.Context, logger *slog.Logger, input json.RawMessage) (tools.Result, error)

func (t *GrepTool) Name() string

func (t *GrepTool) Schema() json.RawMessage

type Risk ¶

type Risk int

Risk classifies a shell command's safety from the gate's perspective.

The gate uses Risk to drive auto mode (RiskReadOnly → allow, RiskDangerous → ask with a hint, RiskMutate/RiskUnknown → ask without a hint). Default mode treats every risk level as "ask," so a misclassification can't bypass the user — at worst it shows a prompt that didn't need to appear.

Conservative bias: RiskUnknown is the catch-all. Anything we can't confidently rate as ReadOnly stays Unknown, which forces ask.

const (
	RiskUnknown   Risk = iota // safe fallback: forces ask in auto mode
	RiskReadOnly              // read-only allowlist binary with safe arguments
	RiskMutate                // a non-allowlisted, non-dangerous command
	RiskDangerous             // matches a known code-execution prefix
)

func (r Risk) String() string

type TaskListTool ¶

type TaskListTool struct {
	// contains filtered or unexported fields
}

TaskListTool enumerates every background task in the agent's BgTaskStore. Pure read; safe in any permission mode. Mirrors ref's TaskListTool.

func NewTaskList(host BgTaskHost) *TaskListTool

func (t *TaskListTool) Description() string

func (t *TaskListTool) Execute(_ context.Context, logger *slog.Logger, _ json.RawMessage) (tools.Result, error)

func (t *TaskListTool) Name() string

func (t *TaskListTool) Schema() json.RawMessage

type TaskOutputTool ¶

type TaskOutputTool struct {
	// contains filtered or unexported fields
}

TaskOutputTool returns the captured stdout+stderr of one task. Works for running and terminal tasks (running tasks return whatever has been buffered so far at snapshot time — Phase 16's store captures output only at Complete time, so running tasks read empty).

func NewTaskOutput(host BgTaskHost) *TaskOutputTool

func (t *TaskOutputTool) Description() string

func (t *TaskOutputTool) Execute(_ context.Context, logger *slog.Logger, raw json.RawMessage) (tools.Result, error)

func (t *TaskOutputTool) Name() string

func (t *TaskOutputTool) Schema() json.RawMessage

type TaskStopTool ¶

type TaskStopTool struct {
	// contains filtered or unexported fields
}

TaskStopTool terminates a running task. Idempotent on tasks that have already finished (returns a no-op message). The store's Stop method cancels the task's per-process ctx; the bg goroutine then calls Complete with Status=BgKilled and the agent's signal pump delivers the killed snapshot like any other terminal result.

func NewTaskStop(host BgTaskHost) *TaskStopTool

func (t *TaskStopTool) Description() string

func (t *TaskStopTool) Execute(_ context.Context, logger *slog.Logger, raw json.RawMessage) (tools.Result, error)

func (t *TaskStopTool) Name() string

func (t *TaskStopTool) Schema() json.RawMessage

type TreeTool ¶

type TreeTool struct{}

func (t *TreeTool) Description() string

func (t *TreeTool) Execute(_ context.Context, logger *slog.Logger, input json.RawMessage) (tools.Result, error)

func (t *TreeTool) Name() string

func (t *TreeTool) Schema() json.RawMessage