All Implemented Interfaces:
```
public final class CodingAgentFileSystem

                    
```
Full filesystem access layer for AI coding agents.
Unlike AgentFileSystem which is sandboxed to a specific directory and limited to a few file extensions, this class provides the agent with read/write access across the entire filesystem (subject to OS permissions), supports all file types, and includes directory operations, glob-based file search, and content diffing.
Operations outside the workspaceRoot log a warning but are permitted when allowExternalAccess is true. Destructive operations (delete, move outside workspace) require explicit opt-in.
```
val cfs = CodingAgentFileSystem(workspaceRoot = Path.of("/home/user/project"))
cfs.writeFile("src/main.kt", code)
val content = cfs.readFile("src/main.kt")
val results = cfs.glob("src/**/*.kt")
```

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`public class`	`CodingAgentFileSystem.Companion`

Field Summary

Fields
Modifier and Type	Field	Description
`public final static Long`	`MAX_READ_SIZE_BYTES`
`public final static Integer`	`MAX_GLOB_RESULTS`
`public final static Integer`	`MAX_LIST_DIR_DEPTH`
`public final static Integer`	`DEFAULT_MAX_OUTPUT_CHARS`
`private final Path`	`workspaceRoot`
`public final static CodingAgentFileSystem.Companion`	`Companion`

Constructor Summary

Constructors
Constructor	Description
`CodingAgentFileSystem(Path workspaceRoot, Boolean allowExternalAccess, Boolean allowDestructive, Set<String> searchExcludedDirs, Set<String> protectedFiles)`

Enum Constant Summary

Enum Constants
Enum Constant	Description

Method Summary

Modifier and Type	Method	Description
`final Path`	`getWorkspaceRoot()`
`final String`	`readFile(String path, Charset encoding)`	Read a text file.
`final String`	`readFileLines(String path, Integer startLine, Integer endLine, Integer maxChars)`	Read a file with surrounding context lines (like head/tail).
`final String`	`writeFile(String path, String content, Charset encoding, Boolean createSnapshot)`	Write content to a file.
`final String`	`appendFile(String path, String content)`	Append content to a file.
`final String`	`replaceInFile(String path, String oldStr, String newStr, Integer count)`	Replace all occurrences of a string in a file.
`final String`	`replaceRegexInFile(String path, String regex, String replacement, Integer count)`	Replace all matches of a regular expression in a file.
`final String`	`editLinesInFile(String path, Integer startLine, Integer endLine, String content)`	Replace a line range startLine..
`final String`	`insertAfterInFile(String path, String anchor, String content)`	Insert content after the line containing anchor (substring match on first hit).
`final String`	`revert(String path)`	Restore a file to its snapshot (the state before the first tracked write).
`final Boolean`	`exists(String path)`	Check if a path exists.
`final String`	`fileInfo(String path)`	Get file or directory information.
`final String`	`delete(String path, Boolean recursive)`	Delete a file or empty directory.
`final String`	`mkdir(String path)`	Create a directory (and parents if needed).
`final String`	`copy(String source, String dest)`	Copy a file or directory.
`final String`	`move(String source, String dest)`	Move/rename a file or directory.
`final String`	`listDir(String path, Integer maxDepth)`	List files in a directory (relative to workspace root).
`final String`	`glob(String pattern, Integer maxResults)`	Search for files matching a glob pattern.
`final String`	`grep(String pattern, String path, String filePattern, Boolean ignoreCase, Integer maxResults)`	Search file contents for a regex pattern (like grep -r).
`final Map<String, String>`	`collectTextFiles(String path)`	Collect all text files under path (recursively) as relative-path → content, skipping searchExcludedDirs, binary extensions, and files over MAX_READ_SIZE_BYTES.
`final String`	`diff(String path, String algorithm)`	Get a unified diff between the snapshot and current content of a file.
`final String`	`changeSummary(Duration maxAge)`	Get change summary since tracking started.
`final String`	`getWorkspaceRoot()`	Get the workspace root path.
`final String`	`resolvePathString(String path)`	Resolve a path against the workspace sandbox and return the absolute path string.
`final Map<String, Integer>`	`detectLanguages()`	Detect the programming languages used in the workspace.
`final String`	`protect(String path, Boolean on)`	Add (or remove) a session-level protection on a specific file.
`final String`	`protectedList()`	List the session-level dynamic protections.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CodingAgentFileSystem
```
CodingAgentFileSystem(Path workspaceRoot, Boolean allowExternalAccess, Boolean allowDestructive, Set<String> searchExcludedDirs, Set<String> protectedFiles)
```
- Method Detail
  - getWorkspaceRoot
```
 final Path getWorkspaceRoot()
```
  - readFile
```
 final String readFile(String path, Charset encoding)
```
    Read a text file. Path is resolved relative to workspaceRoot, or absolute when allowExternalAccess is true.
  - readFileLines
```
 final String readFileLines(String path, Integer startLine, Integer endLine, Integer maxChars)
```
    Read a file with surrounding context lines (like head/tail).
    The returned text is folded to DEFAULT_MAX_OUTPUT_CHARS to protect the agent's context budget; pass a larger maxChars when a full range is needed.
  - writeFile
```
 final String writeFile(String path, String content, Charset encoding, Boolean createSnapshot)
```
    Write content to a file. Creates parent directories if needed. Takes a snapshot before writing for potential revert.
  - appendFile
```
 final String appendFile(String path, String content)
```
    Append content to a file.
  - replaceInFile
```
 final String replaceInFile(String path, String oldStr, String newStr, Integer count)
```
    Replace all occurrences of a string in a file.
  - replaceRegexInFile
```
 final String replaceRegexInFile(String path, String regex, String replacement, Integer count)
```
    Replace all matches of a regular expression in a file.
    
    Parameters:
    
    regex - Java regex pattern; the whole match is replaced by replacement.
    
    count - max number of matches to replace; -1 = replace all
  - editLinesInFile
```
 final String editLinesInFile(String path, Integer startLine, Integer endLine, String content)
```
    Replace a line range startLine..endLine (1-based, inclusive) with content. Uses the snapshot BEFORE the edit as its diff baseline is captured on first write.
  - insertAfterInFile
```
 final String insertAfterInFile(String path, String anchor, String content)
```
    Insert content after the line containing anchor (substring match on first hit).
  - revert
```
 final String revert(String path)
```
    Restore a file to its snapshot (the state before the first tracked write). Fails if no snapshot exists — use changeSummary to see tracked files.
  - exists
```
 final Boolean exists(String path)
```
    Check if a path exists.
  - fileInfo
```
 final String fileInfo(String path)
```
    Get file or directory information.
  - delete
```
 final String delete(String path, Boolean recursive)
```
    Delete a file or empty directory.
    Hard protections (always active, independent of allowDestructive):
    the workspace root itself can never be deleted
    version-control directories (.git/.svn/.hg) can never be deleted recursively
  - mkdir
```
 final String mkdir(String path)
```
    Create a directory (and parents if needed).
  - copy
```
 final String copy(String source, String dest)
```
    Copy a file or directory.
  - move
```
 final String move(String source, String dest)
```
    Move/rename a file or directory.
  - listDir
```
 final String listDir(String path, Integer maxDepth)
```
    List files in a directory (relative to workspace root).
  - glob
```
 final String glob(String pattern, Integer maxResults)
```
    Search for files matching a glob pattern. Supports ** for recursive matching.
  - grep
```
 final String grep(String pattern, String path, String filePattern, Boolean ignoreCase, Integer maxResults)
```
    Search file contents for a regex pattern (like grep -r).
  - collectTextFiles
```
 final Map<String, String> collectTextFiles(String path)
```
    Collect all text files under path (recursively) as relative-path → content, skipping searchExcludedDirs, binary extensions, and files over MAX_READ_SIZE_BYTES. Returns an empty map when nothing readable is found or the path is not a directory.
    Used by the multi-file live-template extraction (coding.scaffoldFromExample with a directory path) and other whole-subtree operations.
  - diff
```
 final String diff(String path, String algorithm)
```
    Get a unified diff between the snapshot and current content of a file.
    
    Parameters:
    
    algorithm - "myers" (default, fastest, edit-distance optimal) or "patience" (anchors on unique lines — reads better for code moves and repeated boilerplate).
  - changeSummary
```
 final String changeSummary(Duration maxAge)
```
    Get change summary since tracking started.
    Change tracking lives on this filesystem instance. Long-lived shared instances (e.g. the session-less standalone coding shell) accumulate entries from every caller, so a maxAge window (default 24h) filters out stale noise from other callers/earlier sessions; hidden entries are counted and reported so agents know the listing is windowed. diff/revert still see snapshots of any age.
  - getWorkspaceRoot
```
 final String getWorkspaceRoot()
```
    Get the workspace root path.
  - resolvePathString
```
 final String resolvePathString(String path)
```
    Resolve a path against the workspace sandbox and return the absolute path string.
    Returns null when the path is blocked (external access without allowExternalAccess, or traversal outside workspaceRoot) — same policy as readFile/writeFile. Use this for tools that hand the path to third-party validators that do raw IO (e.g. ArtifactValidator.validatePlugin), so they cannot escape the sandbox.
  - detectLanguages
```
 final Map<String, Integer> detectLanguages()
```
    Detect the programming languages used in the workspace.
  - protect
```
 final String protect(String path, Boolean on)
```
    Add (or remove) a session-level protection on a specific file.
    
    Parameters:
    
    path - file path (resolved against the workspace root)
    
    on - true = protect (destructive ops blocked), false = unprotect
    
    Returns:
    
    confirmation message
  - protectedList
```
 final String protectedList()
```
    List the session-level dynamic protections.

Class CodingAgentFileSystem

Nested Class Summary

Field Summary

Constructor Summary

Enum Constant Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CodingAgentFileSystem

Method Detail

getWorkspaceRoot

readFile

readFileLines

writeFile

appendFile

replaceInFile

replaceRegexInFile

editLinesInFile

insertAfterInFile

revert

exists

fileInfo

delete

mkdir

copy

move

listDir

glob

grep

collectTextFiles

diff

changeSummary

getWorkspaceRoot

resolvePathString

detectLanguages

protect

protectedList