Workspace

Workspace gives an agent read/write/edit/search/shell access to a directory, with destructive operations gated behind human confirmation by default.

Workspace is a local-machine toolkit scoped to a single root directory. Reads (read, list, search) run silently; destructive operations (write, edit, move, delete, shell) require human confirmation by default, which AgentOS renders as approval prompts in the run timeline.

Example

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.tools.workspace import Workspace
4
5agent = Agent(
6    model=OpenAIResponses(id="gpt-5.4"),
7    tools=[
8        Workspace(
9            "/path/to/project",
10            allowed=["read", "list", "search"],
11            confirm=["write", "edit", "move", "delete", "shell"],
12        )
13    ],
14    markdown=True,
15)
16
17agent.print_response("Read README.md, then write a 2-line summary to NOTES.md.")

Permission Model

allowed and confirm are mutually exclusive partitions of short aliases:

In list	Behavior
`allowed`	Runs silently.
`confirm`	Requires user approval via HITL pause/resume.
neither	Not registered with the toolkit. The LLM never sees it.
both	Raises `ValueError`.

When both lists are None, reads auto-pass and writes require confirmation (the safe default). When only one is set, the other defaults to []. Use Workspace.ALL_TOOLS to register every tool.

Alias	Registered tool	What it does
`read`	`read_file`	Read a file (line-numbered).
`list`	`list_files`	List a directory (recursive option).
`search`	`search_content`	Recursive content grep.
`write`	`write_file`	Create or overwrite a file (atomic).
`edit`	`edit_file`	Replace a substring (with `replace_all`).
`move`	`move_file`	Move or rename a file.
`delete`	`delete_file`	Delete a file.
`shell`	`run_command`	Run a shell command in `root`.

Warning

This is a path-scoping boundary, not a process sandbox. Paths resolving outside root are rejected, but the agent can still read environment variables and make network calls via shell. For untrusted code execution, run the agent inside a real sandbox (container, VM, or Daytona).

Toolkit Params

Parameter	Type	Default	Description
`root`	`Optional[str\|Path]`	`cwd`	Directory all operations are scoped to.
`allowed`	`Optional[List[str]]`	`None`	Aliases that run silently.
`confirm`	`Optional[List[str]]`	`None`	Aliases that require confirmation.
`require_read_before_write`	`bool`	`False`	Block writes/edits/move/delete on existing files until read this session.
`max_file_lines`	`int`	`100000`	Maximum lines `read_file` will load.
`max_file_length`	`int`	`10000000`	Maximum file size (bytes) `read_file` will load.
`exclude_patterns`	`Optional[List[str]]`	noise dirs	Patterns skipped by `list_files`/`search_content`. Pass `[]` to disable.

list_files and search_content skip common noise directories (.venv, .git, __pycache__, node_modules, etc.) by default.

Confirmation Flow

With aliases in confirm, the run pauses when the agent calls a gated tool. Resolve the requirement and continue the run:

1run_response = agent.run("Delete the old logs in /tmp/project")
2
3while run_response.is_paused:
4    for requirement in run_response.active_requirements:
5        if requirement.needs_confirmation:
6            requirement.confirm()  # or requirement.reject()
7    run_response = agent.continue_run(
8        run_id=run_response.run_id,
9        requirements=run_response.requirements,
10    )

See Workspace with confirmation for the full pause/resume example, and User Confirmation for the HITL pattern.

Developer Resources

Tools source
Basic usage
With confirmation
WorkspaceContextProvider wraps this toolkit read-only as a context provider