Skip to content

RunCtx

Fields

cwd

The working directory the tool runs in.

  • Type: string
  • Access: read-only

mode

The active mode's name.

  • Type: string
  • Access: read-only

personality

The active personality's name.

  • Type: string
  • Access: read-only

session_id

Returns the ULID of the session this call runs in, an empty string for a session-less run. It differs from the session returned by ctx:spawn_agent, which is the session of the child.

  • Type: string
  • Access: read-only

spill_dir

A scratch directory for output too large to return inline, for the model to read back.

  • Type: string
  • Access: read-only

tool_options

The mode's per-tool options, as a Lua table keyed by tool name.

  • Type: any
  • Access: read-only

Methods

show

RunCtx:show(state)

Publish a display-state snapshot for the block to render from. state must be a plain serializable table; it becomes the block's current state and triggers a redraw.

Parameters

  • state: any

spawn_agent

RunCtx:spawn_agent(opts) -> SpawnHandle

Prepare a sub-agent to run opts.task under opts.personality, without running it yet. Any personality registered in the config may be delegated to. opts.mode picks the mode to run in (the first mode of the personality when omitted). opts.context seeds the conversation of the child, fresh (the default) for an empty one, fork to copy the current conversation in at the last settled turn, or resume to continue the existing session named by opts.session.

Returns a [SpawnHandle] for the prepared child. Raises on a setup failure. Wrap the call in pcall to catch it. The child runs headless.

Parameters

  • opts: any

Returns

title

RunCtx:title(title?)

Set a short label shown after the tool's name in the block header (like the path an edit shows), naming what the call is acting on. nil clears it.

Parameters

  • title: string (optional)

with_file_mutation

RunCtx:with_file_mutation(path, critical) -> any

Run critical (a function of no arguments) holding an exclusive lock on path, so a filesystem mutation it performs serializes against every other tool touching the same file. Returns whatever critical returns. The lock is held until critical settles even if the call is interrupted, so the next waiter never sees a half-written file.

Parameters

  • path: string
  • critical: (...any) -> ()

Returns

  • any