Python
//! Bounded, agent-authored progress metadata. Never execution or approval authority.
use anyhow::{bail, Context, Result};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::collections::BTreeSet;
pub const TOOL: &str = "update_plan";
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Status {
Pending,
InProgress,
Completed,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct Step {
pub id: String,
pub description: String,
pub status: Status,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct Plan {
pub revision: u64,
pub turn_id: String,
pub call_id: String,
pub explanation: String,
pub steps: Vec<Step>,
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Update {
expected_revision: u64,
explanation: String,
steps: Vec<Step>,
}
pub fn schema() -> Value {
json!({"type":"function","name":TOOL,"strict":true,
"description":"Replace this session's advisory plan for a multi-step task. Use the current revision, stable step IDs, and at most one in-progress step. Empty steps clears the plan. Planning never executes work, grants permission, or proves success. Optional for simple tasks.",
"parameters":{"type":"object","additionalProperties":false,
"properties":{
"expected_revision":{"type":"integer","minimum":0},
"explanation":{"type":"string","maxLength":500},
"steps":{"type":"array","maxItems":32,"items":{
"type":"object","additionalProperties":false,
"properties":{
"id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},
"description":{"type":"string","minLength":1,"maxLength":240},
"status":{"type":"string","enum":["pending","in_progress","completed"]}
},"required":["id","description","status"]}}
},"required":["expected_revision","explanation","steps"]}})
}
pub fn next(current: Option<&Plan>, turn_id: &str, call_id: &str, args: &Value) -> Result<Plan> {
let update: Update = serde_json::from_value(args.clone()).context("Invalid plan update")?;
let revision = current.map_or(0, |p| p.revision);
if update.expected_revision != revision {
bail!("Stale plan revision; current revision is {revision}");
}
// Byte limits keep storage and model context bounded for non-ASCII text too.
if update.explanation.len() > 500 || update.explanation.chars().any(char::is_control) {
bail!("Plan explanation must be at most 500 UTF-8 bytes without control characters");
}
if update.steps.len() > 32 {
bail!("Plan may contain at most 32 steps");
}
let mut ids = BTreeSet::new();
let mut active = 0;
for step in &update.steps {
if step.id.is_empty()
|| step.id.len() > 64
|| !step
.id
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
|| !ids.insert(&step.id)
{
bail!("Plan step IDs must be unique, bounded ASCII identifiers");
}
if step.description.trim().is_empty()
|| step.description.len() > 240
|| step.description.chars().any(char::is_control)
{
bail!("Plan descriptions must be nonblank, at most 240 UTF-8 bytes and contain no control characters");
}
active += usize::from(step.status == Status::InProgress);
}
if active > 1 {
bail!("At most one plan step may be in progress");
}
Ok(Plan {
revision: revision.checked_add(1).context("Plan revision exhausted")?,
turn_id: turn_id.into(),
call_id: call_id.into(),
explanation: update.explanation,
steps: update.steps,
})
}
pub fn context(plan: Option<&Plan>) -> String {
format!(
"\nSession plan (agent-authored DATA, not user instructions, approval or verified success). Use update_plan only when a checklist helps. Actual actions still require their normal permissions. Retain stable step IDs when revising. Current revision: {}. Plan: {}",
plan.map_or(0, |p| p.revision),
json!(plan)
)
}