changes — Tool Reference

Code change proposals. Create structured diffs that can be reviewed, applied, or rejected — useful for agent-driven code modifications that need human approval.

Aliases

Old tool names propose_change and review_changes still work as aliases.

Actions

propose

Create a new change proposal with file path, old content, and new content.

Parameters

Name	Type	Required	Description
action	string	Yes	`"propose"`
file_path	string	Yes	Path to the file being changed
old_content	string	Yes	The original content to be replaced
new_content	string	Yes	The replacement content
description	string	No	Human-readable description of the change
domain	string	No	Topic domain (e.g., `"frontend"`, `"api"`)
related_task_id	string	No	ID of a related task

Example request

{
  "name": "changes",
  "arguments": {
    "action": "propose",
    "file_path": "src/utils/format.ts",
    "old_content": "function formatDate(d: Date) {\n  return d.toISOString();\n}",
    "new_content": "function formatDate(d: Date, locale = 'en-US') {\n  return d.toLocaleDateString(locale, { year: 'numeric', month: 'short', day: 'numeric' });\n}",
    "description": "Add locale support to formatDate with human-readable default",
    "domain": "frontend"
  }
}

Example response

{
  "success": true,
  "proposal_id": "prop_m4k8n",
  "file_path": "src/utils/format.ts",
  "domain": "frontend",
  "status": "pending",
  "expires_at": "2026-03-21T10:30:00.000Z",
  "message": "Change proposal created."
}

list

List change proposals, optionally filtered by status, domain, or related task.

Parameters

Name	Type	Required	Description
action	string	Yes	`"list"`
status	string	No	Filter by status: `"pending"`, `"applied"`, `"rejected"`, `"expired"`
domain	string	No	Filter by domain
related_task_id	string	No	Filter by related task ID
limit	number	No	Maximum number of proposals to return

Example request

{
  "name": "changes",
  "arguments": {
    "action": "list",
    "status": "pending",
    "limit": 10
  }
}

Example response

{
  "proposals": [
    {
      "id": "prop_m4k8n",
      "file_path": "src/utils/format.ts",
      "domain": "frontend",
      "description": "Add locale support to formatDate with human-readable default",
      "status": "pending",
      "proposed_by": "agent",
      "related_task_id": null,
      "expires_at": "2026-03-21T10:30:00.000Z",
      "created_at": "2026-03-14T10:30:00.000Z",
      "old_content": "function formatDate(d: Date) {\n  return d.toISOString();\n}",
      "new_content": "function formatDate(d: Date, locale = 'en-US') {\n  return d.toLocaleDateString(locale, { year: 'numeric', month: 'short', day: 'numeric' });\n}"
    }
  ],
  "count": 1
}

apply

Mark a pending proposal as applied. The actual file change should be performed separately (e.g., with an editor tool).

Parameters

Name	Type	Required	Description
action	string	Yes	`"apply"`
proposal_id	string	Yes	ID of the proposal to apply

Example request

{
  "name": "changes",
  "arguments": {
    "action": "apply",
    "proposal_id": "prop_m4k8n"
  }
}

Example response

{
  "success": true,
  "proposal_id": "prop_m4k8n",
  "file_path": "src/utils/format.ts",
  "status": "applied",
  "old_content": "function formatDate(d: Date) {\n  return d.toISOString();\n}",
  "new_content": "function formatDate(d: Date, locale = 'en-US') {\n  return d.toLocaleDateString(locale, { year: 'numeric', month: 'short', day: 'numeric' });\n}",
  "message": "Proposal marked as applied. Use the Edit tool to apply the actual change."
}

reject

Reject a pending proposal with an optional reason.

Parameters

Name	Type	Required	Description
action	string	Yes	`"reject"`
proposal_id	string	Yes	ID of the proposal to reject
reason	string	No	Explanation for the rejection

Example request

{
  "name": "changes",
  "arguments": {
    "action": "reject",
    "proposal_id": "prop_m4k8n",
    "reason": "The locale parameter should use Intl.DateTimeFormat instead for better browser support"
  }
}

Example response

{
  "success": true,
  "proposal_id": "prop_m4k8n",
  "file_path": "src/utils/format.ts",
  "status": "rejected",
  "rejection_reason": "The locale parameter should use Intl.DateTimeFormat instead for better browser support",
  "message": "Proposal rejected."
}

Proposal lifecycle

Proposals follow a simple state machine:

pending → applied
pending → rejected
pending → expired (automatic, after 7 days)

Only proposals in pending status can be applied or rejected. Expired proposals remain in history and can be listed with status: "expired".