propose_file_access — Lock Files Before Editing

propose_file_access is the entry point to Axis’s file-locking protocol. Before any agent edits a file, it must call this tool to register its intent and claim the file as its own. If the file is free, the lock is GRANTED and a content hash is fingerprinted for tamper detection. If another agent already holds the lock, the response is REQUIRES_ORCHESTRATION — not a generic “denied”, but a structured message that names the locking agent, states their intent, and tells you exactly what to do next.

NEVER edit a file without locking it first. Locks are advisory — another process could still write the file — but the lock record is your coordination contract with other agents.

Parameters

filePath

string

required

Path to the file to lock, relative to the repo root or absolute. Must point to a file — directories and paths outside the repo root are rejected with REJECTED.

filePaths

string[]

Lock multiple files in a single all-or-nothing batch call. If any file in the array is already locked by another agent, the entire batch is rejected and any locks acquired earlier in the same batch are automatically released. Use this for edits that must span several files atomically.

agentId

string

Identifier for the agent requesting the lock. Appears in denial messages shown to other agents, so use a recognisable name (e.g. "dana-claude-code").

intent

string

required

A plain-language description of what you will do with the file. This text surfaces directly in REQUIRES_ORCHESTRATION messages seen by other agents, so be specific — say what you are doing, not just “editing file”.

projectName

string

The Axis project to scope the lock to. Defaults to the auto-detected project derived from the nearest .git or package.json, or from a committed .axis/axis.json.

Return values

Status	Meaning
`GRANTED`	Lock recorded. The file’s current content is hashed and stored for tamper detection. Proceed with your edits; prefer `guarded_write` to write the result.
`REQUIRES_ORCHESTRATION`	The file is already locked by another agent. The response includes the locking agent’s ID, their intent, when the lock was acquired, when it auto-expires, and suggested next steps.
`REJECTED`	The path is invalid — a directory, a path outside the repo root, or otherwise not a lockable file.

REQUIRES_ORCHESTRATION message format

When a file is locked, the denial message is structured to be immediately actionable:

File 'src/auth.ts' is locked by 'dana-claude-code' for:
"refactor auth to issue JWTs instead of session cookies".
Pick a different file or job, or coordinate via update_shared_context.
The lock auto-expires after 30 min; use force_unlock only if 'dana-claude-code' has crashed.

The message includes:

Locking agent ID — who holds the file
Intent — what they are doing with it
Time acquired — when the lock was granted
Expiry time — when the lock auto-expires (30 minutes from grant)
Suggested actions — what to do instead of forcing through

Batch locking

Pass filePaths (an array) instead of a single filePath to lock multiple files in one round-trip. The batch is all-or-nothing: if any file in the array is locked by another agent, every lock acquired earlier in the same call is immediately released, and the response identifies which file caused the failure.

{
  "filePaths": ["src/auth.ts", "src/session.ts", "tests/auth.test.ts"],
  "agentId": "dana-claude-code",
  "intent": "Refactor auth layer to issue JWTs instead of session cookies"
}

A failed batch response looks like:

{
  "status": "REQUIRES_ORCHESTRATION",
  "failedOn": "src/session.ts",
  "message": "Batch lock failed on 'src/session.ts' — File 'src/session.ts' is locked by 'sam-cursor' for: \"migrate session store to Redis\". All-or-nothing: 1 lock(s) acquired earlier in this batch were released."
}

Companion tools

`verify_file_lock(agentId, filePath)`

A tamper check to run immediately before writing, when not using guarded_write. Axis recorded a content hash when the lock was granted; verify_file_lock re-hashes the file on disk and compares the two.

Return status	Meaning
`CLEAN`	File is unchanged since the lock was granted. Safe to overwrite.
`CONFLICT`	File changed since the lock was granted — another process wrote it. Re-read the file and reconcile your changes before writing.
`UNKNOWN`	No fingerprint was recorded (remote-backed lock without hash storage). Integrity cannot be verified.

guarded_write is the preferred alternative to calling verify_file_lock yourself. Because guarded_write performs the check and the write atomically, there is no race window between the two steps. Use verify_file_lock only when you must write through your own editor instead.

`release_file_access(filePath, reason?)`

Releases a lock you hold before calling complete_job. Use this when you finish with a file but your job is still in progress — freeing the lock early lets other agents proceed without waiting for your job to close.

{
  "filePath": "src/auth.ts",
  "reason": "Done with auth changes; moving on to tests"
}

complete_job releases all locks associated with the job automatically, so release_file_access is only needed for early, mid-job releases.

Best practices

Write a specific intent

Describe what you are doing, not just that you are editing. “Refactor auth to issue JWTs” is useful to blocked agents; “editing file” is not.

On REQUIRES_ORCHESTRATION: move on

Pick a different file or job. Never force the write — the lock holder is actively working on that file and a clobber will produce a real conflict.

Prefer guarded_write

Use guarded_write over the manual verify_file_lock → write pattern. It is atomic and eliminates the race window between the check and the write.

On CONFLICT: reconcile first

If verify_file_lock returns CONFLICT, re-read the file from disk and merge your changes before writing. Do not clobber the concurrent edit.

Example flow

Lock the file

{
  "tool": "propose_file_access",
  "filePath": "src/auth.ts",
  "agentId": "dana-claude-code",
  "intent": "Refactor auth to issue JWTs instead of session cookies"
}

{ "status": "GRANTED", "message": "Access granted for src/auth.ts" }

Make your changes in memory

Read the file, apply your edits, hold the result in memory. Do not write yet.

Write atomically through the lock

Use guarded_write to write only if you still hold the lock and the file is unchanged:

{
  "tool": "guarded_write",
  "agentId": "dana-claude-code",
  "filePath": "src/auth.ts",
  "content": "/* updated content */"
}

Complete the job

Call complete_job — this releases all file locks held by the job automatically.

Overview

Job Board

File Locking

Context & Search

Session & Account

propose_file_access — Lock Files Before Editing

Parameters

Return values

REQUIRES_ORCHESTRATION message format

Batch locking

Companion tools

`verify_file_lock(agentId, filePath)`

`release_file_access(filePath, reason?)`

Best practices

Write a specific intent

On REQUIRES_ORCHESTRATION: move on

Prefer guarded_write

On CONFLICT: reconcile first

Example flow

Build docs developers (and LLMs) love

Overview

Job Board

File Locking

Context & Search

Session & Account

Documentation Index

​Parameters

​Return values

​REQUIRES_ORCHESTRATION message format

​Batch locking

​Companion tools

​verify_file_lock(agentId, filePath)

​release_file_access(filePath, reason?)

​Best practices

Write a specific intent

On REQUIRES_ORCHESTRATION: move on

Prefer guarded_write

On CONFLICT: reconcile first

​Example flow

Build docs developers (and LLMs) love

Parameters

Return values

REQUIRES_ORCHESTRATION message format

Batch locking

Companion tools

`verify_file_lock(agentId, filePath)`

`release_file_access(filePath, reason?)`

Best practices

Example flow